.NET 幫助

.NET Core Polly（如何為開發者運作）

發佈 2023年7月26日

波利這是一個.NET的韌性策略和瞬時故障處理庫，允許開發人員表達韌性策略，例如重試策略、熔斷器、超時、柵欄隔離策略和回退。Polly專注於ASP.NET Core，是.NET Core韌性的重要工具。Polly具有線程安全的特性，並支持處理多個並發請求以獲取成功響應。

本教程將詳細介紹瞬時故障處理.NET庫Polly及其使用方式。 IronPDF 在 ASP.NET Core 應用程式中。我們將深入探討 Polly 的每個方面，解釋斷路器模式的機制，討論艙壁隔離和超時，並展示如何以受控且執行緒安全的方式處理特定異常或失敗服務的失敗回應。

Polly 策略

當您的應用程序嘗試通過 HTTP 請求、數據庫或其他外部資源與 web 服務連接時，經常會出現短暫故障。這些故障，如網絡失敗、臨時連接問題或超時，都是短暫的，通常在短時間內自行糾正。

Polly 通過採用不同的策略和表達型策略來管理這些短暫故障，如重試策略、高級熔斷器策略、超時策略、回退策略和艙壁隔離策略。

重試策略

重試策略會自動使用重試邏輯來重試失敗的並發請求。可以配置為永遠重試或自動重試特定次數，並且可以在重試之間等待設定的時間間隔或使用指數回退。

斷路器

斷路器策略允許您的系統在達到預設的失敗請求閾值後，支持使用取消令牌來嘗試特定服務。斷路器策略類似於混沌工程或一艘船關閉水密門以局限損害：一個故障不會使整艘船沉沒。

超時政策

超時政策強制特定的 .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#

Bulkhead Isolation

Bulkhead Isolation 用於限制針對特定服務的併發操作數量。它提供了一種隔離故障並防止故障蔓延的方法。它還限制了我們對依賴項施加的負載。

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#

retryPolicy 將採用指數回退策略重試失敗的請求最多三次，分別在重試之間等待2秒、4秒和8秒。circuitBreakerPolicy 如果在30秒時間間隔內連續發生兩次失敗，將會打開電路。

現在，讓我們定義將URL轉換為PDF的IronPDF代碼：

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 策略的測試案例

要測試我們的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#

在上面的程式碼中，我們迭代一組測試網址並嘗試將每個網址轉換為PDF。如果請求失敗，將會捕獲異常並在控制台顯示適當的訊息。

.NET Core Polly（開發人員如何使用）：圖 1 - 網址到 PDF 輸出