IRONSOFTWAREHOME
开发者更新

.NET Core Polly(开发者如何使用)

Jacob Mellor,Team Iron 的首席技术官
Jacob Mellor
Updated: 2025年7月28日

Polly 是一个 .NET 弹性策略和瞬态故障处理库,允许开发人员表达弹性策略,如重试策略、断路器、超时、舱壁隔离策略和回退。 Polly 以 ASP.NET Core 为目标,使其成为 .NET Core 弹性的重要工具。 Polly 是线程安全的,支持处理多个并发请求并成功响应。

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

Polly 策略

瞬态故障经常发生在您的应用程序尝试通过 HTTP 请求连接到 Web 服务、数据库或其他外部资源时。 这些故障,如网络故障、临时连接问题或超时,通常是短暂的,并会在短时间内自我纠正。

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

重试策略

重试策略使用重试逻辑自动重试失败的并发请求。 它可以配置为永远重试或自动重试一定次数,并且可以在重试之间等待设定的时间间隔或使用指数退避。

断路器

断路器策略使您的系统支持在配置的失败请求阈值后尝试特定服务的取消令牌。 断路器策略类似于混沌工程或船只关闭防水门以局部化损坏:一个故障不会让整艘船沉没。

超时策略

超时策略强制执行特定 .NET 弹性代码可以执行的最长时间。 它有两种形式:乐观超时和悲观超时。

回退策略

回退策略用于在发生故障时提供替代值或行为。 当失败的服务不应停止整个过程时,此策略非常有用。

舱壁隔离

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

缓存策略

缓存策略缓存执行的成功响应,以便在同一执行再次调用时,Polly 可以返回分布式缓存值。

策略包装

允许我们将多个策略结合在一起,使其可以作为一个单元工作。

创建和配置策略

重试策略

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

// Retry policy for handling HttpRequestException with exponential back-off
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
        Console.WriteLine($"Retry {retryCount} after {timeSpan}. Exception: {exception.Message}");
    });

断路器策略

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

// Circuit breaker policy to handle failing requests with open and half-open states
var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(5, TimeSpan.FromMinutes(1));

超时策略

超时策略处理服务未在合理时间范围内响应的场景。 Polly 提供两种类型的超时:乐观和悲观。 乐观的超时在单独的线程上工作,并通过CancellationToken取消底层操作。 悲观超时会阻塞父线程,直到操作完成或超时时间过去。

// Timeout policy with a 30-second optimistic timeout
var timeoutPolicy = Policy.TimeoutAsync(30); // 30 seconds

舱壁隔离

舱壁隔离用于限制对特定服务的并发操作数量。它提供了一种隔离故障的方法,防止它们连锁反应。 它还限制了我们对依赖项所施加的负载。

// Bulkhead isolation policy to limit concurrency and queue length
var bulkheadIsolationPolicy = Policy.BulkheadAsync(10, 20); // 10 concurrent actions, 20 queue slots

回退策略

当所有其他方法均告失败时,回退策略在需要提供默认行为或替代值时非常有用。

// Fallback policy to provide a default result on failure
var fallbackPolicy = Policy
    .Handle<Exception>()
    .FallbackAsync<FallbackResult>(
        FallbackResult.SomethingWentWrong, 
        (exception, context) => 
        {
            Console.WriteLine($"Fallback triggered due to: {exception.Message}");
            return Task.CompletedTask;
        });

包装策略

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

// Combining multiple policies using PolicyWrap
var policyWrap = Policy.WrapAsync(fallbackPolicy, retryPolicy, circuitBreakerPolicy, timeoutPolicy, bulkheadIsolationPolicy);

开始

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

PM > Install-Package Polly

PM > Install-Package IronPdf

在 IronPDF 中使用 Polly 将 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");
    }
}

让我们通过一个使用 Polly 和 IronPDF 的例子来转换 URL 为 PDF。 假设我们有一个由于瞬态故障而偶尔失败的 Web 服务,我们希望使用 Polly 优雅地处理这些故障。

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

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

接下来,我们将定义我们的策略。 在此示例中,我们将结合使用重试和断路器策略来处理故障:

// Retry policy with exponential backoff
var retryPolicy = Policy
    .Handle<Exception>()
    .WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(2 * i));

// Circuit breaker policy to block requests after consecutive failures
var circuitBreakerPolicy = Policy
    .Handle<Exception>()
    .CircuitBreakerAsync(2, TimeSpan.FromSeconds(30));

retryPolicy将使用指数退避策略最多重试失败的请求三次,在重试之间等待2秒、4秒和8秒。 circuitBreakerPolicy如果在30秒的时间间隔内连续发生两次失败,将打开电路。

现在,让我们定义我们的 IronPDF 代码,将 URL 转换为 PDF:

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

pdfBytes.SaveAs("output.pdf");

在上面的示例代码中,我们使用circuitBreakerPolicy。 这使我们能够对新请求按顺序应用多个策略。 RenderUrlAsPdfAsync方法。

通过应用 Polly 策略,我们确保我们的代码具有适应瞬态故障的弹性。 如果请求失败,Polly 将根据重试策略自动重试。 如果连续故障的数量超过预配置的阈值,则断路器策略将打开电路,防止在指定时间内进一步的请求。

Polly 策略的测试用例

为了测试我们的 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}");
    }
}

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

.NET Core Polly(开发人员如何使用):图1 - URL到PDF输出

结论

Polly 是一个功能强大且灵活的库,用于在 .NET Core 应用程序中实现弹性和瞬态故障处理。 通过结合重试和断路器等策略,开发人员可以构建稳健和容错的系统,优雅地处理故障。

在本教程中,我们探索了如何使用 Polly 和 IronPDF 转换 URL 为 PDF。 我们学习了如何定义和应用 Polly 策略,包括重试和断路器。 我们还用不同的 URL 测试了我们的策略。 我们还可以将其用于将 HTML 转换为 PDF。

IronPDF 提供免费试用,许可证以具有竞争力的价格起售,使您能够在项目中利用其功能。

Jacob Mellor,Team Iron 的首席技术官
首席技术官

Jacob Mellor 是 Iron Software 的首席技术官,也是一位开创 C# PDF 技术的有远见的工程师。作为 Iron Software 核心代码库的原始开发者,他从公司成立之初就开始塑造公司的产品架构,与首席执行官 Cameron Rimington 一起将公司转变为一家拥有 50 多名员工的公司,为 NASA、特斯拉和全球政府机构提供服务。

相关文章

Key in blue circle

立即获取免费的 30 天试用版密钥。

Your trial license will be sent to your email address

无任何限制。100% 解锁。无需信用卡。

OR
bullet_checked无需信用卡或创建账户无任何限制。100% 解锁。无需信用卡。
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried Iron Suite
预约您的免费现场演示
Booking Badge

深受全球数百万工程师信赖

Iron Software 的客户徽标
获取您的无义务咨询
填写下面的表格或通过sales@ironsoftware.com
您的资料将始终保密。
深受全球数百万工程师信赖
Iron Software 的客户徽标
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
C# 用于 PDF 的 NuGet 库
通过 NuGet 安装

版本: 2026.9

PM > Install-Package IronPdf
nuget.org/packages/IronPdf/
  1. 在解决方案资源管理器中,右键点击引用,管理 NuGet 包
  2. 选择浏览并搜索 “IronPDF”
  3. 选择包并安装
C# PDF DLL
下载 DLL

版本: 2026.9

或在此处下载 Windows 安装程序。

  1. 下载并解压 IronPDF 到您的解决方案目录中的 ~/Libs 之类的位置
  2. 在 Visual Studio 解决方案资源管理器中,右键点击引用。选择浏览,“IronPDF.dll”

$999 起