跳過到頁腳內容
.NET幫助

.NET Core Polly(開發者的工作原理)

Polly 是一個 .NET 復原策略和暫態故障處理函式庫,允許開發人員表達復原策略,例如重試策略、斷路器、逾時、隔離埠隔離策略和回退。 Polly 以 ASP.NET Core 為目標,使其成為 .NET Core 復原的重要工具。 Polly 是線程安全的,並支援處理多個成功回應的並發請求。

本教程將提供更多關於暫態故障處理 .NET 函式庫 Polly 的詳細資訊,以及如何在 ASP.NET Core 應用程式中將其與 IronPDF 搭配使用。 我們會深入探討 Polly 的每個面向,解釋斷路器模式的機制,討論隔板隔離和逾時,並展示如何以受控、線程安全的方式,處理特定的異常或失敗服務的失敗回應。

Polly 策略

當您的應用程式嘗試透過 HTTP 請求、資料庫或其他外部資源與網路服務連線時,常會發生暫態故障。 這些故障,例如網路故障、暫時連線問題或超時,都很短暫,通常在短時間後就會自行糾正。

Polly 透過應用不同的策略和表達政策來管理這些暫態故障,例如重試政策 (Retry Policy)、進階斷路器政策 (advanced Circuit Breaker Policy)、逾時政策 (Timeout Policy)、回退政策 (Fallback Policy) 和隔離政策 (Bulkhead Isolation Policy)。

回覆政策

重試策略使用重試邏輯自動重試失敗的並發請求。 它可以設定為永遠重複嘗試,或進行一定次數的自動重複嘗試,它可以在重複嘗試之間等待設定的時間間隔,或使用指數回溯。

斷路器

Circuit Breaker (斷路器) 政策可讓您的系統在預先設定的要求失敗臨界值之後,支援嘗試特定服務的取消標記。 斷路器策略類似於混沌工程或船舶關閉水密門以局部損壞:一個故障不會讓整艘船沉沒。

逾時政策

超時政策強制執行特定 .NET 復原程式碼的最長時間。 它有兩種風格:樂觀超時和悲觀超時。

回退政策

回退策略用於在發生故障時提供替代值或行為。 當服務失敗不應導致整個流程停頓時,此政策就能發揮作用。

艙壁隔離

Bulkhead 隔離用於限制特定作業的並發請求數量,從而限制套接字耗盡的可能性,並維持受控的執行時隙數量。

快取政策

快取政策會快取執行成功的回應,因此如果再次調用相同的執行,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}");
    });
// 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}");
    });
' Retry policy for handling HttpRequestException with exponential back-off
Dim retryPolicy = Policy.Handle(Of HttpRequestException)().WaitAndRetryAsync(3, Function(retryAttempt) TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), Sub(exception, timeSpan, retryCount, context)
	Console.WriteLine($"Retry {retryCount} after {timeSpan}. Exception: {exception.Message}")
End Sub)
$vbLabelText   $csharpLabel

斷路器政策

斷路器 (Circuit Breaker) 策略可讓 Polly 函式庫監控故障,如果故障次數在指定時間內超過設定的臨界值,則電路會"斷開",並在指定時間內阻斷進一步的請求。這稱為"開放"狀態。 這段時間之後,電路會進入"半開放"狀態,允許一些流量來檢查特定服務的健康狀況。如果這些請求成功且沒有故障發生,電路就會關閉; 否則會再次打開。

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

逾時政策

超時政策可處理服務未在合理時間內回應的情況。 Polly 提供兩種類型的超時:樂觀和悲觀。 樂觀超時在單獨的線程中運行,並通過 CancellationToken 取消底層操作。 悲觀超時會阻塞父線程,直到作業完成或超時期間結束。

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

艙壁隔離

Bulkhead Isolation 用於限制針對特定服務的並發動作的數量。它提供了一種隔離故障並防止故障連鎖發生的方法。 這也限制了我們對依賴者的負擔。

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

回退政策

當您需要提供預設行為或替代值時,當其他方法都失敗時,回退原則是非常有用的。

// 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;
        });
// 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;
        });
' Fallback policy to provide a default result on failure
Dim fallbackPolicy = Policy.Handle(Of Exception)().FallbackAsync(Of FallbackResult)(FallbackResult.SomethingWentWrong, Function(exception, context)
			Console.WriteLine($"Fallback triggered due to: {exception.Message}")
			Return Task.CompletedTask
End Function)
$vbLabelText   $csharpLabel

包裝政策

可使用 PolicyWrap 靈活組合多重策略:

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

開始

若要開始使用 Polly 與 IronPDF,請確定您已安裝 Visual Studio,並在 .NET Core 中建立新的 Console Application 專案。 在 Visual Studio 中開啟 NuGet 套件管理器控制台,並安裝 PollyIronPDF 套件:

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
$vbLabelText   $csharpLabel

讓我們以使用 Polly 與 IronPDF 來 將 URL 轉換為 PDF 為例進行說明。 假設我們有一個 Web 服務偶爾會因為瞬間故障而失敗,而我們想要使用 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
$vbLabelText   $csharpLabel

接下來,我們將定義我們的政策。 在這個範例中,我們將結合使用重試與斷路器政策來處理故障:

// 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));
// 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));
' Retry policy with exponential backoff
Dim retryPolicy = Policy.Handle(Of Exception)().WaitAndRetryAsync(3, Function(i) TimeSpan.FromSeconds(2 * i))

' Circuit breaker policy to block requests after consecutive failures
Dim circuitBreakerPolicy = Policy.Handle(Of Exception)().CircuitBreakerAsync(2, TimeSpan.FromSeconds(30))
$vbLabelText   $csharpLabel

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

現在,讓我們定義 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");
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");
Dim htmlToPdf = New ChromePdfRenderer()
Dim pdfBytes = Await retryPolicy.WrapAsync(circuitBreakerPolicy).ExecuteAsync(Async Function()
		Console.WriteLine("Attempting to convert URL to PDF...")
		Dim result = Await htmlToPdf.RenderUrlAsPdfAsync("https://example.com")
		Console.WriteLine("Conversion successful!")
		Return result
End Function)

pdfBytes.SaveAs("output.pdf")
$vbLabelText   $csharpLabel

在上面的範例程式碼中,我們使用 retryPolicycircuitBreakerPolicy 方法包裝我們的 WrapAsync。 這可讓我們依序對新請求套用多項政策。 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}");
    }
}
Imports System

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
$vbLabelText   $csharpLabel

在上述程式碼中,我們會遍歷一組測試 URL,並嘗試將其逐一轉換為 PDF。 如果請求失敗,則會捕捉到異常,並在控制台中顯示適當的訊息。

.NET Core Polly (How It Works For Developers):圖 1 - URL 至 PDF 輸出

結論

Polly 是一個功能強大且靈活的函式庫,用於在 .NET Core 應用程式中實作彈性與暫態故障處理。 透過結合重試和斷路器等政策,開發人員可以建立穩健且容錯的系統,從容處理故障。

在本教程中,我們探討了如何使用 Polly 搭配 IronPDF 將 URL 轉換為 PDF。 我們學習了如何定義和套用 Polly 策略,包括重試和斷路器。 我們也使用不同的 URL 測試我們的政策。 我們也可以使用同樣的方式將 HTML 轉換為 PDF

IronPDF 提供 免費試用,且授權起始價格極具競爭力,可讓您在專案中充分利用其功能。

常見問題解答

什麼是 Polly,它如何增強 .NET Core 的彈性?

Polly 是一個專為彈性和瞬態故障處理設計的 .NET 庫,特別適用於 ASP.NET Core 應用程序。它通過提供諸如重試、斷路器、超時、隔艙隔離和降級等策略來提高彈性,確保系統的穩健性和容錯能力。

我如何在 .NET Core 中使用 Polly 實現重試策略?

在 .NET Core 中,您可以使用 Polly 通過配置自動重試失敗的請求來實現重試策略。這可以通過設置重試次數和嘗試之間的時間間隔來完成,以有效管理瞬態故障。

斷路器策略如何防止 .NET 應用程序中的級聯故障?

Polly 中的斷路器策略通過監控故障並在到達故障閾值時打開電路阻止請求來防止級聯故障。這會阻止進一步的請求,直到電路重置,使系統在接受新請求之前能夠恢復。

隔艙隔離在管理資源耗盡方面起到什麼作用?

Polly 中的隔艙隔離限制服務的並發請求數量,通過控制執行槽位來防止資源耗盡。此策略有助於控制故障並確保 .NET Core 應用程序中的資源管理效率。

Polly 的超時策略如何提高應用程序的響應性?

Polly 的超時策略為操作執行設置最大時間,這有助於管理服務無法及時響應的場景。通過設置樂觀或悲觀超時,開發者可以確保應用程序始終保持響應。

是否可以使用 Polly 增強 URL 到 PDF 轉換的可靠性?

是的,Polly 可以通過將其重試和斷路器策略與 PDF 生成工具集成來增強 URL 到 PDF 轉換的可靠性。這確保了轉換過程對瞬態故障具有彈性,維持可靠性。

Polly 中的降級策略如何確保服務的優雅降級?

Polly 中的降級策略提供當服務失效時的替代響應或行為。這有助於確保一個故障不會導致整個應用程序停頓,允許優雅降級和持續運行。

您如何在 .NET 應用程序中結合多個 Polly 策略?

在 .NET 應用程序中,可以使用策略包裝來結合多個 Polly 策略。這允許開發者將不同的彈性策略一起執行,實現更全面和靈活的故障處理方法。

將 Polly 與 IronPDF 整合如何處理 PDF 生成中的瞬態故障?

通過將 Polly 與 IronPDF 整合,開發者可以通過重試和斷路器等策略來處理 PDF 生成中的瞬態故障。這樣的整合確保了即使在偶爾的服務中斷下 PDF 生成仍然穩定和可靠。

使用 Polly 與 .NET Core 時的一些常見故障排除策略是什麼?

常見的故障排除策略包括驗證策略配置,例如重試間隔和斷路器閾值,並通過不同場景測試策略以確保正確處理故障和系統的彈性。

Jacob Mellor, Team Iron 首席技術官
首席技術官

Jacob Mellor是Iron Software的首席技術官,也是開創C# PDF技術的前瞻性工程師。作為Iron Software核心代碼庫的原始開發者,他自公司成立以來就塑造了公司的產品架構,並與CEO Cameron Rimington將公司轉型為服務NASA、Tesla以及全球政府機構的50多人公司。

Jacob擁有曼徹斯特大學土木工程一級榮譽學士學位(1998年–2001年)。他於1999年在倫敦開立首家軟體公司,並於2005年建立了他的第一個.NET組件,專注於解決Microsoft生態系統中的複雜問題。

他的旗艦作品IronPDF和Iron Suite .NET程式庫全球已獲得超過3000萬次NuGet安裝,他的基礎代碼不斷在全球各地驅動開發者工具。擁有25年以上的商業經驗和41年的編碼專業知識,Jacob仍然專注於推動企業級C#、Java和Python PDF技術的創新,同時指導下一代技術領導者。

鋼鐵支援團隊

我們每週 5 天,每天 24 小時在線上。
聊天
電子郵件
打電話給我