復原應用程式開發簡介

發行項
03/01/2024

「復原」是指應用程式從暫時性失敗中復原並繼續運作的能力。在 .NET 程式設計的內容中，藉由設計可正常處理失敗並快速復原的應用程式來達成復原。為了協助在 .NET 中建置復原性應用程式，NuGet 上提供下列兩個套件：

NuGet 套件	描述
📦 Microsoft.Extensions.Resilience	此 NuGet 套件提供機制來強化應用程式，以防止暫時性失敗。
📦 Microsoft.Extensions.Http.Resilience	此 NuGet 套件提供 HttpClient 類別專屬的復原機制。

這兩個 NuGet 套件是在 Polly 的基礎上建置，這是熱門的開放原始碼專案。 Polly 是 .NET 復原和暫時性失敗處理程式庫，可讓開發人員以流暢且安全執行緒的方式表達重試、斷路器、逾時、大量隔離、速率限制、後援和對沖等策略。

重要

Microsoft.Extensions.Http.Polly NuGet 套件已淘汰。請改用上述其中一個套件。

開始使用

若要開始使用 .NET 中的復原，請安裝 Microsoft.Extensions.Resilience NuGet 套件。

.NET CLI
PackageReference

dotnet add package Microsoft.Extensions.Resilience --version 8.0.0

<PackageReference Include="Microsoft.Extensions.Resilience" Version="8.0.0" />

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

建置復原管線

若要使用復原，您必須先建置以復原為基礎的策略管線。每個設定的策略都會依組態順序執行。換句話說，順序很重要。進入點是 IServiceCollection 類型上的擴充方法，名為 AddResiliencePipeline。這個方法會取得管線的識別碼，以及可設定管線的委派。委派會傳遞 ResiliencePipelineBuilder 的執行個體，用來將復原策略新增至管線。

請考慮下列以字串為基礎的 key 範例：

using Microsoft.Extensions.DependencyInjection;
using Polly;
using Polly.CircuitBreaker;
using Polly.Registry;
using Polly.Retry;
using Polly.Timeout;

var services = new ServiceCollection();

const string key = "Retry-Timeout";

services.AddResiliencePipeline(key, static builder =>
{
    // See: https://www.pollydocs.org/strategies/retry.html
    builder.AddRetry(new RetryStrategyOptions
    {
        ShouldHandle = new PredicateBuilder().Handle<TimeoutRejectedException>()
    });

    // See: https://www.pollydocs.org/strategies/timeout.html
    builder.AddTimeout(TimeSpan.FromSeconds(1.5));
});

上述程式碼：

建立新的 ServiceCollection 執行個體。
定義 key 以識別管線。
將復原管線新增至 ServiceCollection 執行個體。
使用重試和逾時策略來設定管線。

每個管線都會針對指定的 key 設定，而且每個 key 都會用來識別從提供者取得管線時的對應 ResiliencePipeline。 key 是 AddResiliencePipeline 方法的泛型型別參數。

復原管線建立器延伸模組

若要將策略新增至管線，請在 ResiliencePipelineBuilder 執行個體上呼叫任何可用的 Add* 擴充方法。

AddRetry：如果某個項目失敗請再試一次，當問題是暫時的且可能消失時會很有用。
AddCircuitBreaker：如果某個項目中斷或忙碌則停止嘗試，這有利於您避免浪費時間，並且讓事情變得更糟。
AddTimeout：如果某個項目花費太長的時間請放棄，藉由釋放資源來改善效能。
AddRateLimiter：限制您接受的要求數目，這可讓您控制輸入負載。
AddConcurrencyLimiter：限制您提出的要求數目，這可讓您控制輸出負載。
AddFallback：遇到失敗時請執行其他項目，可改善使用者體驗。
AddHedging：在高延遲或失敗的情況下發出多個要求，可改善回應性。

如需詳細資訊，請參閱復原策略。如需範例，請參閱建置復原性 HTTP 應用程式：主要開發模式。

計量擴充

擴充是名稱/值組形式，具有已知狀態的自動增強遙測。例如，應用程式可能會發出記錄，其中包含作業和結果碼作為資料行，以代表某些作業的結果。在此情況下，視周邊內容而定，擴充會在傳送至遙測後端時，將叢集名稱、程序名稱、區域、租用戶識別碼等項目新增至記錄。新增擴充時，應用程式程式碼不需要執行任何額外的動作，即可從擴充的計量中獲益。

擴充的運作方式

假設有 1,000 個全域分散式服務執行個體產生記錄和計量。當您在服務儀表板上遇到問題時，快速識別有問題的區域或資料中心非常重要。擴充可確保計量記錄包含找出分散式系統中失敗的必要資訊。如果沒有擴充，內部管理此狀態、將其整合至記錄程序，然後手動傳輸的負擔就會落到應用程式程式碼上面。擴充可簡化此程序，順暢地處理，而不會影響應用程式的邏輯。

在復原的情況下，當您新增擴充時，下列維度會新增至傳出遙測：

error.type：例外狀況資訊的低基數版本。
request.name：要求的名稱。
request.dependency.name：相依性的名稱。

實際上，復原擴充是在 Polly 的遙測 MeteringEnricher 基礎上建置。如需詳細資訊，請參閱 Polly：計量擴充。

新增復原擴充

除了註冊復原管線之外，您也可以註冊復原擴充。若要新增擴充，請在 IServiceCollection 執行個體上呼叫 AddResilienceEnricher(IServiceCollection) 擴充方法。

services.AddResilienceEnricher();

藉由呼叫 AddResilienceEnricher 擴充方法，您會在基礎 Polly 程式庫內建的預設維度之上新增維度。已新增下列擴充維度：

根據 IExceptionSummarizer 的例外狀況擴充，提供一個機制來摘要用於遙測的例外狀況。如需詳細資訊，請參閱例外狀況摘要彙總。
根據 RequestMetadata 要求中繼資料擴充，其會保存遙測的要求中繼資料。如需詳細資訊，請參閱 Polly：遙測計量。

使用復原管線

若要使用已設定的復原管線，您必須從 ResiliencePipelineProvider<TKey> 取得管線。當您稍早新增管線時，key 的類型為 string，因此您必須從 ResiliencePipelineProvider<string> 取得管線。

using ServiceProvider provider = services.BuildServiceProvider();

ResiliencePipelineProvider<string> pipelineProvider =
    provider.GetRequiredService<ResiliencePipelineProvider<string>>();

ResiliencePipeline pipeline = pipelineProvider.GetPipeline(key);

上述程式碼：

從 ServiceCollection 執行個體建置 ServiceProvider。
從服務提供者取得 ResiliencePipelineProvider<string>。
從 ResiliencePipelineProvider<string> 擷取 ResiliencePipeline。

執行復原管線

若要使用復原管線，請在 ResiliencePipeline 執行個體上呼叫任何可用的 Execute* 方法。例如，請考慮呼叫 ExecuteAsync 方法的範例：

await pipeline.ExecuteAsync(static cancellationToken =>
{
    // Code that could potentially fail.

    return ValueTask.CompletedTask;
});

上述程式碼會在 ExecuteAsync 方法內執行委派。發生失敗時，會執行已設定的策略。例如，如果 RetryStrategy 設定為重試三次，則會在傳播失敗之前執行委派四次 (一次初始嘗試加上三次重試嘗試)。

下一步

建置復原性 HTTP 應用程式：主要開發模式考慮重試呼叫的等冪處理挑戰

共用方式為