Realización de solicitudes HTTP mediante IHttpClientFactory en ASP.NET Core

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

Se puede registrar y usar una interfaz IHttpClientFactory para crear y configurar instancias de HttpClient en una aplicación. IHttpClientFactory ofrece las ventajas siguientes:

• Proporciona una ubicación central para denominar y configurar instancias de HttpClient lógicas. Por ejemplo, se podría registrar un cliente llamado github y configurarlo para acceder a GitHub. Se puede registrar un cliente predeterminado para el acceso general.
• Codifica el concepto de middleware de salida a través de la delegación de controladores en HttpClient. Proporciona extensiones para el middleware basado en Polly a fin de aprovechar los controladores de delegación en HttpClient.
• Administra la agrupación y la duración de las instancias de HttpClientMessageHandler subyacentes. La administración automática evita los problemas comunes de DNS (Sistema de nombres de dominio) que se producen al administrar la duración de HttpClient de forma manual.
• Agrega una experiencia de registro configurable (a través de ILogger) en todas las solicitudes enviadas a través de los clientes creados por Factory.

En el código de ejemplo de la versión este tema se usa System.Text.Json para deserializar el contenido JSON devuelto en las respuestas HTTP. Para obtener ejemplos en los que se usan Json.NET y ReadAsAsync<T>, utilice el selector de versión para seleccionar una versión 2.x de este tema.

Patrones de consumo

IHttpClientFactory se puede usar de varias formas en una aplicación:

• Uso básico
• Clientes con nombre
• Clientes con tipo
• Clientes generados

El mejor enfoque depende de los requisitos de la aplicación.

Uso básico

Registre IHttpClientFactory mediante una llamada a AddHttpClient en Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Se puede solicitar una instancia de IHttpClientFactory mediante la inserción de dependencias (DI). En el código siguiente se usa IHttpClientFactory para crear una instancia de 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);
        }
    }
}

El uso de IHttpClientFactory como en el ejemplo anterior es una buena manera de refactorizar una aplicación existente. No tiene efecto alguno en la forma de usar HttpClient. En aquellos sitios de una aplicación existente en los que ya se hayan creado instancias de HttpClient, reemplace esas repeticiones por llamadas a CreateClient.

Clientes con nombre

Los clientes con nombre son una buena opción cuando:

• La aplicación requiere muchos usos distintos de HttpClient.
• Muchas instancias HttpClient de tienen otra configuración.

Especifique la configuración de un objeto HttpClient con nombre durante su registro en 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");
});

En el código anterior, el cliente está configurado con:

• La dirección base. https://api.github.com/.
• Dos encabezados necesarios para trabajar con la API de GitHub.

CreateClient

Cada vez que se llama a CreateClient:

• Se crea una instancia de HttpClient.
• Se llama a la acción de configuración.

Para crear un cliente con nombre, pase su nombre a 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);
        }
    }
}

En el código anterior, no es necesario especificar un nombre de host en la solicitud. El código puede pasar solo la ruta de acceso, ya que se usa la dirección base configurada del cliente.

Clientes con tipo

Clientes con tipo:

• Proporcionan las mismas funciones que los clientes con nombre sin la necesidad de usar cadenas como claves.
• Ofrecen ayuda relativa al compilador e IntelliSense al consumir clientes.
• Facilitan una sola ubicación para configurar un elemento HttpClient determinado e interactuar con él. Por ejemplo, es posible usar un solo cliente con tipo:
  • Para un único punto de conexión de back-end.
  • Para encapsular toda la lógica relacionada con el punto de conexión.
• Funcionan con la inserción de dependencias y se pueden insertar en la aplicación cuando sea necesario.

Un cliente con tipo acepta un parámetro HttpClient en su constructor:

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

En el código anterior:

• La configuración se mueve al cliente con tipo.
• La instancia de HttpClient proporcionada se almacena como un campo privado.

Se pueden crear métodos específicos de la API que exponen la funcionalidad de HttpClient. Por ejemplo, el método GetAspNetCoreDocsBranches encapsula el código para recuperar las ramas de GitHub de documentos.

En el código siguiente se llama a AddHttpClient en Program.cs para registrar una clase de cliente GitHubService con tipo:

builder.Services.AddHttpClient<GitHubService>();

El cliente con tipo se registra como transitorio con inserción con dependencias, En el código anterior, AddHttpClient registra GitHubService como servicio transitorio. Este registro usa un Factory Method para:

1. Crea una instancia de HttpClient.
2. Cree una instancia de GitHubService, pasando la instancia de HttpClient a su constructor.

y se puede insertar y consumir directamente:

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

La configuración de un cliente con tipo se puede especificar también durante su registro en Program.cs, en lugar de en su constructor:

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

    // ...
});

Clientes generados

IHttpClientFactory se puede usar en combinación con bibliotecas de terceros, como Refit. Refit es una biblioteca de REST para .NET. Convierte las API de REST en interfaces en vivo. Llame a AddRefitClient para generar una implementación dinámica de una interfaz, que usa HttpClient para realizar las llamadas HTTP externas.

Una interfaz personalizada representa la API externa:

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

Llame a AddRefitClient para generar la implementación dinámica y, luego, llame a ConfigureHttpClient para configurar el elemento HttpClient subyacente:

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 DI para acceder a la implementación 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)
        {
            // ...
        }
    }
}

Realización de solicitudes POST, PUT y DELETE

En los ejemplos anteriores, todas las solicitudes HTTP usan el verbo HTTP de GET. HttpClient también admite otros verbos HTTP; por ejemplo:

• POST
• PUT
• SUPRIMIR
• PATCH

Para obtener una lista completa de los verbos HTTP admitidos, vea HttpMethod.

En el ejemplo siguiente se muestra cómo hacer una solicitud POST HTTP:

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

En el código anterior, el método CreateItemAsync:

• Serializa el parámetro TodoItem en JSON mediante System.Text.Json.
• Crea una instancia de StringContent a fin de empaquetar el JSON serializado para enviarlo en el cuerpo de la solicitud de HTTP.
• Llama a PostAsync para enviar el contenido de JSON a la URL especificada. Se trata de una URL relativa que se agrega a HttpClient.BaseAddress.
• Llama a EnsureSuccessStatusCode para iniciar una excepción si el código de estado de la respuesta no indica que la operación se ha realizado correctamente.

HttpClient también admite otros tipos de contenido. Por ejemplo, MultipartContent y StreamContent. Para obtener una lista completa del contenido admitido, vea HttpContent.

En el ejemplo siguiente se muestra una solicitud PUT HTTP:

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

El código anterior es similar al ejemplo de POST. El método SaveItemAsync llama a PutAsync en lugar de PostAsync.

En el ejemplo siguiente se muestra una solicitud DELETE HTTP:

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

    httpResponseMessage.EnsureSuccessStatusCode();
}

En el código anterior, el método DeleteItemAsync llama a DeleteAsync. Debido a que las solicitudes DELETE HTTP normalmente no contienen ningún cuerpo, el método DeleteAsync no proporciona ninguna sobrecarga que acepte una instancia de HttpContent.

Para obtener más información sobre el uso de verbos HTTP diferentes con HttpClient, vea HttpClient.

Middleware de solicitud saliente

HttpClient tiene el concepto de controladores de delegación, que se pueden vincular entre sí para las solicitudes HTTP salientes. IHttpClientFactory:

• simplifica la definición de controladores que se aplicarán por cada cliente con nombre.
• Admite el registro y encadenamiento de varios controladores para crear una canalización de middleware de solicitud saliente. Cada uno de estos controladores es capaz de realizar la tarea antes y después de la solicitud de salida. Este patrón:
  • Es similar a la canalización de middleware de entrada de ASP.NET Core.
  • Proporciona un mecanismo para administrar los intereses transversales relacionados con las solicitudes HTTP, como:
    • el almacenamiento en caché
    • el control de errores
    • la serialización
    • el registro

Para crear un controlador de delegación:

• Derívelo de DelegatingHandler.
• Reemplace SendAsync. Ejecute el código antes de pasar la solicitud al siguiente controlador de la canalización:

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

El código anterior comprueba si el encabezado X-API-KEY está en la solicitud. Si falta X-API-KEY, se devuelve BadRequest.

Se puede agregar más de un controlador a la configuración de una instancia de HttpClient con Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler:

builder.Services.AddTransient<ValidateHeaderHandler>();

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

En el código anterior, ValidateHeaderHandler se ha registrado con inserción de dependencias. Una vez registrado, se puede llamar a AddHttpMessageHandler, pasando el tipo del controlador.

Se pueden registrar varios controladores en el orden en que deben ejecutarse. Cada controlador contiene el siguiente controlador hasta que el último HttpClientHandler ejecuta la solicitud:

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

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

En el código anterior, SampleHandler1 se ejecuta primero, antes que SampleHandler2.

Uso de la inserción de dependencias en el middleware de solicitud de salida

Cuando IHttpClientFactory crea un nuevo controlador de delegación, usa la inserción de dependencias para cumplir con los parámetros de constructor del controlador. IHttpClientFactory crea un ámbito de inserción de dependencias independiente para cada controlador, lo que puede provocar un comportamiento sorprendente cuando un controlador consume un servicio con ámbito.

Por ejemplo, considere la siguiente interfaz y su implementación, que representa una tarea como una operación con un identificador, OperationId:

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Como sugiere su nombre, IOperationScoped se registra con la inserción de dependencias mediante una duración con ámbito:

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

El siguiente controlador de delegación consume y usa IOperationScoped para establecer el encabezado X-OPERATION-ID para la solicitud de salida:

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

En la HttpRequestsSampledescarga de , vaya a /Operation y actualice la página. El valor del ámbito de la solicitud cambia para cada solicitud, pero el valor del ámbito del controlador solo cambia cada 5 segundos.

Los controladores pueden depender de servicios de cualquier ámbito. Los servicios de los que dependen los controladores se eliminan cuando se elimina el controlador.

Use uno de los siguientes enfoques para compartir el estado por solicitud con controladores de mensajes:

• Pase datos al controlador usando HttpRequestMessage.Options.
• Use IHttpContextAccessor para acceder a la solicitud actual.
• Cree un objeto de almacenamiento AsyncLocal<T> personalizado para pasar los datos.

Usar controladores basados en Polly

IHttpClientFactory se integra con la biblioteca de terceros Polly. Polly es una biblioteca con capacidades de resistencia y control de errores transitorios para .NET. Permite a los desarrolladores expresar directivas como, por ejemplo, de reintento, interruptor, tiempo de espera, aislamiento compartimentado y reserva de forma fluida y segura para los subprocesos.

Se proporcionan métodos de extensión para hacer posible el uso de directivas de Polly con instancias de HttpClient configuradas. Las extensiones de Polly permiten agregar controladores basados en Polly a los clientes. Polly requiere el paquete NuGet Microsoft.Extensions.Http.Polly.

Control de errores transitorios

Los errores se suelen producir cuando las llamadas HTTP externas son transitorias. AddTransientHttpErrorPolicy permite definir una directiva para controlar los errores transitorios. Las directivas configuradas con AddTransientHttpErrorPolicy controlan las respuestas siguientes:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy proporciona acceso a un objeto PolicyBuilder configurado para controlar los errores que representan un posible error transitorio:

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

En el código anterior, se define una directiva WaitAndRetryAsync. Las solicitudes erróneas se reintentan hasta tres veces con un retardo de 600 ms entre intentos.

Seleccionar directivas dinámicamente

Los métodos de extensión se proporcionan para agregar controladores basados en Polly, por ejemplo, AddPolicyHandler. La siguiente sobrecarga de AddPolicyHandler inspecciona la solicitud para decidir qué directiva se debe 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);

En el código anterior, si la solicitud GET saliente es del tipo HTTP, se aplica un tiempo de espera de 10 segundos. En cualquier otro método HTTP, se usa un tiempo de espera de 30 segundos.

Agregar varios controladores de Polly

Es común anidar las directivas de Polly:

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

En el ejemplo anterior:

• Se agregan dos controladores.
• El primer controlador usa AddTransientHttpErrorPolicy para agregar una directiva de reintentos. Las solicitudes con error se reintentan hasta tres veces.
• La segunda llamada a AddTransientHttpErrorPolicy agrega una directiva de interruptor. Las solicitudes externas adicionales se bloquean durante 30 segundos si se producen cinco intentos con error seguidos. Las directivas de interruptor tienen estado. Así, todas las llamadas realizadas a través de este cliente comparten el mismo estado de circuito.

Agregar directivas desde el Registro de Polly

Una forma de administrar las directivas usadas habitualmente consiste en definirlas una vez y registrarlas con PolicyRegistry. Por ejemplo:

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

En el código anterior:

• Se agregan dos directivas, Regular y Long, al registro de Polly.
• AddPolicyHandlerFromRegistry configura clientes con nombre individuales para que usen estas directivas del registro de Polly.

Para más información sobre IHttpClientFactory y las integraciones de Polly, vea la wiki de Polly.

HttpClient y administración de la duración

Cada vez que se llama a CreateClient en IHttpClientFactory, se devuelve una nueva instancia de HttpClient. Se crea un objeto HttpMessageHandler por cada cliente con nombre. La fábrica administra la duración de las instancias de HttpMessageHandler.

IHttpClientFactory agrupa las instancias de HttpMessageHandler creadas por Factory para reducir el consumo de recursos. Se puede reutilizar una instancia de HttpMessageHandler del grupo al crear una instancia de HttpClient si su duración aún no ha expirado.

Se recomienda agrupar controladores porque cada uno de ellos normalmente administra sus propias conexiones HTTP subyacentes. Crear más controladores de los necesarios puede provocar retrasos en la conexión. Además, algunos controladores dejan las conexiones abiertas de forma indefinida, lo que puede impedir que el controlador reaccione ante los cambios de DNS (Sistema de nombres de dominio).

La duración de controlador predeterminada es dos minutos. El valor predeterminado se puede reemplazar de forma individual en cada cliente con nombre:

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

Normalmente, las instancias de HttpClient se pueden trata como objetos de .NET que no requieren eliminación. ya que se cancelan las solicitudes salientes y la instancia de HttpClient determinada no se puede usar después de llamar a Dispose. IHttpClientFactory realiza un seguimiento y elimina los recursos que usan las instancias de HttpClient.

Mantener una sola instancia de HttpClient activa durante un período prolongado es un patrón común que se utiliza antes de la concepción de IHttpClientFactory. Este patrón se convierte en innecesario tras la migración a IHttpClientFactory.

Alternativas a IHttpClientFactory

El uso de IHttpClientFactory en una aplicación habilitada para la inserción de dependencias evita lo siguiente:

• Problemas de agotamiento de recursos mediante la agrupación de instancias de HttpMessageHandler.
• Problemas de DNS obsoletos al recorrer las instancias de HttpMessageHandler a intervalos regulares.

Existen formas alternativas de solucionar los problemas anteriores mediante una instancia de SocketsHttpHandler de larga duración.

• Cree una instancia de SocketsHttpHandler al iniciar la aplicación y úsela para la vida útil de la aplicación.
• Configure PooledConnectionLifetime con un valor adecuado en función de los tiempos de actualización de DNS.
• Cree instancias de HttpClient mediante new HttpClient(handler, disposeHandler: false) según sea necesario.

Los enfoques anteriores solucionan los problemas de administración de recursos que IHttpClientFactory resuelve de forma similar.

• SocketsHttpHandler comparte las conexiones entre las instancias de HttpClient. Este uso compartido impide el agotamiento del socket.
• SocketsHttpHandler recorre las conexiones según PooledConnectionLifetime para evitar problemas de DNS obsoletos.

Registro

Los clientes que se han creado a través de IHttpClientFactory registran mensajes de registro de todas las solicitudes. Habilite el nivel de información adecuado en la configuración del registro para ver los mensajes de registro predeterminados. El registro de más información, como el registro de encabezados de solicitud, solo se incluye en el nivel de seguimiento.

La categoría de registro usada en cada cliente incluye el nombre del cliente. Un cliente denominado MyNamedClient, por ejemplo, registra mensajes con una categoría de "System.Net.Http.HttpClient.MyNamedClient.LogicalHandler". Los mensajes con el sufijo LogicalHandler se producen fuera de la canalización de controlador de la solicitud. En la solicitud, los mensajes se registran antes de que cualquier otro controlador de la canalización haya procesado la solicitud. En la respuesta, los mensajes se registran después de que cualquier otro controlador de la canalización haya recibido la respuesta.

El registro también se produce dentro de la canalización de controlador de la solicitud. En el ejemplo MyNamedClient, esos mensajes se registran con la categoría de registro "System.Net.Http.HttpClient.MyNamedClient.ClientHandler". En la solicitud, esto tiene lugar después de que todos los demás controladores se hayan ejecutado y justo antes de que se envíe la solicitud. En la respuesta, este registro incluye el estado de la respuesta antes de que vuelva a pasar por la canalización del controlador.

Al habilitar el registro tanto dentro como fuera de la canalización, se podrán inspeccionar los cambios realizados por otros controladores de la canalización. Esto puede incluir cambios en los encabezados de solicitud o en el código de estado de la respuesta.

La inclusión del nombre del cliente en la categoría de registro permite filtrar el registro para clientes con nombre específicos.

Configurar HttpMessageHandler

Puede que sea necesario controlar la configuración del elemento HttpMessageHandler interno usado por un cliente.

Se devuelve un IHttpClientBuilder cuando se agregan clientes con nombre o con tipo. Se puede usar el método de extensión ConfigurePrimaryHttpMessageHandler para definir un delegado. Este delegado servirá para crear y configurar el elemento principal HttpMessageHandler que ese cliente usa:

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

Cookies

Las instancias de HttpMessageHandler agrupadas generan objetos CookieContainer que se comparten. El uso compartido de objetos CookieContainer no previsto suele generar código incorrecto. En el caso de las aplicaciones que requieren cookies, tenga en cuenta lo siguiente:

• Deshabilitación del control automático de cookies
• Evitar IHttpClientFactory

Llame a ConfigurePrimaryHttpMessageHandler para deshabilitar el control automático de cookies:

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

Uso de IHttpClientFactory en una aplicación de consola

En una aplicación de consola, agregue las siguientes referencias de paquete al proyecto:

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

En el ejemplo siguiente:

• IHttpClientFactory y GitHubService se registran en el contenedor de servicio del host genérico.
• GitHubService se solicita desde DI, que, a su vez, solicita una instancia de IHttpClientFactory.
• GitHubService usa IHttpClientFactory para crear una instancia de HttpClient, que usa para recuperar ramas de GitHub de documentos.

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 propagación de encabezados

La propagación de encabezados es un middleware de ASP.NET Core que se usa para propagar encabezados HTTP de la solicitud entrante a las solicitudes HttpClient salientes. Para utilizar la propagación de encabezados:

• Instale el paquete Microsoft.AspNetCore.HeaderPropagation.

• Configure HttpClient y la canalización de middleware en 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();
  

• Realice solicitudes salientes mediante la instancia de HttpClient configurada, que incluye los encabezados agregados.

Recursos adicionales

• Vea o descargue el código de ejemplo (cómo descargarlo)
• Uso de HttpClientFactory para implementar solicitudes HTTP resistentes
• Implementación de reintentos de llamada HTTP con retroceso exponencial con HttpClientFactory y las directivas de Polly
• Implementación del patrón de interruptor
• Procedimiento para serializar y deserializar JSON en .NET