.NET 幫助

.NET Core Polly（開發者使用指南）

更新:7月 28, 2025

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

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

Polly Policies

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

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

回覆政策

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

斷路器

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

逾時政策

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

回退政策

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

Bulkhead Isolation

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}");
    });

$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));

$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

$vbLabelText $csharpLabel

Bulkhead Isolation

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

$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;
        });

$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);

$vbLabelText $csharpLabel

開始

若要開始使用 Polly 與 IronPDF，請確定您已安裝 Visual Studio，並在 .NET Core 中建立新的 Console Application 專案。在 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");
    }
}

$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;

$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));

$vbLabelText $csharpLabel

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");

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");

$vbLabelText $csharpLabel

在上述範例程式碼中，我們使用 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}");
    }
}

$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 應用程式中，可以使用策略包裝 (Policy Wraps) 將多個 Polly 策略組合在一起。這使得開發人員能夠同時執行不同的彈性策略，從而實現更全面、更靈活的故障處理方法。

Polly 與 IronPDF 整合後如何處理 PDF 產生中的瞬態故障？

透過將 Polly 與 IronPDF 集成，開發人員可以透過重試和熔斷器等策略來處理 PDF 生成過程中的瞬態故障。這種整合確保即使偶爾出現服務中斷，也能穩定可靠地產生 PDF 文件。

使用 Polly 和 .NET Core 時，有哪些常見的故障排除策略？

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

雅各·梅勒

現在就和工程團隊聊天吧

首席技術長

Jacob Mellor 是 Iron Software 的首席技術官，也是一位富有遠見的工程師，率先開發了 C# PDF 技術。作為 Iron Software 核心程式碼庫的最初開發者，他自公司成立之初便參與塑造了其產品架構，並與執行長 Cameron Rimington 一起將其發展成為一家擁有 50 多名員工、服務於 NASA、特斯拉和全球政府機構的公司。

Jacob 於 1998 年至 2001 年在曼徹斯特大學獲得土木工程一級榮譽學士學位。 1999 年，他在倫敦創辦了自己的第一家軟體公司；2005 年，他創建了自己的第一個 .NET 元件。此後，他專注於解決微軟生態系統中的複雜問題。

他的旗艦產品 IronPDF 和 IronSuite .NET 庫在全球 NuGet 上的安裝量已超過 3000 萬次，其基礎程式碼持續為全球開發者工具提供支援。憑藉 25 年的商業經驗和 41 年的程式設計專長，Jacob 始終致力於推動企業級 C#、Java 和 Python PDF 技術的創新，同時指導下一代技術領導者。

C# 字串分割（開發者使用方法）

Blazor 與 MVC（開發者如何理...

客戶亮點：

開發者對焦：

網路研討會：

.NET Core Polly（開發者使用指南）

Polly Policies

回覆政策

斷路器

逾時政策

回退政策

Bulkhead Isolation

快取政策

政策包裝

建立和設定政策。

回覆政策

斷路器政策

逾時政策

Bulkhead Isolation

回退政策

包裝政策

開始

使用 Polly 與 IronPDF 將 URL 轉換為 PDF 。

Polly Policies 的測試案例

結論

常見問題解答

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

如何在 .NET Core 中使用 Polly 實作重試策略？

熔斷策略如何防止 .NET 應用程式中出現級聯故障？

艙壁隔離在資源枯竭管理中扮演什麼角色？

Polly 的超時策略如何提高我的應用程式的反應速度？

Polly 能否用來提升 URL 轉 PDF 轉換的可靠性？

Polly 中的回退策略如何確保服務優雅降級？

如何在 .NET 應用程式中組合多個 Polly 策略？

Polly 與 IronPDF 整合後如何處理 PDF 產生中的瞬態故障？

使用 Polly 和 .NET Core 時，有哪些常見的故障排除策略？

.NET Core Polly（開發者使用指南）

Polly Policies

回覆政策

斷路器

逾時政策

回退政策

Bulkhead Isolation

快取政策

政策包裝

建立和設定政策。

回覆政策

斷路器政策

逾時政策

Bulkhead Isolation

回退政策

包裝政策

開始

使用 Polly 與 IronPDF 將 URL 轉換為 PDF 。

Polly Policies 的測試案例

結論

常見問題解答

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

如何在 .NET Core 中使用 Polly 實作重試策略？

熔斷策略如何防止 .NET 應用程式中出現級聯故障？

艙壁隔離在資源枯竭管理中扮演什麼角色？

Polly 的超時策略如何提高我的應用程式的反應速度？

Polly 能否用來提升 URL 轉 PDF 轉換的可靠性？

Polly 中的回退策略如何確保服務優雅降級？

如何在 .NET 應用程式中組合多個 Polly 策略？

Polly 與 IronPDF 整合後如何處理 PDF 產生中的瞬態故障？

使用 Polly 和 .NET Core 時，有哪些常見的故障排除策略？

相關文章

連結 CLI 的簡潔性和 .NET：將 Curl DotNet 與 IronPDF 結合使用

C# 隨機數產生器

C# 字串相等運算子（開發者使用方法）

下一步：開始30天免費試用

下一步：開始30天免費試用

深受全球數百萬工程師信賴