.NET 帮助

.NET Core Polly（开发人员如何使用）

发布 2023年七月26日

波莉 Polly 是一个 .NET 弹性策略和瞬态故障处理库，允许开发人员表达重试策略、断路器、超时、隔板隔离策略和回退等弹性策略。Polly 以 ASP.NET Core 为目标，因此是 .NET Core 恢复能力的重要工具。Polly 采用线程安全方式，支持处理多个并发请求并成功响应。

本教程将提供有关瞬态故障处理 .NET 库 Polly 的更多详细信息，以及如何将其与以下应用程序一起使用 IronPDF 在 ASP.NET Core 应用程序中的应用。我们将深入研究 Polly 的每个方面，解释断路器模式的机制，讨论隔板隔离和超时，并展示如何以可控的线程安全方式处理特定异常或故障响应的失败服务。

Polly Policies

当应用程序尝试通过 HTTP 请求、数据库或其他外部资源连接网络服务时，经常会出现瞬时故障。这些故障，如网络故障、临时连接问题或超时，都是短暂的，通常会在很短时间后自行纠正。

Polly 通过应用不同的策略和表达式策略（如重试策略、高级断路器策略、超时策略、回退策略和隔板隔离策略）来管理这些瞬时故障。

重试政策

重试策略使用重试逻辑自动重试失败的并发请求。可以将其配置为永久重试或自动重试一定次数，还可以在重试之间等待设定的时间间隔或使用指数退让。

断路器

Circuit Breaker（断路器）策略可让系统支持取消令牌，以便在请求失败次数达到预设阈值后尝试特定服务。断路器策略类似于混沌工程或船舶关闭水密门以控制局部损坏：一个故障不会导致整艘船沉没。

超时政策

超时策略规定了特定 .NET 恢复代码的最长执行时间。超时策略有两种：乐观超时和悲观超时。

后备政策

回退策略用于在出现故障时提供替代值或行为。当出现故障的服务不应停止整个进程时，这种策略就非常有用。

隔板隔离

隔墙隔离用于限制对特定操作的并发请求数量，从而限制套接字耗尽的可能性，并保持受控的执行插槽数量。

缓存政策

缓存策略会缓存执行的成功响应，这样如果再次调用相同的执行，Polly 就能返回分布式缓存值。

政策概述

允许我们将多个策略包装在一起，使它们作为一个整体运行。

创建和配置政策

重试政策

重试策略很简单：当发生特定异常或故障时，Polly 会尝试再次执行底层委托。你可以定义重试的次数、重试之间的时间间隔，或者使用指数退避策略，否则就会永远重试。下面是一个示例：

//extension method
var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), 
    (exception, timeSpan, retryCount, context) =>
    {
        // This is the OnRetry delegate, where you can log or monitor failed requests
    });

//extension method
var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), 
    (exception, timeSpan, retryCount, context) =>
    {
        // This is the OnRetry delegate, where you can log or monitor failed requests
    });

'extension method
Dim retryPolicy = Policy.Handle(Of HttpRequestException)().WaitAndRetryAsync(3, Function(retryAttempt) TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), Sub(exception, timeSpan, retryCount, context)
End Sub)

VB C#

断路器政策

断路器策略可让 Polly 库监控故障，如果在指定时间内故障数量超过配置的阈值，电路就会 "断开"，并在指定时间内阻止进一步请求。这就是所谓的 "打开 "状态。这段时间过后，电路进入 "半开放 "状态，允许一些流量检查特定服务的健康状况。如果这些请求成功且没有发生故障，电路就会关闭，否则就会再次打开。

var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(5, TimeSpan.FromMinutes(1));

var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(5, TimeSpan.FromMinutes(1));

Dim circuitBreakerPolicy = Policy.Handle(Of HttpRequestException)().CircuitBreakerAsync(5, TimeSpan.FromMinutes(1))

VB C#

超时政策

超时策略可处理服务未在合理时间内响应的情况。Polly 提供两种超时类型：乐观和悲观。乐观超时在单独的线程上运行，并通过 "CancellationToken "取消底层操作。悲观超时会阻塞父线程，直到操作完成或超时时间结束。

var timeoutPolicy = Policy.TimeoutAsync(30); // Optimistic timeout of 30 seconds

var timeoutPolicy = Policy.TimeoutAsync(30); // Optimistic timeout of 30 seconds

IRON VB CONVERTER ERROR developers@ironsoftware.com

VB C#

隔板隔离

隔墙隔离用于限制针对特定服务的并发操作的数量。它提供了一种隔离故障并防止故障级联的方法。它还能限制我们对依赖关系的负载。

var bulkheadIsolationPolicy = Policy.BulkheadAsync(10, 20); // 10 concurrent actions, queue 20 additional actions

var bulkheadIsolationPolicy = Policy.BulkheadAsync(10, 20); // 10 concurrent actions, queue 20 additional actions

IRON VB CONVERTER ERROR developers@ironsoftware.com

VB C#

后备政策

当你需要提供默认行为或替代值时，回退策略非常有用。

var fallbackPolicy = Policy
    .Handle<Exception>()
    .FallbackAsync<FallbackResult>(FallbackResult.SomethingWentWrong);

var fallbackPolicy = Policy
    .Handle<Exception>()
    .FallbackAsync<FallbackResult>(FallbackResult.SomethingWentWrong);

Dim fallbackPolicy = Policy.Handle(Of Exception)().FallbackAsync(Of FallbackResult)(FallbackResult.SomethingWentWrong)

VB C#

包裹政策

使用 PolicyWrap 可以灵活组合多个策略：

var policyWrap = Policy.WrapAsync(fallbackPolicy, retryPolicy, circuitBreakerPolicy, timeoutPolicy, bulkheadIsolationPolicy);

var policyWrap = Policy.WrapAsync(fallbackPolicy, retryPolicy, circuitBreakerPolicy, timeoutPolicy, bulkheadIsolationPolicy);

IRON VB CONVERTER ERROR developers@ironsoftware.com

VB C#

开始

要开始使用 Polly 和 IronPDF，请确保已安装 Visual Studio，并在 .NET Core 中创建一个新的控制台应用程序项目。在 Visual Studio 中打开 NuGet 软件包管理器控制台，安装 Polly 和 IronPdf 软件包：

Install-Package Polly

Install-Package IronPdf

使用 Polly 和 IronPDF 将 URL 转换为 PDF

IronPDF 的一个突出特点是其 HTML 转 PDF 功能，确保布局和样式完好无损。该功能可将网页内容转化为 PDF，非常适合报告、发票和文档。它支持将 HTML 文件、URL 和 HTML 字符串转换为 PDF。

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

Imports IronPdf

Friend Class Program
	Shared Sub Main(ByVal args() As String)
		Dim renderer = New ChromePdfRenderer()

		' 1. Convert HTML String to PDF
		Dim htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>"
		Dim pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent)
		pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf")

		' 2. Convert HTML File to PDF
		Dim htmlFilePath = "path_to_your_html_file.html" ' Specify the path to your HTML file
		Dim pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath)
		pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf")

		' 3. Convert URL to PDF
		Dim url = "http://ironpdf.com" ' Specify the URL
		Dim pdfFromUrl = renderer.RenderUrlAsPdf(url)
		pdfFromUrl.SaveAs("URLToPDF.pdf")
	End Sub
End Class

VB C#

让我们以使用 Polly 和 IronPDF 为例，来了解一下将 URL 转换为 PDF.假设我们有一个网络服务，偶尔会因瞬时故障而失效，我们希望使用 Polly 来优雅地处理这些故障。

首先，让我们在 Program.cs 文件中导入必要的命名空间：

using System;
using System.Threading.Tasks;
using Polly;
using Polly.Wrap;
using IronPdf;

using System;
using System.Threading.Tasks;
using Polly;
using Polly.Wrap;
using IronPdf;

Imports System
Imports System.Threading.Tasks
Imports Polly
Imports Polly.Wrap
Imports IronPdf

VB C#

接下来，我们将定义策略。在本例中，我们将结合使用重试和断路器策略来处理故障：

var retryPolicy = Policy
    .Handle<Exception>()
    .WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(2 * i));

var circuitBreakerPolicy = Policy
    .Handle<Exception>()
    .CircuitBreakerAsync(2, TimeSpan.FromSeconds(30));

var retryPolicy = Policy
    .Handle<Exception>()
    .WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(2 * i));

var circuitBreakerPolicy = Policy
    .Handle<Exception>()
    .CircuitBreakerAsync(2, TimeSpan.FromSeconds(30));

Dim retryPolicy = Policy.Handle(Of Exception)().WaitAndRetryAsync(3, Function(i) TimeSpan.FromSeconds(2 * i))

Dim circuitBreakerPolicy = Policy.Handle(Of Exception)().CircuitBreakerAsync(2, TimeSpan.FromSeconds(30))

VB C#

重试策略 "将采用指数后退策略重试失败的请求，最多三次，重试间隔分别为 2 秒、4 秒和 8 秒。如果在 30 秒的时间间隔内连续发生两次失败，"断路策略 "将打开电路。

现在，让我们定义 IronPDF 代码，将 URL 转换为 PDF：

var htmlToPdf = new ChromePdfRenderer();
var pdfBytes = await retryPolicy
    .WrapAsync(circuitBreakerPolicy)
    .ExecuteAsync(() =>
    {
        Console.WriteLine("Attempting to convert URL to PDF...");
// var result
        var result = htmlToPdf.RenderUrlAsPdfAsync("https://example.com");
        Console.WriteLine("Conversion successful!");
        return result;
    });

pdfBytes.SaveAs("output.pdf");

var htmlToPdf = new ChromePdfRenderer();
var pdfBytes = await retryPolicy
    .WrapAsync(circuitBreakerPolicy)
    .ExecuteAsync(() =>
    {
        Console.WriteLine("Attempting to convert URL to PDF...");
// var result
        var result = htmlToPdf.RenderUrlAsPdfAsync("https://example.com");
        Console.WriteLine("Conversion successful!");
        return result;
    });

pdfBytes.SaveAs("output.pdf");

Dim htmlToPdf = New ChromePdfRenderer()
Dim pdfBytes = Await retryPolicy.WrapAsync(circuitBreakerPolicy).ExecuteAsync(Function()
		Console.WriteLine("Attempting to convert URL to PDF...")
' var result
		Dim result = htmlToPdf.RenderUrlAsPdfAsync("https://example.com")
		Console.WriteLine("Conversion successful!")
		Return result
End Function)

pdfBytes.SaveAs("output.pdf")

VB C#

在上述示例代码中，我们使用 WrapAsync 方法封装了 retryPolicy 和 circuitBreakerPolicy 。这样，我们就可以按顺序对新请求应用多个策略。ExecuteAsync方法会执行所提供的委托，在上述代码中就是 IronPDF 的RenderUrlAsPdfAsync` 方法。

通过应用 Polly 策略，我们可以确保代码能够抵御瞬时故障。如果请求失败，Polly 会根据重试策略自动重试。如果连续失败的次数超过了预先配置的阈值，断路器策略就会打开电路，在指定的时间内阻止进一步的请求。

Polly Policies 的测试用例

为了测试 Polly 策略的有效性，我们来模拟一些失败的请求。将 URL 修改为一个不存在的端点，然后添加一些测试用例：

var testUrls = new []
{
                "https://ironpdf.com",
                "https://notexistingdomain.com/",
                "http://httpbin.org/delay/120"
};

foreach (var url in testUrls)
{
    try
    {
        var pdfBytes = await retryPolicy
            .WrapAsync(circuitBreakerPolicy)
            .ExecuteAsync(() => htmlToPdf.RenderUrlAsPdfAsync(url));

        pdfBytes.SaveAs($"{Guid.NewGuid()}.pdf");
        Console.WriteLine($"Successfully converted {url} to PDF.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to convert {url} to PDF: {ex.Message}");
    }
}

var testUrls = new []
{
                "https://ironpdf.com",
                "https://notexistingdomain.com/",
                "http://httpbin.org/delay/120"
};

foreach (var url in testUrls)
{
    try
    {
        var pdfBytes = await retryPolicy
            .WrapAsync(circuitBreakerPolicy)
            .ExecuteAsync(() => htmlToPdf.RenderUrlAsPdfAsync(url));

        pdfBytes.SaveAs($"{Guid.NewGuid()}.pdf");
        Console.WriteLine($"Successfully converted {url} to PDF.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to convert {url} to PDF: {ex.Message}");
    }
}

Dim testUrls = { "https://ironpdf.com", "https://notexistingdomain.com/", "http://httpbin.org/delay/120" }

For Each url In testUrls
	Try
		Dim pdfBytes = Await retryPolicy.WrapAsync(circuitBreakerPolicy).ExecuteAsync(Function() htmlToPdf.RenderUrlAsPdfAsync(url))

		pdfBytes.SaveAs($"{Guid.NewGuid()}.pdf")
		Console.WriteLine($"Successfully converted {url} to PDF.")
	Catch ex As Exception
		Console.WriteLine($"Failed to convert {url} to PDF: {ex.Message}")
	End Try
Next url

VB C#

在上述代码中，我们遍历一组测试 URL，并尝试将每个 URL 转换为 PDF。如果请求失败，将捕获异常并在控制台中显示适当的消息。

.NET Core Polly（如何为开发人员工作）：图 1 - URL 至 PDF 输出