Wysyłaj żądania HTTP przy użyciu elementu IHttpClientFactory w ASP.NET Core

Kirk Larkin, Steve Gordon, Glenn Condron i Ryan Nowak.

Element IHttpClientFactory można zarejestrować i użyć do konfigurowania i tworzenia HttpClient wystąpień w aplikacji. IHttpClientFactory oferuje następujące korzyści:

• Zapewnia centralną lokalizację nazewnictwa i konfigurowania wystąpień logicznych HttpClient. Na przykład klient o nazwie github może zostać zarejestrowany i skonfigurowany do uzyskiwania dostępu do usługi GitHub. W celu uzyskania dostępu ogólnego można zarejestrować domyślnego klienta.
• Codififies koncepcja wychodzącego oprogramowania pośredniczącego za pośrednictwem delegowania programów obsługi w programie HttpClient. Udostępnia rozszerzenia oprogramowania pośredniczącego opartego na usłudze Polly w celu korzystania z delegowania programów obsługi w programie HttpClient.
• Zarządza buforowaniem i okresem istnienia wystąpień bazowych HttpClientMessageHandler . Automatyczne zarządzanie pozwala uniknąć typowych problemów z systemem DNS (system nazw domen), które występują podczas ręcznego zarządzania HttpClient okresami istnienia.
• Dodaje konfigurowalne środowisko rejestrowania (za pośrednictwem ILogger) dla wszystkich żądań wysyłanych za pośrednictwem klientów utworzonych przez fabrykę.

Przykładowy kod w tej wersji tematu używa System.Text.Json do deserializacji JSzawartości ON zwróconej w odpowiedziach HTTP. W przypadku przykładów korzystających z elementów Json.NET i ReadAsAsync<T>użyj selektora wersji, aby wybrać wersję 2.x tego tematu.

Konsumpcji

W aplikacji można użyć kilku sposobów IHttpClientFactory :

• Podstawowy sposób użycia
• Nazwani klienci
• Klienci typizowane
• Wygenerowani klienci

Najlepsze podejście zależy od wymagań aplikacji.

Podstawowy sposób użycia

Zarejestruj się IHttpClientFactory , wywołując polecenie AddHttpClient w programie Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Żądanie IHttpClientFactory można zażądać przy użyciu wstrzykiwania zależności (DI). Poniższy kod używa IHttpClientFactory metody do utworzenia HttpClient wystąpienia:

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

Użycie IHttpClientFactory metody podobnej do w poprzednim przykładzie jest dobrym sposobem refaktoryzacji istniejącej aplikacji. Nie ma to wpływu na sposób HttpClient użycia. W miejscach, w których HttpClient wystąpienia są tworzone w istniejącej aplikacji, zastąp te wystąpienia wywołaniami do CreateClient.

Nazwani klienci

Nazwani klienci są dobrym wyborem, gdy:

• Aplikacja wymaga wielu odrębnych zastosowań programu HttpClient.
• Wiele HttpClientz nich ma inną konfigurację.

Określ konfigurację dla nazwy HttpClient podczas rejestracji w pliku 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");
});

W poprzednim kodzie klient jest skonfigurowany z:

• Adres podstawowy https://api.github.com/.
• Dwa nagłówki wymagane do pracy z interfejsem API usługi GitHub.

CreateClient

Za każdym razem CreateClient jest wywoływana:

• Zostanie utworzone nowe wystąpienie klasy HttpClient .
• Akcja konfiguracji jest wywoływana.

Aby utworzyć nazwanego klienta, przekaż jego nazwę do elementu 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);
        }
    }
}

W poprzednim kodzie żądanie nie musi określać nazwy hosta. Kod może przekazać tylko ścieżkę, ponieważ używany jest adres podstawowy skonfigurowany dla klienta.

Klienci typizowane

Klienci typizowane:

• Zapewnij te same możliwości, co nazwani klienci bez konieczności używania ciągów jako kluczy.
• Zapewnia funkcję IntelliSense i pomoc kompilatora podczas korzystania z klientów.
• Podaj pojedynczą lokalizację do skonfigurowania określonego elementu i interakcji z nim HttpClient. Na przykład można użyć pojedynczego klienta typizowanego:
  • W przypadku pojedynczego punktu końcowego zaplecza.
  • Aby hermetyzować całą logikę do obsługi punktu końcowego.
• Praca z di i można wstrzyknąć tam, gdzie jest to wymagane w aplikacji.

Typowany klient akceptuje HttpClient parametr w konstruktorze:

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

Powyższy kod ma następujące działanie:

• Konfiguracja jest przenoszona do typizowanego klienta.
• Podane HttpClient wystąpienie jest przechowywane jako pole prywatne.

Można utworzyć metody specyficzne dla interfejsu API, które uwidaczniają HttpClient funkcjonalność. Na przykład GetAspNetCoreDocsBranches metoda hermetyzuje kod umożliwiający pobranie gałęzi usługi GitHub docs.

Następujące wywołania AddHttpClient kodu w programie w Program.cs celu zarejestrowania wpisanej GitHubService klasy klienta:

builder.Services.AddHttpClient<GitHubService>();

Typizowanego klienta jest rejestrowany jako przejściowy z di. W poprzednim kodzie rejestruje AddHttpClient się GitHubService jako usługa przejściowa. Ta rejestracja używa metody fabryki do:

1. Utwórz wystąpienie elementu HttpClient.
2. Utwórz wystąpienie GitHubServiceklasy , przekazując w wystąpieniu obiektu do jego konstruktora HttpClient .

Typizowanego klienta można wstrzyknąć i używać bezpośrednio:

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

Konfigurację typizowanego klienta można również określić podczas jego rejestracji w Program.csprogramie , a nie w konstruktorze typizowanego klienta:

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

    // ...
});

Wygenerowani klienci

IHttpClientFactory można używać w połączeniu z bibliotekami innych firm, takimi jak Refit. Refit to REST biblioteka platformy .NET. Konwertuje interfejsy REST API na interfejsy na żywo. Wywołanie AddRefitClient metody w celu wygenerowania dynamicznej implementacji interfejsu, który używa HttpClient metody do wykonywania zewnętrznych wywołań HTTP.

Interfejs niestandardowy reprezentuje zewnętrzny interfejs API:

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

Wywołaj metodę AddRefitClient w celu wygenerowania implementacji dynamicznej, a następnie wywołaj metodę ConfigureHttpClient w celu skonfigurowania bazowego HttpClientelementu :

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

Użyj di, aby uzyskać dostęp do dynamicznej implementacji programu 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)
        {
            // ...
        }
    }
}

Żądania POST, PUT i DELETE

W poprzednich przykładach wszystkie żądania HTTP używają czasownika GET HTTP. HttpClient Obsługuje również inne czasowniki HTTP, w tym:

• POST
• PUT
• DELETE
• PATCH

Aby uzyskać pełną listę obsługiwanych czasowników HTTP, zobacz HttpMethod.

W poniższym przykładzie pokazano, jak utworzyć żądanie 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();
}

W poprzednim kodzie CreateItemAsync metoda :

• Serializuje TodoItem parametr na JSWŁ. przy użyciu polecenia System.Text.Json.
• Tworzy wystąpienie StringContent elementu w celu spakowania serializowanego JSmodułu ON do wysyłania w treści żądania HTTP.
• Wywołania PostAsync w celu wysłania JSzawartości ON do określonego adresu URL. Jest to względny adres URL, który jest dodawany do obiektu HttpClient.BaseAddress.
• Wywołania EnsureSuccessStatusCode w celu zgłoszenia wyjątku, jeśli kod stanu odpowiedzi nie wskazuje powodzenia.

HttpClient Obsługuje również inne typy zawartości. Na przykład MultipartContent i StreamContent. Aby uzyskać pełną listę obsługiwanej zawartości, zobacz HttpContent.

W poniższym przykładzie pokazano żądanie 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();
}

Powyższy kod jest podobny do przykładu POST. Metoda SaveItemAsync wywołuje PutAsync metodę PostAsynczamiast .

W poniższym przykładzie pokazano żądanie HTTP DELETE:

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

    httpResponseMessage.EnsureSuccessStatusCode();
}

W poprzednim kodzie metoda wywołuje DeleteAsyncmetodę DeleteItemAsync . Ponieważ żądania HTTP DELETE zwykle nie zawierają treści, DeleteAsync metoda nie zapewnia przeciążenia, które akceptuje wystąpienie HttpContentklasy .

Aby dowiedzieć się więcej o korzystaniu z różnych czasowników HTTP w programie HttpClient, zobacz HttpClient.

Oprogramowanie pośredniczące żądań wychodzących

HttpClient Ma koncepcję delegowania procedur obsługi, które mogą być połączone razem dla wychodzących żądań HTTP. IHttpClientFactory:

• Upraszcza definiowanie procedur obsługi do zastosowania dla każdego nazwanego klienta.
• Obsługuje rejestrację i tworzenie łańcucha wielu procedur obsługi w celu utworzenia potoku oprogramowania pośredniczącego żądań wychodzących. Każdy z tych programów obsługi może wykonać pracę przed i po żądaniu wychodzącym. Ten wzorzec:
  • Jest podobny do potoku oprogramowania pośredniczącego dla ruchu przychodzącego w ASP.NET Core.
  • Zapewnia mechanizm zarządzania problemami krzyżowymi dotyczącymi żądań HTTP, takich jak:
    • Buforowanie
    • obsługa błędów
    • Serializacji
    • rejestrowanie

Aby utworzyć procedurę obsługi delegowania:

• Wyprowadzanie z klasy DelegatingHandler.
• Zastąpij SendAsync. Wykonaj kod przed przekazaniem żądania do następnej procedury obsługi w potoku:

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

Powyższy kod sprawdza, czy X-API-KEY nagłówek znajduje się w żądaniu. Jeśli X-API-KEY brakuje, BadRequest jest zwracany.

Do konfiguracji programu można dodać więcej niż jedną procedurę obsługi za HttpClient pomocą Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandlerpolecenia :

builder.Services.AddTransient<ValidateHeaderHandler>();

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

W poprzednim kodzie ValidateHeaderHandler element jest zarejestrowany za pomocą di. Po zarejestrowaniu AddHttpMessageHandler można wywołać metodę , przekazując typ programu obsługi.

Wiele procedur obsługi można zarejestrować w kolejności, w której powinny być wykonywane. Każda procedura obsługi opakowuje następną procedurę obsługi do momentu, aż końcowy HttpClientHandler wykona żądanie:

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

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

W poprzednim kodzie SampleHandler1 uruchamia się najpierw przed SampleHandler2.

Używanie di w rozwiązaniu pośredniczącym żądań wychodzących

Podczas IHttpClientFactory tworzenia nowej procedury obsługi delegowania używa di do spełnienia parametrów konstruktora programu obsługi. IHttpClientFactory Tworzy oddzielny zakres di dla każdej procedury obsługi, co może prowadzić do zaskakującego zachowania, gdy program obsługi korzysta z usługi o określonym zakresie .

Rozważmy na przykład następujący interfejs i jego implementację, która reprezentuje zadanie jako operację o identyfikatorze : OperationId

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Jak sugeruje jego nazwa, IOperationScoped jest rejestrowana w di przy użyciu okresu istnienia o określonym zakresie :

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

Następująca procedura obsługi delegowania używa metody i używa IOperationScoped jej do ustawiania nagłówka X-OPERATION-ID dla żądania wychodzącego:

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

W pobranym plikuHttpRequestsSample przejdź do /Operation strony i odśwież stronę. Wartość zakresu żądania zmienia się dla każdego żądania, ale wartość zakresu procedury obsługi zmienia się tylko co 5 sekund.

Programy obsługi mogą zależeć od usług dowolnego zakresu. Usługi, od których zależą programy obsługi, są usuwane po usunięciu programu obsługi.

Użyj jednej z następujących metod udostępniania stanu poszczególnych żądań z procedurami obsługi komunikatów:

• Przekazywanie danych do programu obsługi przy użyciu polecenia HttpRequestMessage.Options.
• Użyj polecenia IHttpContextAccessor , aby uzyskać dostęp do bieżącego żądania.
• Utwórz niestandardowy AsyncLocal<T> obiekt magazynu w celu przekazania danych.

Korzystanie z programów obsługi opartych na usłudze Polly

IHttpClientFactory program integruje się z biblioteką innej firmy Polly. Polly to kompleksowa odporność i biblioteka obsługi błędów przejściowych dla platformy .NET. Umożliwia deweloperom wyrażanie zasad, takich jak ponawianie prób, wyłącznik, przekroczenie limitu czasu, izolacja grodziowa i powrót w sposób płynny i bezpieczny wątkowo.

Dostępne są metody rozszerzenia umożliwiające korzystanie z zasad polly ze skonfigurowanymi HttpClient wystąpieniami. Rozszerzenia Polly obsługują dodawanie programów obsługi opartych na usłudze Polly do klientów. Polly wymaga pakietu NuGet Microsoft.Extensions.Http.Polly .

Obsługa błędów przejściowych

Błędy zwykle występują, gdy zewnętrzne wywołania HTTP są przejściowe. AddTransientHttpErrorPolicy umożliwia zdefiniowanie zasad w celu obsługi błędów przejściowych. Zasady skonfigurowane z obsługą AddTransientHttpErrorPolicy następujących odpowiedzi:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy zapewnia dostęp do obiektu skonfigurowanego PolicyBuilder do obsługi błędów reprezentujących możliwy błąd przejściowy:

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

W poprzednim kodzie zdefiniowano WaitAndRetryAsync zasady. Żądania, które zakończyły się niepowodzeniem, są ponawiane do trzech razy z opóźnieniem 600 ms między próbami.

Dynamiczne wybieranie zasad

Metody rozszerzeń są udostępniane w celu dodania procedur obsługi opartych na usłudze Polly, na przykład AddPolicyHandler. Następujące AddPolicyHandler przeciążenie sprawdza żądanie, aby zdecydować, które zasady mają być stosowane:

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

W poprzednim kodzie, jeśli żądanie wychodzące jest żądaniem HTTP GET, zostanie zastosowany 10-sekundowy limit czasu. W przypadku każdej innej metody HTTP jest używany limit czasu 30 sekund.

Dodawanie wielu procedur obsługi polly

Często zagnieżdżanie zasad polly:

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

W powyższym przykładzie:

• Dodano dwie procedury obsługi.
• Pierwsza procedura obsługi używa AddTransientHttpErrorPolicy metody w celu dodania zasad ponawiania. Żądania, które zakończyły się niepowodzeniem, są ponawiane do trzech razy.
• Drugie AddTransientHttpErrorPolicy wywołanie dodaje zasady wyłącznika. Kolejne żądania zewnętrzne są blokowane przez 30 sekund, jeśli 5 nieudanych prób nastąpi sekwencyjnie. Zasady wyłącznika są stanowe. Wszystkie wywołania za pośrednictwem tego klienta mają ten sam stan obwodu.

Dodawanie zasad z rejestru Polly

Podejście do zarządzania regularnie używanymi zasadami polega na zdefiniowaniu ich raz i zarejestrowaniu ich w obiekcie PolicyRegistry. Na przykład:

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

Powyższy kod ma następujące działanie:

• Dwie zasady Regular i Long, są dodawane do rejestru Polly.
• AddPolicyHandlerFromRegistry Konfiguruje poszczególnych nazwanych klientów tak, aby używali tych zasad z rejestru Polly.

Aby uzyskać więcej informacji na IHttpClientFactory temat integracji z usługą Polly, zobacz witrynę typu wiki polly.

Zarządzanie klientem HttpClient i okresem istnienia

HttpClient Nowe wystąpienie jest zwracane za każdym razem, gdy CreateClient jest wywoływane w elemecie IHttpClientFactory. Element HttpMessageHandler jest tworzony na nazwanego klienta. Fabryka zarządza okresami HttpMessageHandler istnienia wystąpień.

IHttpClientFactoryHttpMessageHandler pule wystąpień utworzonych przez fabrykę w celu zmniejszenia zużycia zasobów. Wystąpienie HttpMessageHandler może zostać ponownie użyte z puli podczas tworzenia nowego HttpClient wystąpienia, jeśli jego okres istnienia nie wygasł.

Buforowanie procedur obsługi jest pożądane, ponieważ każda procedura obsługi zwykle zarządza własnymi podstawowymi połączeniami HTTP. Utworzenie większej liczby procedur obsługi niż jest to konieczne może spowodować opóźnienia połączeń. Niektóre programy obsługi utrzymują również połączenia otwarte na czas nieokreślony, co może uniemożliwić programowi obsługi reagowanie na zmiany systemu DNS (systemu nazw domen).

Domyślny okres obsługi to dwie minuty. Wartość domyślną można zastąpić na podstawie nazwanego klienta:

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

HttpClient wystąpienia mogą być zwykle traktowane jako obiekty platformy .NET , które nie wymagają usuwania. Usuwanie anuluje wychodzące żądania i gwarantuje, że dane HttpClient wystąpienie nie może być używane po wywołaniu metody Dispose. IHttpClientFactory śledzi i usuwa zasoby używane przez HttpClient wystąpienia.

Utrzymywanie aktywności pojedynczego HttpClient wystąpienia przez długi czas jest typowym wzorcem używanym przed utworzeniem klasy IHttpClientFactory. Ten wzorzec staje się zbędny po przeprowadzeniu migracji do programu IHttpClientFactory.

Alternatywy dla IHttpClientFactory

Użycie IHttpClientFactory w aplikacji z włączoną obsługą di pozwala uniknąć:

• Problemy z wyczerpaniem zasobów przez wystąpienia puli HttpMessageHandler .
• Nieaktualne problemy z systemem DNS przez wystąpienia rowerowe HttpMessageHandler w regularnych odstępach czasu.

Istnieją alternatywne sposoby rozwiązywania powyższych problemów przy użyciu długotrwałego SocketsHttpHandler wystąpienia.

• Utwórz wystąpienie aplikacji SocketsHttpHandler , gdy aplikacja zostanie uruchomiona i użyj jej do końca życia aplikacji.
• Skonfiguruj PooledConnectionLifetime odpowiednią wartość na podstawie czasów odświeżania DNS.
• Utwórz HttpClient wystąpienia przy użyciu zgodnie z new HttpClient(handler, disposeHandler: false) potrzebami.

Powyższe podejścia rozwiązują problemy z zarządzaniem zasobami, które IHttpClientFactory są rozwiązywane w podobny sposób.

• Udziały SocketsHttpHandler połączeń między HttpClient wystąpieniami. To udostępnianie uniemożliwia wyczerpanie gniazd.
• Połączenia SocketsHttpHandler cykli zgodnie z, aby PooledConnectionLifetime uniknąć nieaktualnych problemów z systemem DNS.

Rejestrowanie

Klienci utworzeni za pośrednictwem IHttpClientFactory komunikatów dziennika rekordów dla wszystkich żądań. Włącz odpowiedni poziom informacji w konfiguracji rejestrowania, aby wyświetlić domyślne komunikaty dziennika. Dodatkowe rejestrowanie, takie jak rejestrowanie nagłówków żądań, jest uwzględniane tylko na poziomie śledzenia.

Kategoria dziennika używana dla każdego klienta zawiera nazwę klienta. Klient o nazwie MyNamedClient, na przykład, rejestruje komunikaty z kategorią "System.Net.Http.HttpClient. MyNamedClient. Logiczna procedura obsługi". Komunikaty sufiksowane za pomocą programu LogicalHandler występują poza potokiem obsługi żądań. W żądaniu komunikaty są rejestrowane, zanim wszystkie inne programy obsługi w potoku przetworzyły je. W odpowiedzi komunikaty są rejestrowane po otrzymaniu odpowiedzi przez inne programy obsługi potoku.

Rejestrowanie odbywa się również wewnątrz potoku procedury obsługi żądań. W przykładzie MyNamedClient te komunikaty są rejestrowane z kategorią dziennika "System.Net.Http.HttpClient. MyNamedClient. ClientHandler". W przypadku żądania dzieje się tak po uruchomieniu wszystkich innych procedur obsługi i bezpośrednio przed wysłaniem żądania. W odpowiedzi to rejestrowanie zawiera stan odpowiedzi, zanim przejdzie z powrotem przez potok obsługi.

Włączenie rejestrowania na zewnątrz i wewnątrz potoku umożliwia inspekcję zmian wprowadzonych przez inne programy obsługi potoków. Może to obejmować zmiany nagłówków żądań lub kod stanu odpowiedzi.

Uwzględnienie nazwy klienta w kategorii dziennika umożliwia filtrowanie dzienników dla określonych nazwanych klientów.

Konfigurowanie programu HttpMessageHandler

Może być konieczne kontrolowanie konfiguracji wewnętrznej HttpMessageHandler używanej przez klienta.

Element IHttpClientBuilder jest zwracany podczas dodawania nazwanych lub wpisanych klientów. Metoda ConfigurePrimaryHttpMessageHandler rozszerzenia może służyć do definiowania delegata. Delegat służy do tworzenia i konfigurowania podstawowego HttpMessageHandler używanego przez tego klienta:

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

CookieS

Wystąpienia w puli HttpMessageHandler powoduje CookieContainer udostępnianie obiektów. Nieprzewidziane CookieContainer udostępnianie obiektów często powoduje niepoprawny kod. W przypadku aplikacji wymagających wartości cookies należy wziąć pod uwagę jedną z następujących kwestii:

• Wyłączanie automatycznej cookie obsługi
• Unikanie IHttpClientFactory

Wywołaj, ConfigurePrimaryHttpMessageHandler aby wyłączyć automatyczną cookie obsługę:

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

Używanie elementu IHttpClientFactory w aplikacji konsolowej

W aplikacji konsolowej dodaj następujące odwołania do pakietu do projektu:

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

W poniższym przykładzie:

• IHttpClientFactory i GitHubService są zarejestrowane w kontenerze usługi hosta ogólnego .
• GitHubService jest żądana od di, który z kolei żąda wystąpienia klasy IHttpClientFactory.
• GitHubService używa IHttpClientFactory polecenia do utworzenia wystąpienia klasy HttpClient, którego używa do pobierania gałęzi usługi GitHub w witrynie 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);

Oprogramowanie pośredniczące propagacji nagłówka

Propagacja nagłówka to oprogramowanie pośredniczące ASP.NET Core propagujące nagłówki HTTP z żądania przychodzącego do żądań wychodzącychHttpClient. Aby użyć propagacji nagłówka:

• Zainstaluj pakiet Microsoft.AspNetCore.HeaderPropagation .

• Skonfiguruj potok oprogramowania pośredniczącego HttpClient i w programie 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();
  

• Wysyłaj żądania wychodzące przy użyciu skonfigurowanego HttpClient wystąpienia, w tym dodanych nagłówków.

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Używanie elementu HttpClientFactory do implementowania odpornych na błędy żądań HTTP
• Implementowanie ponownych prób wywołań HTTP z wycofywaniem wykładniczym przy użyciu zasad HttpClientFactory i Polly
• Implementowanie wzorca wyłącznika
• Jak serializować i deserializować JSWŁ. na platformie .NET