Выполнения HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core

Авторы Кирк Ларкин (Kirk Larkin), Стив Гордон (Steve Gordon), Гленн Кондрон (Glenn Condron) и Райан Новак (Ryan Nowak).

IHttpClientFactory можно зарегистрировать и использовать для настройки и создания экземпляров HttpClient в приложении. IHttpClientFactory предоставляет следующие преимущества:

• Центральное расположение для именования и настройки логических экземпляров HttpClient. Например, можно зарегистрировать и настроить клиент github для доступа к GitHub. Можно зарегистрировать клиент по умолчанию для общего доступа.
• Кодификация концепции исходящего ПО промежуточного слоя путем делегирования обработчиков в HttpClient. Предоставление расширений для ПО промежуточного слоя на основе Polly для делегирования обработчиков в HttpClient.
• Управление созданием пулов и временем существования базовых экземпляров HttpClientMessageHandler. Автоматическое управление позволяет избежать обычных проблем со службой доменных имен (DNS), которые возникают при управлении временем существования HttpClient вручную.
• Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

Пример кода в этой версии раздела использует System.Text.Json для десериализации содержимого JSON, возвращаемого в ответах HTTP. Для примеров, использующих Json.NET и ReadAsAsync<T>, воспользуйтесь средством выбора версии, чтобы выбрать версию 2.x этого раздела.

Шаблоны потребления

Существует несколько способов использования IHttpClientFactory в приложении:

• Основное использование
• Именованные клиенты
• Типизированные клиенты
• Созданные клиенты

Оптимальный подход зависит от требований приложения.

Базовое использование

Зарегистрируйте IHttpClientFactory, вызвав AddHttpClient в 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);
        }
    }
}

Подобное использование IHttpClientFactory — это хороший способ рефакторинга имеющегося приложения. Он не оказывает влияния на использование HttpClient. Там, где в существующем приложении создаются экземпляры HttpClient, используйте вызовы к CreateClient.

Именованные клиенты

Именованные клиенты являются хорошим выбором в следующих случаях:

• Приложение требует много отдельных использований HttpClient.
• Многие HttpClient имеют другую конфигурацию.

Укажите конфигурацию для именованного клиента HttpClient во время регистрации в 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");
});

В приведенном выше коде клиент регистрируется с:

• базовым адресом https://api.github.com/;
• двумя заголовками, необходимыми для работы с API GitHub.

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. Например, можно использовать один типизированный клиент:
  • для одной серверной конечной точки;
  • для инкапсуляции всей логики, связанной с конечной точкой.
• Поддерживаются работа с внедрением зависимостей и возможность вставки в нужное место в приложении.

Типизированный клиент принимает параметр 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 по документации.

Следующий код вызывает AddHttpClient в Program.cs для регистрации класса типизированного клиента GitHubService:

builder.Services.AddHttpClient<GitHubService>();

Типизированный клиент регистрируется во внедрении зависимостей как временный. В приведенном выше коде 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 — это библиотека REST для .NET. Она преобразует 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");
    });

Используйте внедрение зависимостей, чтобы получить доступ к динамической реализации 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-запросы используют HTTP-команду GET. 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 выполняет следующие задачи:

• сериализует параметр TodoItem в JSON с помощью System.Text.Json.
• создает экземпляр StringContent для упаковки сериализованного JSON для отправки в тексте HTTP-запроса.
• вызывает метод PostAsync для отправки содержимого JSON по указанному URL-адресу. Это относительный 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.

Дополнительные сведения об использовании различных 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.

Можно добавить сразу несколько обработчиков в конфигурацию для HttpClient с использованием Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler:

builder.Services.AddTransient<ValidateHeaderHandler>();

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

В приведенном выше коде ValidateHeaderHandler регистрируется с помощью внедрения зависимостей. После регистрации можно вызвать AddHttpMessageHandler, передав тип обработчика.

Можно зарегистрировать несколько обработчиков в порядке, в котором они должны выполняться. Каждый обработчик содержит следующий обработчик, пока последний HttpClientHandler не выполнит запрос:

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

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

В приведенном выше коде SampleHandler1 выполняется первым, перед SampleHandler2.

Использование внедрения зависимостей в ПО промежуточного слоя для исходящих запросов

Когда IHttpClientFactory создает новый делегированный обработчик, он использует внедрение зависимостей для выполнения параметров конструктора обработчика. IHttpClientFactory создает отдельную область внедрения зависимостей для каждого обработчика, что может стать причиной аномального поведения, когда обработчик использует службу с назначенной областью.

Например, рассмотрим следующий интерфейс и его реализацию, которая представляет задачу в виде операции с идентификатором OperationId:

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Как можно понять из названия, 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. Она позволяет разработчикам выражать политики, например политику повтора, размыкателя цепи, времени ожидания, изоляции отсеков и отката, более эффективным и потокобезопасным образом.

Для использования политик Polly с настроенными экземплярами HttpClient предоставляются методы расширения. Расширения Polly поддерживают добавление обработчиков на основе Polly клиентам. Polly нужен пакет NuGet Microsoft.Extensions.Http.Polly.

Обработка временных сбоев

Чаще всего ошибки происходят, когда внешние вызовы HTTP являются временными. AddTransientHttpErrorPolicy позволяет определить политику для обработки временных ошибок. Политики, настроенные с помощью AddTransientHttpErrorPolicy, обрабатывают следующие ответы:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy предоставляет доступ к объекту PolicyBuilder, настроенному для обработки ошибок, представляющих возможный временный сбой:

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

В приведенном выше коде определена политика WaitAndRetryAsync. Неудачные запросы повторяются до трех раз с задержкой 600 мс между попытками.

Динамический выбор политик

Предоставляются методы расширения для добавления обработчиков на основе Polly, например AddPolicyHandler. Следующая перегрузка AddPolicyHandler проверяет запрос для определения применимой политики:

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

builder.Services.AddHttpClient("PollyDynamic")
    .AddPolicyHandler(httpRequestMessage =>
        httpRequestMessage.Method == HttpMethod.Get ? timeoutPolicy : longTimeoutPolicy);

Если в приведенном выше коде исходящий запрос является запросом HTTP GET, применяется время ожидания 10 секунд. Для остальных методов HTTP время ожидания — 30 секунд.

Добавление нескольких обработчиков Polly

Общепринятой практикой является вложение политик Polly:

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

В предыдущем примере:

• Добавляются два обработчика.
• Первый обработчик использует AddTransientHttpErrorPolicy, чтобы добавить политику повтора. Неудачные запросы выполняются повторно до трех раз.
• Второй вызов AddTransientHttpErrorPolicy добавляет политику размыкателя цепи. Дополнительные внешние запросы блокируются в течение 30 секунд в случае пяти неудачных попыток подряд. Политики размыкателя цепи отслеживают состояние. Все вызовы через этот клиент имеют одинаковое состояние цепи.

Добавление политик из реестра Polly

Подход к управлению регулярно используемыми политиками заключается в их однократном определении и регистрации с помощью PolicyRegistry. Например:

var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(10));
var longTimeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(
    TimeSpan.FromSeconds(30));

var policyRegistry = builder.Services.AddPolicyRegistry();

policyRegistry.Add("Regular", timeoutPolicy);
policyRegistry.Add("Long", longTimeoutPolicy);

builder.Services.AddHttpClient("PollyRegistryRegular")
    .AddPolicyHandlerFromRegistry("Regular");

builder.Services.AddHttpClient("PollyRegistryLong")
    .AddPolicyHandlerFromRegistry("Long");

В предыдущем коде:

• Две политики Regular и Long добавляются в реестр Polly.
• AddPolicyHandlerFromRegistry настраивает отдельные именованные клиенты для использования этих политик из реестра Polly.

Дополнительные сведения о IHttpClientFactory и интеграции Polly см. на вики-сайте Polly.

Управление HttpClient и временем существования

При каждом вызове CreateClient в IHttpClientFactory возвращается новый экземпляр HttpClient. HttpMessageHandler создается для каждого именованного клиента. Фабрика обеспечивает управление временем существования экземпляров HttpMessageHandler.

IHttpClientFactory объединяет в пул все экземпляры HttpMessageHandler, созданные фабрикой, чтобы уменьшить потребление ресурсов. Экземпляр HttpMessageHandler можно использовать повторно из пула при создании экземпляра HttpClient, если его время существования еще не истекло.

Создавать пулы обработчиков желательно, так как каждый обработчик обычно управляет собственными базовыми HTTP-подключениями. Создание лишних обработчиков может привести к задержке подключения. Некоторые обработчики поддерживают подключения открытыми в течение неопределенного периода, что может помешать обработчику отреагировать на изменения службы доменных имен (DNS).

Время существования обработчика по умолчанию — две минуты. Значение по умолчанию можно переопределить для каждого именованного клиента:

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

Экземпляры HttpClient обычно можно рассматривать как объекты .NET, не требующие освобождения. Высвобождение отменяет исходящие запросы и гарантирует, что указанный экземпляр HttpClient не может использоваться после вызова Dispose. IHttpClientFactory отслеживает и высвобождает ресурсы, используемые экземплярами HttpClient.

До появления IHttpClientFactory один экземпляр HttpClient часто сохраняли в активном состоянии в течение длительного времени. После перехода на IHttpClientFactory это уже не нужно.

Альтернативы интерфейсу IHttpClientFactory

Использование IHttpClientFactory в приложении с внедрением зависимостей позволяет:

• предотвращать проблемы нехватки ресурсов путем объединения экземпляров HttpMessageHandler в пулы;
• предотвращать проблемы устаревания записей DNS путем регулярной утилизации экземпляров HttpMessageHandler.

Существуют альтернативные способы решения указанных выше проблем с помощью долгосрочного экземпляра SocketsHttpHandler.

• Создайте экземпляр SocketsHttpHandler при запуске приложения и используйте его в течение всего жизненного цикла приложения.
• Присвойте PooledConnectionLifetime соответствующее значение в соответствии со временем обновления записей DNS.
• По мере необходимости создавайте экземпляры HttpClient с помощью new HttpClient(handler, disposeHandler: false).

Описанные выше подходы решают проблемы, связанные с управлением ресурсами, которые в IHttpClientFactory решаются сходным образом.

• SocketsHttpHandler обеспечивает совместное использование подключений экземплярами HttpClient. Этот позволяет предотвратить нехватку сокетов.
• SocketsHttpHandler уничтожает подключения в соответствии со значением PooledConnectionLifetime, чтобы предотвратить проблемы устаревания записей DNS.

Ведение журнала

Клиенты, созданные через IHttpClientFactory, записывают сообщения журнала для всех запросов. Установите соответствующий уровень информации в конфигурации ведения журнала, чтобы просматривать сообщения журнала по умолчанию. Дополнительное ведение журнала, например запись заголовков запросов, включено только на уровне трассировки.

Категория журнала для каждого клиента включает в себя имя клиента. Клиент с именем MyNamedClient, например, записывает в журнал сообщения с категорией "System.Net.Http.HttpClient.MyNamedClient.LogicalHandler". Сообщения с суффиксом LogicalHandler создаются за пределами конвейера обработчиков запросов. Во время запроса сообщения записываются в журнал до обработки запроса другими обработчиками в конвейере. Во время ответа сообщения записываются в журнал после получения ответа другими обработчиками в конвейере.

Кроме того, журнал ведется в конвейере обработчиков запросов. В примере MyNamedClient эти сообщения регистрируются с категорией журнала "System.Net.Http.HttpClient.MyNamedClient.ClientHandler". Во время запроса это происходит после выполнения всех обработчиков и непосредственно перед отправкой запроса. Во время ответа в журнале записывается состояние ответа перед его передачей обратно по конвейеру обработчиков.

Включив ведение журнала в конвейере и за его пределами, можно выполнять проверку изменений, внесенных другими обработчиками конвейера. Сюда входят изменения заголовков запросов или кода состояния ответов.

Включение имени клиента в категорию журнала позволяет фильтровать журналы по именованным клиентам.

Настройка HttpMessageHandler

Иногда необходимо контролировать конфигурацию внутреннего обработчика HttpMessageHandler, используемого клиентом.

При добавлении именованного или типизированного клиента возвращается IHttpClientBuilder. Для определения делегата можно использовать метод расширения ConfigurePrimaryHttpMessageHandler. Делегат используется для создания и настройки основного обработчика HttpMessageHandler, используемого этим клиентом:

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

Файлы cookie

Объединение экземпляров HttpMessageHandler в пул приводит к совместному использованию объектов CookieContainer. Непредвиденное совместное использование объектов CookieContainer часто приводит к ошибкам в коде. Для приложений, которым требуются файлы cookie, рекомендуется один из следующих подходов:

• отключите автоматическую обработку файлов cookie;
• не используйте IHttpClientFactory.

Чтобы отключить автоматическую обработку файлов ConfigurePrimaryHttpMessageHandler, вызовите cookie:

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

Использование IHttpClientFactory в консольном приложении

В консольном приложении добавьте в проект следующие ссылки на пакеты:

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

В следующем примере :

• IHttpClientFactory и GitHubService регистрируются в контейнере службы универсального узла.
• GitHubService запрашивается из внедрения зависимостей, которое запрашивает экземпляр 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.

• Настройте HttpClient и конвейер ПО промежуточного слоя в 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();
  

• Создайте исходящие запросы с помощью настроенного экземпляра HttpClient, который включает добавленные заголовки.

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)
• Использование HttpClientFactory для реализации устойчивых HTTP-запросов
• Реализация повторных попыток вызова HTTP с экспоненциальной задержкой с помощью HttpClientFactory и политик Polly
• Реализация шаблона размыкателя цепи
• Сериализация и десериализация JSON в .NET