Fazer solicitações HTTP usando IHttpClientFactory no ASP.NET Core

Por Kirk Larkin, Steve Gordon, Glenn Condron e Ryan Nowak.

É possível registrar e usar um IHttpClientFactory para configurar e criar instâncias de HttpClient em um aplicativo. IHttpClientFactory oferece os seguintes benefícios:

• Fornece um local central para nomear e configurar instâncias lógicas de HttpClient. Por exemplo, um cliente chamado github pode ser registrado e configurado para acessar o GitHub. Um cliente padrão pode ser registrado para ter acesso geral.
• Codifica o conceito de middleware de saída por meio da delegação de manipuladores em HttpClient. Fornece extensões para o middleware baseado em Polly para aproveitar a delegação de manipuladores em HttpClient.
• Gerencia o pooling e o tempo de vida das instâncias HttpClientMessageHandler subjacentes. O gerenciamento automático evita problemas comuns do DNS (Sistema de Nomes de Domínio) que ocorrem ao gerenciar manualmente os tempos de vida HttpClient.
• Adiciona uma experiência de registro em log configurável (via ILogger) para todas as solicitações enviadas por meio de clientes criados pelo alocador.

O código de exemplo nesta versão do tópico usa System.Text.Json para desserializar o conteúdo JSON retornado em respostas HTTP. Para exemplos que usam Json.NET e ReadAsAsync<T>, use o seletor de versão a fim de selecionar uma versão 2.x deste tópico.

Padrões de consumo

Há várias maneiras de usar o IHttpClientFactory em um aplicativo:

• Uso básico
• Clientes nomeados
• Clientes com tipo
• Clientes gerados

A melhor abordagem depende dos requisitos do aplicativo.

Uso básico

Registre IHttpClientFactory chamando AddHttpClient no Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Um IHttpClientFactory pode ser solicitado com o uso de DI (injeção de dependência). O código a seguir usa IHttpClientFactory para criar uma instância 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);
        }
    }
}

Usar IHttpClientFactory como no exemplo anterior é uma boa maneira de refatorar um aplicativo existente. Não há nenhum impacto na maneira em que HttpClient é usado. Em locais em que as instâncias HttpClient são criadas em um aplicativo existente, substitua essas ocorrências por chamadas para CreateClient.

Clientes nomeados

Clientes nomeados são uma boa opção quando:

• O aplicativo requer muitos usos distintos de HttpClient.
• Muitos HttpClients têm configuração diferente.

Especifique a configuração de um HttpClient nomeado durante seu registro no Program.cs:

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

No código anterior, o cliente é configurado com:

• O endereço básico https://api.github.com/.
• Dois cabeçalhos exigidos para trabalhar com a API do GitHub.

CreateClient

Cada vez que CreateClient é chamado:

• Uma nova instância de HttpClient é criada.
• A ação de configuração é chamada.

Para criar um cliente nomeado, passe o nome dele para 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);
        }
    }
}

No código anterior, a solicitação não precisa especificar um nome do host. O código pode passar apenas o caminho, pois o endereço básico configurado para o cliente é usado.

Clientes com tipo

Clientes com tipo:

• Fornecem as mesmas funcionalidade que os clientes nomeados sem a necessidade de usar cadeias de caracteres como chaves.
• Fornecem a ajuda do IntelliSense e do compilador durante o consumo de clientes.
• Fornecem um único local para configurar e interagir com um determinado HttpClient. Por exemplo, um único cliente com tipo pode ser usado:
  • Para um único ponto de extremidade de back-end.
  • Para encapsular toda a lógica que lida com o ponto de extremidade.
• Funcionam com a DI e podem ser injetados no local necessário no aplicativo.

Um cliente com tipo aceita um parâmetro HttpClient em seu construtor:

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

No código anterior:

• A configuração é movida para o cliente tipado.
• A instância HttpClient fornecida é armazenada como um campo privado.

Métodos específicos da API podem ser criados que expõem a funcionalidade HttpClient. Por exemplo, o método GetAspNetCoreDocsBranches encapsula o código para recuperar branches do GitHub de documentos.

O código a seguir chamaAddHttpClient em Program.cs para registrar uma classe de cliente tipado GitHubService:

builder.Services.AddHttpClient<GitHubService>();

O cliente com tipo é registrado como transitório com a DI. No código anterior, AddHttpClient registra GitHubService como um serviço transitório. Esse registro usa um método de fábrica para:

1. Crie uma instância de HttpClient.
2. Crie uma instância de GitHubService, passando a instância de HttpClient para seu construtor.

O cliente com tipo pode ser injetado e consumido diretamente:

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)
        {
            // ...
        }
    }
}

Se preferir, a configuração de um cliente com tipo também poderá ser especificada durante o registro em Program.cs e não no construtor do cliente com tipo:

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

    // ...
});

Clientes gerados

IHttpClientFactory pode ser usado em combinação com bibliotecas de terceiros, como a Refit. A readequação é uma biblioteca REST para .NET. Ela converte APIs REST em interfaces dinâmicas. Chame AddRefitClient para gerar uma implementação dinâmica de uma interface, que usa HttpClient para fazer as chamadas HTTP externas.

Uma interface personalizada representa a API externa:

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

Chame AddRefitClient para gerar a implementação dinâmica e, em seguida, chame ConfigureHttpClient para configurar o HttpClient subjacente:

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

Use a DI para acessar a implementação dinâmica de 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)
        {
            // ...
        }
    }
}

Fazer solicitações POST, PUT e DELETE

Nos exemplos anteriores, todas as solicitações HTTP usam o verbo HTTP GET. HttpClient também dá suporte a outros verbos HTTP, incluindo:

• POST
• PUT
• DELETE
• PATCH

Para obter uma lista completa de verbos HTTP compatíveis, consulte HttpMethod.

O exemplo abaixo mostra como fazer uma solicitação 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();
}

No código anterior, o método CreateItemAsync:

• Serializa o parâmetro TodoItem para JSON usando System.Text.Json.
• Cria uma instância de StringContent para empacotar o JSON serializado para enviar o corpo da solicitação HTTP.
• Chama PostAsync para enviar o conteúdo JSON para a URL especificada. Essa é uma URL relativa que é adicionada ao HttpClient.BaseAddress.
• Chama EnsureSuccessStatusCode para gerar uma exceção se o código de status de resposta não indicar êxito.

HttpClient também dá suporte a outros tipos de conteúdo. Por exemplo, MultipartContent e StreamContent. Para obter uma lista completa dos dispositivos com suporte, consulte HttpContent.

O exemplo abaixo mostra uma solicitação 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();
}

O código anterior é semelhante ao exemplo POST. O método SaveItemAsync chama PutAsync em vez de PostAsync.

O exemplo abaixo mostra uma solicitação HTTP DELETE:

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

    httpResponseMessage.EnsureSuccessStatusCode();
}

No código anterior, o método DeleteItemAsync chama DeleteAsync. Como as solicitações HTTP DELETE normalmente não contêm corpo, o método DeleteAsync não fornece uma sobrecarga que aceita uma instância de HttpContent.

Para saber mais sobre como usar verbos HTTP diferentes com HttpClient, consulte HttpClient.

Middleware de solicitação de saída

O HttpClient tem o conceito de delegar manipuladores que podem ser vinculados para solicitações HTTP de saída. IHttpClientFactory:

• Simplifica a definição dos manipuladores a serem aplicados a cada cliente nomeado.
• Ele permite o registro e o encadeamento de vários manipuladores para criar um pipeline do middleware de solicitação saída. Cada um desses manipuladores é capaz de executar o trabalho antes e após a solicitação de saída. Este padrão:
  • É semelhante ao pipeline do middleware de entrada no ASP.NET Core.
  • Fornece um mecanismo para gerenciar questões entre cortes relativas a solicitações HTTP, por exemplo:
    • cache
    • tratamento de erros
    • serialização
    • registro em log

Para criar um identificador de delegação:

• Derive de DelegatingHandler.
• Substitua SendAsync. Execute o código antes de passar a solicitação para o próximo manipulador no pipeline:

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

O código anterior verifica se o cabeçalho X-API-KEY está na solicitação. Se X-API-KEY estiver ausente, BadRequest será retornado.

Mais de um manipulador pode ser adicionado à configuração de um HttpClient com Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler:

builder.Services.AddTransient<ValidateHeaderHandler>();

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

No código anterior, o ValidateHeaderHandler é registrado com a DI. Depois de registrado, o AddHttpMessageHandler poderá ser chamado, passando o tipo para o manipulador.

Vários manipuladores podem ser registrados na ordem em que eles devem ser executados. Cada manipulador encapsula o próximo manipulador até que o HttpClientHandler final execute a solicitação:

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

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

No código anterior, SampleHandler1 é executado primeiro, antes de SampleHandler2.

Usar DI no middleware de solicitação de saída

Quando IHttpClientFactory cria um manipulador de delegação, ele usa DI para atender aos parâmetros do construtor do manipulador. IHttpClientFactory cria um escopo de DI separado para cada manipulador, o que pode levar a um comportamento surpreendente quando um manipulador consome um serviço com escopo.

Por exemplo, considere a seguinte interface e sua implementação, que representa uma tarefa como uma operação com um manipulador, OperationId:

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Como o nome sugere, IOperationScoped é registrado com DI usando um tempo de vida com escopo:

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

O seguinte manipulador de delegação consome e usa IOperationScoped a fim de definir o cabeçalho X-OPERATION-ID para a solicitação de saída:

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

No download de HttpRequestsSample, navegue até /Operation e atualize a página. O valor do escopo da solicitação é alterado para cada solicitação, mas o valor do escopo do manipulador muda apenas a cada 5 segundos.

Os manipuladores podem depender de serviços de qualquer escopo. Os serviços dos quais os manipuladores dependem são descartados quando o manipulador é descartado.

Use uma das seguintes abordagens para compartilhar o estado por solicitação com os manipuladores de mensagens:

• Passe os dados pelo manipulador usando HttpRequestMessage.Options.
• Use IHttpContextAccessor para acessar a solicitação atual.
• Crie um objeto de armazenamento AsyncLocal<T> personalizado para passar os dados.

Usar manipuladores baseados no Polly

IHttpClientFactory integra-se à biblioteca de terceiros Polly. O Polly é uma biblioteca abrangente de tratamento de falha transitória e de resiliência para .NET. Ela permite que os desenvolvedores expressem políticas, como Repetição, Disjuntor, Tempo Limite, Isolamento de Bulkhead e Fallback de maneira fluente e thread-safe.

Os métodos de extensão são fornecidos para habilitar o uso de políticas do Polly com instâncias de HttpClient configuradas. As extensões do Polly dão suporte à adição de manipuladores baseados em Polly aos clientes. Polly requer o pacote NuGet Microsoft.Extensions.Http.Polly.

Tratar falhas transitórias

As falhas normalmente ocorrem quando as chamadas HTTP externas são transitórias. AddTransientHttpErrorPolicy permite que uma política seja definida para lidar com erros transitórios. As políticas configuradas com AddTransientHttpErrorPolicy manipulam as seguintes respostas:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy fornece acesso a um objeto PolicyBuilder configurado para tratar erros que representam uma possível falha transitória:

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

No código anterior, uma política WaitAndRetryAsync é definida. As solicitações com falha são repetidas até três vezes com um atraso de 600 ms entre as tentativas.

Selecionar políticas dinamicamente

Métodos de extensão são fornecidos para adicionar manipuladores baseados em Polly, por exemplo, AddPolicyHandler. A seguinte sobrecarga de AddPolicyHandler inspeciona a solicitação para decidir qual política aplicar:

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

No código anterior, se a solicitação de saída é um HTTP GET, um tempo limite de 10 segundos é aplicado. Para qualquer outro método HTTP, é usado um tempo limite de 30 segundos.

Adicionar vários manipuladores do Polly

É comum aninhar políticas Polly:

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

No exemplo anterior:

• Dois manipuladores são adicionados.
• O primeiro manipulador usa AddTransientHttpErrorPolicy para adicionar uma política de repetição. As solicitações com falha são repetidas até três vezes.
• A segunda chamada AddTransientHttpErrorPolicy adiciona uma política de disjuntor. As solicitações externas adicionais são bloqueadas por 30 segundos quando ocorrem 5 tentativas com falha consecutivamente. As políticas de disjuntor são políticas com estado. Todas as chamadas por meio desse cliente compartilham o mesmo estado do circuito.

Adicionar políticas do registro do Polly

Uma abordagem para gerenciar as políticas usadas com frequência é defini-las uma única vez e registrá-las em um PolicyRegistry. Por exemplo:

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

No código anterior:

• Duas políticas, Regular e Long, são adicionadas ao registro do Polly.
• AddPolicyHandlerFromRegistry configura clientes nomeados individuais para usar essas políticas do registro do Polly.

Para obter mais informações sobre as integrações IHttpClientFactory e Polly, confira o wiki do Polly.

HttpClient e gerenciamento de tempo de vida

Uma nova instância de HttpClient é chamada, sempre que CreateClient é chamado na IHttpClientFactory. Um HttpMessageHandler é criado por cliente nomeado. O alocador gerencia a vida útil das instâncias do HttpMessageHandler.

IHttpClientFactory cria pools com as instâncias de HttpMessageHandler criadas pelo alocador para reduzir o consumo de recursos. Uma instância de HttpMessageHandler poderá ser reutilizada no pool, ao criar uma nova instância de HttpClient, se o respectivo tempo de vida não tiver expirado.

O pooling de manipuladores é preferível porque normalmente cada manipulador gerencia as próprias conexões HTTP subjacentes. Criar mais manipuladores do que o necessário pode resultar em atrasos de conexão. Alguns manipuladores também mantêm as conexões abertas indefinidamente, o que pode impedir que o manipulador reaja a alterações de DNS (Sistema de Nomes de Domínio).

O tempo de vida padrão do manipulador é de 2 minutos. O valor padrão pode ser substituído para cada cliente nomeado:

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

Geralmente, as instâncias de HttpClient podem ser tratadas como objetos do .NET que não exigem descarte. O descarte cancela as solicitações de saída e garante que a determinada instância de HttpClient não seja usada depois de chamar Dispose. IHttpClientFactory rastreia e descarta recursos usados pelas instâncias de HttpClient.

Manter uma única instância de HttpClient ativa por uma longa duração é um padrão comum usado, antes do início de IHttpClientFactory. Esse padrão se torna desnecessário após a migração para IHttpClientFactory.

Alternativas ao IHttpClientFactory

O uso de IHttpClientFactory em um aplicativo habilitado para DI evita:

• Problemas de esgotamento de recursos ao agrupar instâncias HttpMessageHandler.
• Problemas de DNS obsoletos com a reciclagem de instâncias HttpMessageHandler em intervalos regulares.

Há maneiras alternativas de resolver os problemas anteriores usando uma instância de SocketsHttpHandler de longa duração.

• Crie uma instância de SocketsHttpHandler quando o aplicativo iniciar e use-a na vida útil do aplicativo.
• Configure PooledConnectionLifetime com um valor apropriado com base nos tempos de atualização de DNS.
• Crie instâncias HttpClient usando new HttpClient(handler, disposeHandler: false) conforme a necessidade.

As abordagens anteriores resolvem os problemas de gerenciamento de recursos que IHttpClientFactory resolve de maneira semelhante.

• O SocketsHttpHandler compartilha conexões entre instâncias de HttpClient. Esse compartilhamento impede o esgotamento do soquete.
• O SocketsHttpHandler recicla conexões de acordo com PooledConnectionLifetime para evitar problemas de DNS obsoletos.

Log

Os clientes criado pelo IHttpClientFactory registram mensagens de log para todas as solicitações. Habilite o nível apropriado de informações na configuração de log para ver as mensagens de log padrão. Os registros em log adicionais, como o registro em log dos cabeçalhos de solicitação, estão incluídos somente no nível de rastreamento.

A categoria de log usada para cada cliente inclui o nome do cliente. Um cliente chamado MyNamedClient, por exemplo, registra mensagens com uma categoria de "System.Net.Http.HttpClient.MyNamedClient.LogicalHandler". Mensagens sufixadas com LogicalHandler ocorrem fora do pipeline do manipulador de solicitações. Na solicitação, as mensagens são registradas em log antes que qualquer outro manipulador no pipeline a tenha processado. Na resposta, as mensagens são registradas depois que qualquer outro manipulador do pipeline tenha recebido a resposta.

O registro em log também ocorre dentro do pipeline do manipulador de solicitações. No exemplo MyNamedClient, essas mensagens são registradas com a categoria de log "System.Net.Http.HttpClient.MyNamedClient.ClientHandler". Para a solicitação, isso ocorre depois que todos os outros manipuladores são executados e imediatamente antes que a solicitação seja enviada. Na resposta, esse registro em log inclui o estado da resposta antes que ela seja retornada por meio do pipeline do manipulador.

Habilitar o registro em log dentro e fora do pipeline permite a inspeção das alterações feitas por outros manipuladores do pipeline. Isso pode incluir alterações nos cabeçalhos de solicitação ou no código de status da resposta.

Incluir o nome do cliente na categoria de log permite a filtragem de log para clientes nomeados específicos.

Configurar o HttpMessageHandler

Talvez seja necessário controlar a configuração do HttpMessageHandler interno usado por um cliente.

Um IHttpClientBuilder é retornado ao adicionar clientes nomeados ou com tipo. O método de extensão ConfigurePrimaryHttpMessageHandler pode ser usado para definir um representante. O representante que é usado para criar e configurar o HttpMessageHandler primário usado pelo cliente:

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

Cookies

As instâncias de HttpMessageHandler em pool resultam no compartilhamento de CookieContainer. O compartilhamento do objeto CookieContainer de forma inesperada geralmente resulta em código incorreto. Para aplicativos que exigem cookies, considere:

• Desabilitar o tratamento automático de cookie
• Evitar IHttpClientFactory

Chamar ConfigurePrimaryHttpMessageHandler para desabilitar o tratamento automático de cookie:

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

Usar IHttpClientFactory em um aplicativo de console

Em um aplicativo de console, adicione as seguintes referências de pacote ao projeto:

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

No exemplo a seguir:

• IHttpClientFactory e GitHubService são registrados no contêiner de serviço do Host genérico.
• GitHubService é solicitado da DI, que, por sua vez, solicita uma instância de IHttpClientFactory.
• GitHubService usa IHttpClientFactory para criar uma instância de HttpClient, que a usa para recuperar branches do GitHub do docs.

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

Middleware de propagação de cabeçalho

A propagação de cabeçalho é um middleware ASP.NET Core que propaga cabeçalhos HTTP da solicitação de entrada para as solicitações HttpClient de saída. Para usar a propagação de cabeçalho:

• Instale o pacote Microsoft.AspNetCore.HeaderPropagation.

• Configure o HttpClient e o pipeline de middleware em Program.cs:

  // 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();
  

• Faça solicitações de saída usando a instância de HttpClient configurada, que inclui os cabeçalhos adicionados.

Recursos adicionais

• Exibir ou baixar código de exemplo (como baixar)
• Usar HttpClientFactory implementar solicitações HTTP resilientes
• Implementar repetições de chamadas HTTP com retirada exponencial com o HttpClientFactory e políticas da Polly
• Implementar o padrão de disjuntor
• Como serializar e desserializar JSON no .NET