在 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），適用於工廠建立的所有客戶端之請求。

本文說明如何在 ASP.NET Core應用程式中使用 IHttpClientFactory 來發送 HTTP 請求。 範例程式碼版本用於 System.Text.Json 反序列化 HTTP 回應中回傳的 JSON 內容。 對於使用 Json.NET 和 ReadAsAsync<T> 的範例，請使用瀏覽器的 Version 選擇器選擇本條目的 2.x 版本。

檢視消費模式

有數種方式可將 IHttpClientFactory 用於應用程式：

• 基本用法
• 具名客戶
• 類型化用戶端
• 產生的用戶端

最好的方法取決於應用程式的需求。

基本用法

在 Program.cs 檔案中呼叫方法來註冊。

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

在範例中，呼叫 to IHttpClientFactory 是重構現有應用程式的好方法。 這種做法不會影響使用方式 HttpClient 。

在現有 HttpClient 應用程式中建立實例的情況，請將這些實例替換為呼叫 CreateClient。

指定用戶端

命名用戶端適用於以下情境：

• 應用程式需要許多不同的 HttpClient 用法。
• 有許多不同配置的HttpClient實例。

在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分支檢索文檔。

以下程式碼在 AddHttpClient 檔案中呼叫以註冊GitHubService型別的客戶端類別：

builder.Services.AddHttpClient<GitHubService>();

具類型化的客戶端會在依賴注入（DI）中註冊為瞬態。 在程式碼片段中，該 AddHttpClient 方法被 GitHubService 註冊為暫態服務。 此註冊會使用工廠方法來：

• 建立 HttpClient 的執行個體。
• 建立一個 的 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
• 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 格式。
• 建立一個 StringContent 實例，將序列化的 JSON 打包進 HTTP 請求主體。
• 呼叫 PostAsync 來將 JSON 內容傳送到指定的網址。 這個值是相對的 URL，將被添加到 HttpClient.BaseAddress。
• 呼叫 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 請求相關的跨領域問題，例如快取、錯誤處理、序列化及日誌記錄。

若要建立委派處理常式：

• 源自 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 碼。

可以透過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 秒變更一次。

處理常式可以依賴任何範疇的服務。 當處理器被處置時，其相依的服務也會被處置。

使用下列其中一種方式來與訊息處理常式共用每個請求的狀態：

• 請使用 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");

程式碼片段為 Polly 註冊表新增兩個策略，Regular 和 Long。 程式碼呼叫AddPolicyHandlerFromRegistry來配置個別命名的客戶端，以使用這些來自 Polly 註冊表的政策。

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

HttpClient 和存留期管理

每次在 HttpClient 上呼叫 CreateClient，都會返回一個新的 IHttpClientFactory 實例。 為每個指定的客戶建立一個 HttpMessageHandler。 工廠負責管理 HttpMessageHandler 執行個體的存留期。

IHttpClientFactory 會將處理站所建立的 HttpMessageHandler 執行個體放入集區以減少資源耗用量。 如果HttpMessageHandler實例的壽命尚未過期，那麼在建立新HttpClient實例時，該實例可能會從池中重新使用。

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

預設的處理器壽命是 2 分鐘。 預設值可依每個命名的用戶端來覆寫：

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

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

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

探索 IHttpClientFactory 的替代方案

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

• 藉由集結 HttpMessageHandler 實例來解決資源耗盡的問題。
• 解決過時的 DNS 問題，方法是定期循環 HttpMessageHandler 實例。

還有其他方法可以利用長壽命 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
        });

處理 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 要求，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 package.

• 在 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 序列化與反序列化