アプリケーションの回復性を実装する

  • 10 分

.NET の回復性機能は Polly プロジェクトに基づいて構築され、Microsoft.Extensions を通じて利用できます。 1 行のコードをアプリに追加することで、適切な既定値を使用する標準の回復性戦略を追加できます。

アプリに回復性を追加する

マイクロサービス アーキテクチャを使って構築されたアプリに回復性を追加し、個々のサービス間で HTTP 要求を使用するには、これらの手順を行います。

  1. Microsoft.Extensions.Http.Resilience パッケージをプロジェクトに追加します。
  2. HttpClient サービス呼び出しに回復性ハンドラーを追加します。
  3. 回復性戦略を構成します。

NuGet パッケージをプロジェクトに追加する

次のコマンドを実行して、回復性 NuGet パッケージを追加します。

dotnet add package Microsoft.Extensions.Http.Resilience

アプリ プロジェクト フォルダーのターミナルからこのコマンドを実行すると、パッケージ参照がプロジェクト ファイルに追加されます。

アプリケーションのスタートアップ クラスで、次の using ステートメントを追加します。

using Microsoft.Extensions.Http.Resilience;

回復性戦略を追加する

HttpClient サービスに標準の回復性戦略を追加できるようになりました。 .NET には、多数の戦略を組み合わせた、このすぐに使用できる構成が用意されています。

A diagram showing the strategies included in the Standard Resilience Handler. From overall timeout, retry, bulkhead, circuit breaker, and attempt timeout.

要求ハンドラーは、上記の各戦略を左から右の順に通過します。

  • 合計要求タイムアウト戦略:これにより、要求に要する合計時間が設定されます。 これは、他のすべての戦略の上限時間を設定していると考えることができます。
  • 再試行戦略:この戦略では、再試行回数、バックオフ数、ジッター数のオプションを制御します。 これらのオプションは、前の戦略で設定された合計タイムアウトを超えることはできません。
  • サーキット ブレーカー戦略:この戦略では、障害率がしきい値を超えた場合に回線が開かれます。
  • 試行タイムアウト戦略:この戦略では、個々の要求ごとにタイムアウトが設定されます。 要求にこの時間より長くかかる場合は、例外がスローされます。

この拡張メソッドを追加することで、すべて既定値でこの標準戦略を追加できます。

.AddStandardResilienceHandler();

たとえば、WebApplication を宣言していて、HttpClient サービスに回復性戦略を追加する場合は、このコードを使用します。

builder.Services.AddHttpClient<ServiceBeingCalled>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://service.endpoint/");
}).AddStandardResilienceHandler();

上記のコードの最初の行では、HTTPClient に標準の回復性ハンドラーが追加されます。 これにより、再試行とサーキット ブレーカー戦略のすべての既定の設定が使用されます。

回復性戦略を構成する

次のような新しいオプションを指定することで、任意の戦略の既定値を変更できます。

.AddStandardResilienceHandler( options => 
{  
    options.RetryOptions.RetryCount = 10;
    options.RetryOptions.BaseDelay = TimeSpan.FromSeconds(1);
});

このコードでは、再試行戦略の既定値が再試行の最大回数である 10 に変更され、線形バックオフが使用され、基本遅延として 1 秒が使用されるようになります。

選択するオプションに互換性がある必要があります。 たとえば、合計時間が既定値の 30 秒のままである場合、上記の再試行オプションによって例外が発生します。 指数バックオフ設定により、10 回の再試行を完了するまでの合計時間が 2046 秒になるため、これはエラーです。 これはランタイム例外であり、コンパイル時エラーではありません。

次の表に、各戦略で使用できるオプションを一覧表示します。

合計要求タイムアウトのオプション 説明
TotalTimeout 要求に要する合計時間。 既定値は 30 秒です。
OnTimeout 要求がタイムアウトになったときに呼び出されるコールバック関数。既定値は null です。
再試行オプション 説明
RetryCount 最大再試行回数。 既定値は 3 です。
BackoffType 使用するバックオフの種類。 線形と指数のどちらかを選択できます。 既定値は指数です。
UseJitter バックオフにジッターを追加するかどうか。 ジッターでは、遅延にランダム性が追加され、負荷の急増を減らすのに役立ちます。 既定値は true です。
BaseDelay 再試行間の遅延。 既定は 2 秒です。
サーキット ブレーカーのオプション 説明
BreakDuration 回線遮断の期間。 既定値は 5 秒です。
FailureRatio 回線を開く成功した要求に対する失敗した要求の比率。 既定値は 0.1 です。
SamplingDuration 故障率が計算される期間。 既定値は 30 秒です。
OnClosed 回線が閉じられたときに呼び出されるコールバック関数。 既定値は null です。
OnHalfOpened 回線が半分開いているときに呼び出されるコールバック関数。 既定値は null です。
OnOpened 回線が開かれたときに呼び出されるコールバック関数。 既定値は null です。
試行タイムアウトのオプション 説明
タイムアウト 要求に要する時間。 既定は 2 秒です。
OnTimeout 要求がタイムアウトになったときに呼び出されるコールバック関数。既定値は null です。

A sequence diagram showing the flow of events in an application using a resiliency strategy.

上のシーケンス図は、標準の回復性戦略で各戦略がどのように連携するかを示しています。 まず、要求にかかる時間の制限要因は、合計タイムアウト戦略によって制御されます。 その後、再試行戦略は、合計タイムアウト内に完了する再試行の最大数を含むように設定する必要があります。 故障率が設定されたしきい値を超えると、サーキット ブレーカー戦略によって回線が開かれます。 試行タイムアウト戦略では、個々の要求ごとにタイムアウトが設定されます。 要求にこの時間より長くかかる場合は、例外がスローされます。