在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求

由 Kirk Larkin、Steve Gordon、Glenn Condron 和 Ryan Nowak 撰寫。

IHttpClientFactory 可以註冊及用來在應用程式中設定和建立 HttpClient 執行個體。 IHttpClientFactory 提供下列優點：

• 提供一個集中位置以便命名和設定邏輯 HttpClient 執行個體。 例如，可註冊及設定名為 github 的用戶端，來存取 GitHub。 預設用戶端可以註冊用於一般存取。
• 透過委派 HttpClient 中的處理常式來撰寫傳出中介軟體的概念。 提供適用於 Polly 型中介軟體的延伸模組，以利用 HttpClient 中的委派處理常式。
• 管理基礎 HttpClientMessageHandler 執行個體的共用和存留期。 自動管理可避免在手動管理 HttpClient 存留期時，所發生的常見網域名稱系統 (DNS) 問題。
• 針對透過處理站所建立之用戶端傳送的所有要求，新增可設定的記錄體驗 (透過 ILogger)。

本主題版本中的範例程式碼會使用 System.Text.Json 來還原序列化 HTTP 回應中所傳回的 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();

可以使用相依性注入 (DI) 來要求 IHttpClientFactory。 下列程式碼會使用 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 所需的兩個標頭。

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 並與其互動。 例如，可能會使用單一型別用戶端：
  • 針對單一後端端點。
  • 封裝處理端點的所有邏輯。
• 使用 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 方法會封裝程式碼，以擷取文件 GitHub 分支。

下列程式碼會呼叫 Program.cs 中的 AddHttpClient，以註冊具 GitHubService 類型的用戶端類別：

builder.Services.AddHttpClient<GitHubService>();

具型別用戶端會向 DI 註冊為暫時性。 在上述程式碼中，AddHttpClient 會將 GitHubService 註冊為暫時性服務。 此註冊會使用 Factory 方法：

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

使用 DI 存取 IGitHubClient 的動態實作：

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
• DELETE
• 修補檔

如需支援 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。
• 建立 StringContent 的執行個體來封裝序列化的 JSON，以在 HTTP 要求本文中傳送。
• 呼叫 PostAsync，將 JSON 內容傳送至指定的 URL。 這是新增至 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 方法會呼叫 PutAsync，而不是 PostAsync。

下列範例顯示 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 要求的跨領域考量，例如：
    • 快取
    • 錯誤處理
    • 序列化
    • logging

若要建立委派處理常式：

• 從 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 的完整恢復功能和暫時性錯誤處理程式庫。 它可讓開發人員以流暢且執行緒安全的方式表達原則，例如重試、斷路器、逾時、艙隔離與後援。

提供擴充方法來啟用使用 Polly 原則搭配設定的 HttpClient 執行個體。 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 原則。 失敗的要求會重試最多三次，並且在嘗試之間會有 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)));

在前述範例中:

• 會新增兩個處理常式。
• 第一個處理常式會使用 AddTransientHttpErrorPolicy 來新增重試原則。 失敗的要求會重試最多三次。
• 第二個 AddTransientHttpErrorPolicy 呼叫會新增斷路器原則。 如果循序發生五次失敗的嘗試，進一步的外部要求會遭到封鎖 30 秒。 斷路器原則可設定狀態。 透過此用戶端的所有呼叫都會共用相同的線路狀態。

從 Polly 登錄新增原則

管理定期使用原則的一個方法是定義一次，並向 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");

在上述程式碼中：

• 兩個原則 (Regular 和 Long) 會新增至 Polly 登錄。
• AddPolicyHandlerFromRegistry 會設定個別具名用戶端，以從 Polly 登錄使用這些原則。

如需 IHttpClientFactory 和 Polly 整合的詳細資訊，請參閱 Polly wiki。

HttpClient 和存留期管理

每次在 IHttpClientFactory 上呼叫 CreateClient 時，都會傳回新的 HttpClient 執行個體。 HttpMessageHandler 會根據具名用戶端建立。 處理站會管理 HttpMessageHandler 執行個體的存留期。

IHttpClientFactory 會將處理站所建立的 HttpMessageHandler 執行個體放入集區以減少資源耗用量。 建立新的 HttpClient 執行個體時，如果其存留期間尚未過期，HttpMessageHandler 執行個體可從集區重複使用。

將處理常式放入集區非常實用，因為處理常式通常會管理自己專屬的底層 HTTP 連線。 建立比所需數目更多的處理常式，可能會導致連線延遲。 有些處理常式也會保持連線無限期地開啟，這可能導致處理常式無法對 DNS (網域名稱系統) 變更回應。

預設處理常式存留時間為兩分鐘。 可以針對每個具名用戶端覆寫預設值：

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

HttpClient 執行個體通常可視為 .NET 物件，不需要處置。 處置會取消傳出的要求，並保證指定的 HttpClient 執行個體在呼叫 Dispose 之後無法使用。 IHttpClientFactory 會追蹤並處置 HttpClient 執行個體使用的資源。

在開始使用 IHttpClientFactory 之前，讓單一 HttpClient 執行個體維持一段較長的時間，是很常使用的模式。 在移轉到 IHttpClientFactory 之後，就不再需要此模式。

IHttpClientFactory 的替代方案

在已啟用 DI 的應用程式中使用 IHttpClientFactory 可避免：

• 共用 HttpMessageHandler 實例的資源耗盡問題。
• 定期回收 HttpMessageHandler 實例的過時 DNS 問題。

使用長期 SocketsHttpHandler 實例來解決上述問題的替代方式。

• 在應用程式啟動時建立 SocketsHttpHandler 的實例，並將其用於應用程式生命週期。
• 根據 DNS 重新整理次數，將 PooledConnectionLifetime 設定為適當的值。
• 視需要使用 new HttpClient(handler, disposeHandler: false) 建立 HttpClient 實例。

上述方法可解決資源管理問題，IHttpClientFactory 會以類似方式解決。

• SocketsHttpHandler 會共用 HttpClient 實例之間的連線。 此共用可防止通訊端耗盡。
• SocketsHttpHandler 會根據 PooledConnectionLifetime 來回收連線，以避免發生過時的 DNS 問題。

記錄

透過 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
        });

Cookie

集區式 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 要求，而該 DI 會接著要求 的 IHttpClientFactory 實例。
• GitHubService 會使用 IHttpClientFactory 來建立 HttpClient 實例，用來擷取文件 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);

標頭傳播中介軟體

標頭傳播是一種 ASP.NET Core 中介軟體，可從傳入要求將 HTTP 標頭傳播至傳出 HttpClient 要求。 若要使用標頭傳播：

• 安裝 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