在 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 实例存储为私有字段。

可以创建特定于 API 的方法来公开 HttpClient 功能。 例如，创建 GetAspNetCoreDocsBranches 方法来封装代码以检索文档 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");
    });

使用 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
• 删除
• 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 的相对 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 实例的重载。

要详细了解如何将不同的 HTTP 谓词用于 HttpClient，请参阅 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>();

在上述代码中通过 DI 注册了 ValidateHeaderHandler。 注册后可以调用 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..];
}

顾名思义，使用限定范围的生存期向 DI 注册 IOperationScoped：

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 的全面恢复和临时故障处理库。 开发人员通过它可以表达策略，例如以流畅且线程安全的方式处理重试、断路器、超时、Bulkhead 隔离和回退。

提供了扩展方法，以实现将 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 ms。

动态选择策略

提供了扩展方法来添加基于 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 调用添加断路器策略。 如果尝试连续失败了 5 次，则会阻止后续外部请求 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 对象。 处置既取消传出请求，又保证在调用 Dispose 后无法使用给定的 HttpClient 实例。 IHttpClientFactory 跟踪和处置 HttpClient 实例使用的资源。

保持各个 HttpClient 实例长时间处于活动状态是在 IHttpClientFactory 推出前使用的常见模式。 迁移到 IHttpClientFactory 后，就无需再使用此模式。

IHttpClientFactory 的替代项

通过在启用了 DI 的应用中使用 IHttpClientFactory，可避免：

• 通过共用 HttpMessageHandler 实例，解决资源耗尽问题。
• 通过定期循环 HttpMessageHandler 实例，解决 DNS 过时问题。

此外，还有其他方法使用生命周期长的 SocketsHttpHandler 实例来解决上述问题。

• 在应用启动时创建 SocketsHttpHandler 的实例，并在应用的整个生命周期中使用它。
• 根据 DNS 刷新时间，将 PooledConnectionLifetime 配置为适当的值。
• 根据需要，使用 new HttpClient(handler, disposeHandler: false) 创建 HttpClient 实例。

上述方法使用 IHttpClientFactory 解决问题的类似方式解决资源管理问题。

• SocketsHttpHandler 在 HttpClient 实例之间共享连接。 此共享可防止套接字耗尽。
• SocketsHttpHandler 会根据 PooledConnectionLifetime 循环连接，避免出现 DNS 过时问题。

Logging

通过 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 包。

• 在 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 数据进行序列化和反序列化