ASP.NET Core で IHttpClientFactory を使用して HTTP 要求を行う

作成者: Kirk Larkin、Steve Gordon、Glenn Condron、Ryan Nowak。

アプリ内で HttpClient インスタンスを構成して作成するために、IHttpClientFactory を登録して使用できます。 IHttpClientFactory には次のような利点があります。

• 論理 HttpClient インスタンスの名前付けと構成を一元化します。 たとえば、GitHub にアクセスするために、github という名前のクライアントを登録して構成できます。 一般的なアクセスのために、既定のクライアントを登録できます。
• HttpClient でのハンドラーのデリゲートにより、送信ミドルウェアの概念が体系化されます。 HttpClient でのハンドラーのデリゲートを利用するために、Polly ベースのミドルウェアに対する拡張機能が提供されます。
• 基になっている HttpClientMessageHandler インスタンスのプールと有効期間が管理されます。 自動管理により、HttpClient の有効期間を手動で管理するときの一般的な DNS (ドメイン ネーム システム) の問題が発生しなくなります。
• ファクトリによって作成されたクライアントから送信されるすべての要求に対し、(ILogger によって) 構成可能なログ エクスペリエンスを追加します。

このトピックのバージョンのサンプル コードでは、HTTP 応答で返された JSON コンテンツを、System.Text.Json を使用して逆シリアル化します。 Json.NET および ReadAsAsync<T> を使用するサンプルについては、バージョン セレクターを使用して、このトピックの 2.x バージョンを選択してください。

利用パターン

アプリで IHttpClientFactory を使用するには複数の方法があります。

• 基本的な使用方法
• 名前付きクライアント
• 型指定されたクライアント
• 生成されたクライアント

どの方法が最善かは、アプリの要件によって異なります。

基本的な使用方法

Program.cs で AddHttpClient を呼び出すことにより、IHttpClientFactory を登録します。

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddHttpClient();

IHttpClientFactory は、依存関係の挿入 (DI) を使用して要求できます。 次のコードでは、IHttpClientFactory を使用して HttpClient インスタンスを作成しています。

public class BasicModel : PageModel
{
    private readonly IHttpClientFactory _httpClientFactory;

    public BasicModel(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        var httpRequestMessage = new HttpRequestMessage(
            HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches")
        {
            Headers =
            {
                { HeaderNames.Accept, "application/vnd.github.v3+json" },
                { HeaderNames.UserAgent, "HttpRequestsSample" }
            }
        };

        var httpClient = _httpClientFactory.CreateClient();
        var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);

        if (httpResponseMessage.IsSuccessStatusCode)
        {
            using var contentStream =
                await httpResponseMessage.Content.ReadAsStreamAsync();
            
            GitHubBranches = await JsonSerializer.DeserializeAsync
                <IEnumerable<GitHubBranch>>(contentStream);
        }
    }
}

前の例のように IHttpClientFactory を使用するのは、既存のアプリをリファクタリングするのに適した方法です。 HttpClient の使用方法に対する影響はありません。 既存のアプリで HttpClient のインスタンスが作成されている場所を、CreateClient の呼び出しに置き換えます。

名前付きクライアント

名前付きクライアントは、次の場合に適しています。

• アプリで、多くの異なる HttpClient を使用する必要がある。
• 多くの HttpClient の構成が異なる。

Program.cs での登録時に、特定の名前の HttpClient に対する構成を指定します。

builder.Services.AddHttpClient("GitHub", httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com/");

    // using Microsoft.Net.Http.Headers;
    // The GitHub API requires two headers.
    httpClient.DefaultRequestHeaders.Add(
        HeaderNames.Accept, "application/vnd.github.v3+json");
    httpClient.DefaultRequestHeaders.Add(
        HeaderNames.UserAgent, "HttpRequestsSample");
});

上記のコードでは、クライアントに次のものが構成されます。

• ベース アドレス https://api.github.com/。
• GitHub API を使用するために必要な 2 つのヘッダー。

CreateClient

CreateClient が呼び出されるたびに、次のことが行われます。

• HttpClient の新しいインスタンスが作成されます。
• 構成アクションが呼び出されます。

名前付きクライアントを作成するには、その名前を CreateClient に渡します。

public class NamedClientModel : PageModel
{
    private readonly IHttpClientFactory _httpClientFactory;

    public NamedClientModel(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        var httpClient = _httpClientFactory.CreateClient("GitHub");
        var httpResponseMessage = await httpClient.GetAsync(
            "repos/dotnet/AspNetCore.Docs/branches");

        if (httpResponseMessage.IsSuccessStatusCode)
        {
            using var contentStream =
                await httpResponseMessage.Content.ReadAsStreamAsync();
            
            GitHubBranches = await JsonSerializer.DeserializeAsync
                <IEnumerable<GitHubBranch>>(contentStream);
        }
    }
}

上記のコードでは、要求でホスト名を指定する必要はありません。 クライアントに構成されているベース アドレスが使用されるため、コードではパスを渡すだけで済みます。

型指定されたクライアント

型指定されたクライアント:

• キーとして文字列を使用する必要なしに、名前付きクライアントと同じ機能を提供します。
• クライアントを使用するときに、IntelliSense とコンパイラのヘルプが提供されます。
• 特定の HttpClient を構成してそれと対話する 1 つの場所を提供します。 たとえば、単一の型指定されたクライアントは、次のために使用される場合があります。
  • 単一のバックエンド エンドポイント用。
  • エンドポイントを処理するすべてのロジックをカプセル化するため。
• DI に対応しており、アプリ内の必要な場所に挿入できます。

型指定されたクライアントは、そのコンストラクターで HttpClient パラメーターを受け取ります。

public class GitHubService
{
    private readonly HttpClient _httpClient;

    public GitHubService(HttpClient httpClient)
    {
        _httpClient = httpClient;

        _httpClient.BaseAddress = new Uri("https://api.github.com/");

        // using Microsoft.Net.Http.Headers;
        // The GitHub API requires two headers.
        _httpClient.DefaultRequestHeaders.Add(
            HeaderNames.Accept, "application/vnd.github.v3+json");
        _httpClient.DefaultRequestHeaders.Add(
            HeaderNames.UserAgent, "HttpRequestsSample");
    }

    public async Task<IEnumerable<GitHubBranch>?> GetAspNetCoreDocsBranchesAsync() =>
        await _httpClient.GetFromJsonAsync<IEnumerable<GitHubBranch>>(
            "repos/dotnet/AspNetCore.Docs/branches");
}

上のコードでは以下の操作が行われます。

• 構成が型指定されたクライアントに移動されます。
• 指定された HttpClient インスタンスは、プライベート フィールドとして格納されます。

HttpClient の機能を公開する API 固有のメソッドを作成できます。 たとえば、GetAspNetCoreDocsBranches メソッドでは、docs GitHub ブランチを取得するためのコードがカプセル化されます。

次のコードでは、Program.cs で AddHttpClient を呼び出して、GitHubService 型指定されたクライアント クラスを登録します。

builder.Services.AddHttpClient<GitHubService>();

型指定されたクライアントは、DI で一時的として登録されます。 上記のコードで、AddHttpClient は GitHubService を一時的なサービスとして登録します。 この登録では、ファクトリ メソッドを使用して次のことを行います。

1. HttpClient のインスタンスを作成します。
2. GitHubService のインスタンスを作成し、HttpClient のインスタンスをそのコンストラクターに渡します。

型指定されたクライアントは、直接挿入して使用できます。

public class TypedClientModel : PageModel
{
    private readonly GitHubService _gitHubService;

    public TypedClientModel(GitHubService gitHubService) =>
        _gitHubService = gitHubService;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        try
        {
            GitHubBranches = await _gitHubService.GetAspNetCoreDocsBranchesAsync();
        }
        catch (HttpRequestException)
        {
            // ...
        }
    }
}

型指定されたクライアントの構成は、型指定されたクライアントのコンストラクターではなく、Program.cs での登録時に指定することもできます。

builder.Services.AddHttpClient<GitHubService>(httpClient =>
{
    httpClient.BaseAddress = new Uri("https://api.github.com/");

    // ...
});

生成されたクライアント

IHttpClientFactory は、Refit などのサードパーティ製ライブラリと組み合わせて使用できます。 Refit は、.NET 用の REST ライブラリです。 REST API をライブ インターフェイスに変換します。 インターフェイスの動的実装を生成するには、AddRefitClient を呼び出します。これにより、HttpClient を使用して外部 HTTP 呼び出しが行われます。

外部 API はカスタム インターフェイスによって表されます。

public interface IGitHubClient
{
    [Get("/repos/dotnet/AspNetCore.Docs/branches")]
    Task<IEnumerable<GitHubBranch>> GetAspNetCoreDocsBranchesAsync();
}

AddRefitClient を呼び出して動的実装を生成した後、ConfigureHttpClient を呼び出して、基になる HttpClient を構成します。

builder.Services.AddRefitClient<IGitHubClient>()
    .ConfigureHttpClient(httpClient =>
    {
        httpClient.BaseAddress = new Uri("https://api.github.com/");

        // using Microsoft.Net.Http.Headers;
        // The GitHub API requires two headers.
        httpClient.DefaultRequestHeaders.Add(
            HeaderNames.Accept, "application/vnd.github.v3+json");
        httpClient.DefaultRequestHeaders.Add(
            HeaderNames.UserAgent, "HttpRequestsSample");
    });

IGitHubClient の動的実装にアクセスするには、DI を使用します。

public class RefitModel : PageModel
{
    private readonly IGitHubClient _gitHubClient;

    public RefitModel(IGitHubClient gitHubClient) =>
        _gitHubClient = gitHubClient;

    public IEnumerable<GitHubBranch>? GitHubBranches { get; set; }

    public async Task OnGet()
    {
        try
        {
            GitHubBranches = await _gitHubClient.GetAspNetCoreDocsBranchesAsync();
        }
        catch (ApiException)
        {
            // ...
        }
    }
}

POST、PUT、DELETE の要求を行う

前の例では、すべての HTTP 要求で GET HTTP 動詞が使用されています。 HttpClient では、次のような他の HTTP 動詞もサポートされています。

• POST
• PUT
• Del
• PATCH

サポートされている HTTP 動詞の一覧については、「HttpMethod」を参照してください。

次の例は、HTTP POST 要求の方法を示しています。

public async Task CreateItemAsync(TodoItem todoItem)
{
    var todoItemJson = new StringContent(
        JsonSerializer.Serialize(todoItem),
        Encoding.UTF8,
        Application.Json); // using static System.Net.Mime.MediaTypeNames;

    using var httpResponseMessage =
        await _httpClient.PostAsync("/api/TodoItems", todoItemJson);

    httpResponseMessage.EnsureSuccessStatusCode();
}

上記のコードの CreateItemAsync メソッドは:

• System.Text.Json を使用して TodoItem パラメーターを JSON にシリアル化します。
• HTTP 要求の本文で送信するためにシリアル化された JSON をパッケージ化する StringContent のインスタンスを作成します。
• PostAsync を呼び出し、指定した URL に JSON コンテンツを送信します。 これは HttpClient.BaseAddress に追加される相対 URL です。
• 応答状態コードが成功を示していない場合に、EnsureSuccessStatusCode を呼び出して例外をスローします。

HttpClient は、他の種類のコンテンツもサポートしています。 たとえば、MultipartContent とStreamContent です。 サポートされているコンテンツの一覧については、「HttpContent」を参照してください。

HTTP PUT 要求の例を次に示します。

public async Task SaveItemAsync(TodoItem todoItem)
{
    var todoItemJson = new StringContent(
        JsonSerializer.Serialize(todoItem),
        Encoding.UTF8,
        Application.Json);

    using var httpResponseMessage =
        await _httpClient.PutAsync($"/api/TodoItems/{todoItem.Id}", todoItemJson);

    httpResponseMessage.EnsureSuccessStatusCode();
}

上記のコードは、POST の例に似ています。 SaveItemAsync メソッドは PostAsync ではなく PutAsync を呼び出します。

HTTP DELETE 要求の例を次に示します。

public async Task DeleteItemAsync(long itemId)
{
    using var httpResponseMessage =
        await _httpClient.DeleteAsync($"/api/TodoItems/{itemId}");

    httpResponseMessage.EnsureSuccessStatusCode();
}

上記のコードの DeleteItemAsync メソッドは DeleteAsync を呼び出します。 HTTP DELETE 要求には通常、本文が含まれていないため、DeleteAsync メソッドは HttpContent のインスタンスを受け入れるオーバーロードを提供しません。

HttpClient でのさまざまな HTTP 動詞の使用の詳細については、「HttpClient」を参照してください。

送信要求ミドルウェア

HttpClient は、送信 HTTP 要求用にリンクできるハンドラーのデリゲートの概念を備えています。 IHttpClientFactory:

• 各名前付きクライアントに適用するハンドラーの定義が簡単になります。
• 送信要求ミドルウェア パイプラインを構築するための複数のハンドラーの登録とチェーン化がサポートされています。 各ハンドラーは、送信要求の前と後に処理を実行できます。 このパターンは次のようなものです。
  • ASP.NET Core での受信ミドルウェア パイプラインに似ています。
  • 次のような HTTP 要求に関する横断的な問題を管理するためのメカニズムが提供されます。
    • キャッシュ
    • エラー処理
    • シリアル化
    • ログ

デリゲート ハンドラーを作成するには、次のようにします。

• DelegatingHandler から派生します。
• SendAsync をオーバーライドします。 パイプライン内の次のハンドラーに要求を渡す前に、コードを実行します。

public class ValidateHeaderHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (!request.Headers.Contains("X-API-KEY"))
        {
            return new HttpResponseMessage(HttpStatusCode.BadRequest)
            {
                Content = new StringContent(
                    "The API key header X-API-KEY is required.")
            };
        }

        return await base.SendAsync(request, cancellationToken);
    }
}

上記のコードでは、X-API-KEY ヘッダーが要求に含まれているかどうかが確認されます。 X-API-KEY がない場合は、BadRequest が返されます。

Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler を使用して HttpClient の構成に複数のハンドラーを追加できます。

builder.Services.AddTransient<ValidateHeaderHandler>();

builder.Services.AddHttpClient("HttpMessageHandler")
    .AddHttpMessageHandler<ValidateHeaderHandler>();

上記のコードでは、ValidateHeaderHandler が DI で登録されます。 登録が済むと、AddHttpMessageHandler を呼び出してハンドラーの型を渡すことができます。

実行する順序で、複数のハンドラーを登録することができます。 最後の HttpClientHandler が要求を実行するまで、各ハンドラーは次のハンドラーをラップします。

builder.Services.AddTransient<SampleHandler1>();
builder.Services.AddTransient<SampleHandler2>();

builder.Services.AddHttpClient("MultipleHttpMessageHandlers")
    .AddHttpMessageHandler<SampleHandler1>()
    .AddHttpMessageHandler<SampleHandler2>();

上のコードでは、SampleHandler1 が最初に (SampleHandler2 より先に) 実行されています。

送信要求ミドルウェアで DI を使用する

IHttpClientFactory によって新しいデリゲート ハンドラーが作成される際、ハンドラーのコンストラクター パラメーターを満たすために DI が使用されます。 IHttpClientFactory により、ハンドラーごとに個別の DI スコープが作成されます。これにより、ハンドラーによって "スコープ付き" サービスが使用されるときに、予期しない動作が発生する可能性があります。

たとえば、識別子 OperationId を持つ操作としてタスクを表す、次のインターフェイスとその実装について考えてみます。

public interface IOperationScoped
{
    string OperationId { get; }
}

public class OperationScoped : IOperationScoped
{
    public string OperationId { get; } = Guid.NewGuid().ToString()[^4..];
}

その名前が示すように、IOperationScoped は "スコープ付き" 有効期間を使用して DI に登録されます。

builder.Services.AddScoped<IOperationScoped, OperationScoped>();

次のデリゲート ハンドラーでは、IOperationScoped を使用して、送信要求用の X-OPERATION-ID ヘッダーを設定します。

public class OperationHandler : DelegatingHandler
{
    private readonly IOperationScoped _operationScoped;

    public OperationHandler(IOperationScoped operationScoped) =>
        _operationScoped = operationScoped;

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.Headers.Add("X-OPERATION-ID", _operationScoped.OperationId);

        return await base.SendAsync(request, cancellationToken);
    }
}

HttpRequestsSample ダウンロードで、/Operation に移動してページを更新します。 要求スコープの値は要求ごとに変更されますが、ハンドラーのスコープの値は 5 秒ごとに変更されるだけです。

ハンドラーは、任意のスコープのサービスに依存することができます。 ハンドラーが依存するサービスは、ハンドラーが破棄されるときに破棄されます。

次の方法のいずれかを使って、要求ごとの状態をメッセージ ハンドラーと共有します。

• HttpRequestMessage.Options を使ってデータをハンドラーに渡します。
• IHttpContextAccessor を使って現在の要求にアクセスします。
• データを渡すカスタムの AsyncLocal<T> ストレージ オブジェクトを作成します。

Polly ベースのハンドラーを使用する

IHttpClientFactory は、サードパーティのライブラリ Polly と統合します。 Polly は、.NET 用の包括的な回復力および一時的エラー処理ライブラリです。 開発者は、自然でスレッド セーフな方法を使用して、Retry、Circuit Breaker、Timeout、Bulkhead Isolation、Fallback などのポリシーを表現できます。

構成されている HttpClient インスタンスで Polly ポリシーを使用できるようにするための、拡張メソッドが提供されています。 Polly の拡張機能では、クライアントへの Polly ベースのハンドラーの追加がサポートされています。 Polly では、Microsoft.Extensions.Http.Polly NuGet パッケージが必要です。

一時的な障害を処理する

通常、外部 HTTP を呼び出すときに発生する障害は、一時的なものです。 AddTransientHttpErrorPolicy では、一時的なエラーを処理するためのポリシーを定義できます。 AddTransientHttpErrorPolicy で構成されたポリシーでは、次の応答が処理されます。

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy では、可能性のある一時的障害を表すエラーを処理するために構成された PolicyBuilder オブジェクトへのアクセスが提供されます。

builder.Services.AddHttpClient("PollyWaitAndRetry")
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.WaitAndRetryAsync(
            3, retryNumber => TimeSpan.FromMilliseconds(600)));

上記のコードでは、WaitAndRetryAsync ポリシーが定義されています。 失敗した要求は最大 3 回再試行され、再試行の間には 600 ミリ秒の遅延が設けられます。

ポリシーを動的に選択する

Polly ベースのハンドラーを追加するための拡張メソッドが提供されています (AddPolicyHandler など)。 次の AddPolicyHandler のオーバーロードでは、要求が検査されて、適用するポリシーが決定されます。

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

builder.Services.AddHttpClient("PollyDynamic")
    .AddPolicyHandler(httpRequestMessage =>
        httpRequestMessage.Method == HttpMethod.Get ? timeoutPolicy : longTimeoutPolicy);

上記のコードでは、送信要求が HTTP GET の場合は、10 秒のタイムアウトが適用されます。 他の HTTP メソッドの場合は、30 秒のタイムアウトが使用されます。

複数の Polly ハンドラーを追加する

Polly のポリシーは入れ子にするのが一般的です。

builder.Services.AddHttpClient("PollyMultiple")
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.RetryAsync(3))
    .AddTransientHttpErrorPolicy(policyBuilder =>
        policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));

前の例の場合:

• 2 つのハンドラーが追加されます。
• 1 つ目のハンドラーでは、AddTransientHttpErrorPolicy を使用して再試行ポリシーが追加されます。 失敗した要求は 3 回まで再試行されます。
• 2 つ目の AddTransientHttpErrorPolicy の呼び出しでは、サーキット ブレーカー ポリシーが追加されます。 試行が連続して 5 回失敗した場合、それ以上の外部要求は 30 秒間ブロックされます。 サーキット ブレーカー ポリシーはステートフルです。 このクライアントからのすべての呼び出しは、同じサーキット状態を共有します。

Polly レジストリからポリシーを追加する

定期的に使用されるポリシーを管理するには、ポリシーを 1 回定義した後、PolicyRegistry でポリシーを登録します。 次に例を示します。

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

var policyRegistry = builder.Services.AddPolicyRegistry();

policyRegistry.Add("Regular", timeoutPolicy);
policyRegistry.Add("Long", longTimeoutPolicy);

builder.Services.AddHttpClient("PollyRegistryRegular")
    .AddPolicyHandlerFromRegistry("Regular");

builder.Services.AddHttpClient("PollyRegistryLong")
    .AddPolicyHandlerFromRegistry("Long");

上のコードでは以下の操作が行われます。

• 2 つのポリシー (Regular と Long) が Polly レジストリに追加されます。
• これらのポリシーを Polly から使用するために、AddPolicyHandlerFromRegistry によって個々の名前付きクライアントを構成します。

IHttpClientFactory と Polly の統合の詳細については、Polly に関する wiki を参照してください。

HttpClient と有効期間の管理

IHttpClientFactory で CreateClient を呼び出すたびに、HttpClient の新しいインスタンスが返されます。 HttpMessageHandler は、名前付きクライアントごとに作成されます。 ファクトリによって HttpMessageHandler インスタンスの有効期間が管理されます。

IHttpClientFactory は、リソースの消費量を減らすため、ファクトリによって作成された HttpMessageHandler のインスタンスをプールします。 新しい HttpClient インスタンスを作成するときに、プールの HttpMessageHandler インスタンスの有効期間が切れていない場合はそれを再利用する場合があります。

通常、各ハンドラーでは基になる HTTP 接続が独自に管理されるため、ハンドラーはプールすることが望まれます。 必要以上のハンドラーを作成すると、接続に遅延が発生する可能性があります。 また、一部のハンドラーでは接続が無期限に開かれており、DNS (ドメイン ネーム システム) の変更にハンドラーが対応できないことがあります。

ハンドラーの既定の有効期間は 2 分です。 名前付きクライアントごとに、既定値をオーバーライドすることができます。

builder.Services.AddHttpClient("HandlerLifetime")
    .SetHandlerLifetime(TimeSpan.FromMinutes(5));

通常、HttpClient インスタンスは、破棄する必要のない .NET オブジェクトとして扱うことができます。 破棄すると送信要求がキャンセルされ、Dispose の呼び出し後には指定された HttpClient インスタンスを使用できなくなります。 IHttpClientFactory は、HttpClient インスタンスによって使用されたリソースの追跡と破棄を行います。

IHttpClientFactory の登場以前は、1 つの HttpClient インスタンスを長い期間使い続けるパターンが一般的に使用されていました。 IHttpClientFactory に移行した後は、このパターンは不要になります。

IHttpClientFactory の代替手段

DI 対応のアプリ内で IHttpClientFactory を使用すれば、次のことを回避できます。

• HttpMessageHandler インスタンスをプールすることによるリソース枯渇の問題。
• 一定の間隔で HttpMessageHandler インスタンスを循環させることによって発生する古くなった DNS の問題。

有効期間の長い SocketsHttpHandler インスタンスを使用して、上記の問題を解決する別の方法があります。

• アプリの起動時に SocketsHttpHandler インスタンスを作成し、アプリの有効期間中、それを使用します。
• DNS の更新時間に基づいて、PooledConnectionLifetime を適切な値に構成します。
• 必要に応じて new HttpClient(handler, disposeHandler: false) を使用して HttpClient インスタンスを作成します。

上記の方法を使用すると、IHttpClientFactory が同様の方法で解決するリソース管理の問題を解決できます。

• SocketsHttpHandler を使用すると、HttpClient インスタンス間で接続を共有できます。 この共有によってソケットの枯渇が防止されます。
• SocketsHttpHandler では、古くなった DNS の問題を回避するために PooledConnectionLifetime に従って接続を循環されます。

ログの記録

IHttpClientFactory によって作成されたクライアントは、すべての要求のログ メッセージを記録します。 既定のログ メッセージを見るには、ログの構成で適切な情報レベルを有効にします。 要求ヘッダーのログなどの追加ログは、トレース レベルでのみ含まれます。

各クライアントに使用されるログのカテゴリには、クライアントの名前が含まれます。 たとえば、MyNamedClient という名前のクライアントでは、"System.Net.Http.HttpClient.MyNamedClient.LogicalHandler" というカテゴリでメッセージがログに記録されます。 LogicalHandler というサフィックスが付いたメッセージが、要求ハンドラーのパイプラインの外部で発生します。 要求では、パイプライン内の他のハンドラーが要求を処理する前に、メッセージがログに記録されます。 応答では、他のパイプライン ハンドラーが応答を受け取った後で、メッセージがログに記録されます。

ログ記録は、要求ハンドラーのパイプラインの内部でも行われます。 MyNamedClient の例では、これらのメッセージはログ カテゴリ "System.Net.Http.HttpClient.MyNamedClient.ClientHandler" でログに記録されます。 要求では、他のすべてのハンドラーが実行された後、要求が送信される直前に、これが行われます。 応答では、このログ記録には、ハンドラー パイプラインを通じ戻される前の応答の状態が含まれます。

パイプラインの外部と内部でログを有効にすると、他のパイプライン ハンドラーによる変更を検査できます。 これには、要求ヘッダーや応答状態コードへの変更を含めることができます。

ログのカテゴリにクライアントの名前を含めると、特定の名前付きクライアントでログをフィルター処理できます。

HttpMessageHandler を構成する

クライアントによって使用される内部 HttpMessageHandler の構成を制御することが必要な場合があります。

名前付きクライアントまたは型指定されたクライアントを追加すると、IHttpClientBuilder が返されます。 ConfigurePrimaryHttpMessageHandler 拡張メソッドを使用して、デリゲートを定義することができます。 デリゲートは、そのクライアントによって使用されるプライマリ HttpMessageHandler の作成と構成に使用されます。

builder.Services.AddHttpClient("ConfiguredHttpMessageHandler")
    .ConfigurePrimaryHttpMessageHandler(() =>
        new HttpClientHandler
        {
            AllowAutoRedirect = true,
            UseDefaultCredentials = true
        });

Cookies

HttpMessageHandler インスタンスをプールすると、CookieContainer オブジェクトが共有されます。 予期せぬ CookieContainer オブジェクト共有があると、多くの場合、コードは不適切なものとなります。 cookie を必要とするアプリの場合は、次のいずれかを検討してください。

• 自動的な cookie 処理の無効化
• IHttpClientFactory の回避

ConfigurePrimaryHttpMessageHandler を呼び出して、自動的な cookie 処理を無効にします。

builder.Services.AddHttpClient("NoAutomaticCookies")
    .ConfigurePrimaryHttpMessageHandler(() =>
        new HttpClientHandler
        {
            UseCookies = false
        });

コンソール アプリで IHttpClientFactory を使用する

コンソール アプリで、次のパッケージ参照をプロジェクトに追加します。

• Microsoft.Extensions.Hosting
• Microsoft.Extensions.Http

次に例を示します。

• IHttpClientFactory と GitHubService は、汎用ホストのサービス コンテナーに登録されます。
• GitHubService は DI から要求され、その後、IHttpClientFactory のインスタンスを要求します。
• GitHubService は IHttpClientFactory を使用して HttpClient のインスタンスを作成します。これは、docs GitHub ブランチを取得するために使用されます。

using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddHttpClient();
        services.AddTransient<GitHubService>();
    })
    .Build();

try
{
    var gitHubService = host.Services.GetRequiredService<GitHubService>();
    var gitHubBranches = await gitHubService.GetAspNetCoreDocsBranchesAsync();

    Console.WriteLine($"{gitHubBranches?.Count() ?? 0} GitHub Branches");

    if (gitHubBranches is not null)
    {
        foreach (var gitHubBranch in gitHubBranches)
        {
            Console.WriteLine($"- {gitHubBranch.Name}");
        }
    }
}
catch (Exception ex)
{
    host.Services.GetRequiredService<ILogger<Program>>()
        .LogError(ex, "Unable to load branches from GitHub.");
}

public class GitHubService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public GitHubService(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public async Task<IEnumerable<GitHubBranch>?> GetAspNetCoreDocsBranchesAsync()
    {
        var httpRequestMessage = new HttpRequestMessage(
            HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches")
        {
            Headers =
            {
                { "Accept", "application/vnd.github.v3+json" },
                { "User-Agent", "HttpRequestsConsoleSample" }
            }
        };

        var httpClient = _httpClientFactory.CreateClient();
        var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);

        httpResponseMessage.EnsureSuccessStatusCode();

        using var contentStream =
            await httpResponseMessage.Content.ReadAsStreamAsync();
        
        return await JsonSerializer.DeserializeAsync
            <IEnumerable<GitHubBranch>>(contentStream);
    }
}

public record GitHubBranch(
    [property: JsonPropertyName("name")] string Name);

ヘッダー伝達ミドルウェア

ヘッダー伝達は、受信要求から送信 HttpClient 要求に HTTP ヘッダーを伝達するための ASP.NET Core ミドルウェアです。 ヘッダー伝達を使用するには、次を行います。

• Microsoft.AspNetCore.HeaderPropagation パッケージをインストールします。

• Program.cs で HttpClient とミドルウェア パイプラインを構成します。

  // Add services to the container.
  builder.Services.AddControllers();
  
  builder.Services.AddHttpClient("PropagateHeaders")
      .AddHeaderPropagation();
  
  builder.Services.AddHeaderPropagation(options =>
  {
      options.Headers.Add("X-TraceId");
  });
  
  var app = builder.Build();
  
  // Configure the HTTP request pipeline.
  app.UseHttpsRedirection();
  
  app.UseHeaderPropagation();
  
  app.MapControllers();
  

• 構成済みの HttpClient インスタンス (追加されたヘッダーを含む) を使用して、送信要求を行います。

その他のリソース

• サンプル コードを表示またはダウンロードします (ダウンロード方法)。
• HttpClientFactory を使用して回復力の高い HTTP 要求を実装する
• HttpClientFactory ポリシーと Polly ポリシーで指数バックオフを含む HTTP 呼び出しの再試行を実装する
• サーキット ブレーカー パターンを実装する
• .NET で JSON のシリアル化と逆シリアル化を行う方法