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

Przez 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.
• Koduje koncepcję 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 zawartości JSON zwracanej 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 :

• Podstawowe użycie
• Nazwani klienci
• Wpisanych klientów
• Wygenerowani klienci

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

Podstawowy sposób użycia

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

var builder = WebApplication.CreateBuilder(args);

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

Żądanie IHttpClientFactory może być wymagane 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 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 metody CreateClient.

Nazwani klienci

Nazwani klienci są dobrym wyborem w następujących przypadkach:

• Aplikacja wymaga wielu różnych 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 za pomocą polecenia :

• Adres https://api.github.com/podstawowy .
• 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 programu HttpClient .
• Akcja konfiguracji jest wywoływana.

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

Wpisanych klientów

Typizowane klienci:

• 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 i interakcji z określonym HttpClientelementem . Na przykład można użyć jednego typu klienta:
  • W przypadku pojedynczego punktu końcowego zaplecza.
  • Aby hermetyzować całą logikę do obsługi punktu końcowego.
• Praca z di i może być wstrzykiwana 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:

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

Metody specyficzne dla interfejsu API można utworzyć, aby uwidaczniać HttpClient funkcje. Na przykład GetAspNetCoreDocsBranches metoda hermetyzuje kod w celu pobrania gałęzi usługi GitHub witryny Docs.

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

builder.Services.AddHttpClient<GitHubService>();

Typowany klient jest zarejestrowany jako przejściowy z di. W poprzednim kodzie AddHttpClient rejestruje 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 klasy , przekazując wystąpienie GitHubServicedo 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 dla platformy .NET. Konwertuje REST interfejsy API na interfejsy na żywo. Wywołaj metodę AddRefitClient , aby wygenerować dynamiczną implementację interfejsu, która 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
• ODŁÓŻ
• 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 w formacie JSON przy użyciu polecenia System.Text.Json.
• Tworzy wystąpienie elementu StringContent w celu spakowania serializowanego kodu JSON do wysyłania w treści żądania HTTP.
• Wywołuje metodę PostAsync wysyłania zawartości JSON 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. Przykład: MultipartContent i StreamContent. Aby uzyskać pełną listę obsługiwanych 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 metodę DeleteItemAsync DeleteAsync. Ponieważ żądania HTTP DELETE zwykle nie zawierają treści, DeleteAsync metoda nie udostępnia przeciążenia, które akceptuje wystąpienie HttpContentklasy .

Aby dowiedzieć się więcej na temat używania 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 ze sobą dla wychodzących żądań HTTP. IHttpClientFactory:

• Upraszcza definiowanie procedur obsługi, które mają być stosowane dla każdego nazwanego klienta.
• Obsługuje rejestrację i łączenie 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 programie ASP.NET Core.
  • Udostępnia mechanizm zarządzania problemami krzyżowymi dotyczącymi żądań HTTP, takich jak:
    • Buforowanie
    • obsługa błędów
    • szeregowanie
    • rejestrowanie

Aby utworzyć procedurę obsługi delegowania:

• Pochodzą z klasy DelegatingHandler.
• Zastąpij .SendAsync Przed przekazaniem żądania do następnego programu obsługi w potoku wykonaj kod:

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 zostanie zwrócona wartość .

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

builder.Services.AddTransient<ValidateHeaderHandler>();

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

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

W kolejności wykonywania można zarejestrować wiele procedur obsługi. Każda procedura obsługi opakowuje następną procedurę obsługi do momentu, aż finale HttpClientHandler wykona żądanie:

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

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

W poprzednim kodzie SampleHandler1 uruchomi 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. IHttpClientFactorytworzy oddzielny zakres di dla każdego programu 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ę z identyfikatorem: 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 zarejestrowany 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 polecenia i używa IOperationScoped go do ustawienia 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 pliku HttpRequestsSample przejdź do /Operation strony i odśwież stronę. Wartość zakresu żądania zmienia się dla każdego żądania, ale wartość zakresu programu obsługi zmienia się tylko co 5 sekund.

Programy obsługi mogą zależeć od usług dowolnego zakresu. Usługi, od których są zależne 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ń za pomocą programów 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 procedur 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 bulkhead 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. Usługa 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 WaitAndRetryAsync zdefiniowano 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 to HTTP GET, zostanie zastosowany limit czasu 10-sekundowy. W przypadku każdej innej metody HTTP jest używany 30-sekundowy limit czasu.

Dodawanie wielu programów obsługi polly

Typowe jest 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 dwa programy obsługi.
• Pierwsza procedura obsługi używa AddTransientHttpErrorPolicy metody do dodawania zasad ponawiania. Żądania, które zakończyły się niepowodzeniem, są ponawiane do trzech razy.
• Drugie AddTransientHttpErrorPolicy wywołanie dodaje zasady wyłącznika. Dalsze żą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:

• 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

Nowe HttpClient wystąpienie jest zwracane za każdym razem, gdy CreateClient jest wywoływane w obiekcie 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 być ponownie używane z puli podczas tworzenia nowego HttpClient wystąpienia, jeśli jego okres istnienia nie wygasł.

Buforowanie programów obsługi jest pożądane, ponieważ każda procedura obsługi zwykle zarządza własnymi podstawowymi połączeniami HTTP. Tworzenie 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 istnienia programu obsługi to dwie minuty. Wartość domyślna może zostać zastąpiona 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 żądania wychodzące 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 pojedynczego HttpClient wystąpienia przy życiu przez długi czas trwania jest typowym wzorcem używanym przed utworzeniem klasy IHttpClientFactory. Ten wzorzec staje się niepotrzebny po przeprowadzeniu migracji do IHttpClientFactoryprogramu .

Alternatywy dla IHttpClientFactory

Używanie 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 rowerów 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, 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 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ń. Na żądanie komunikaty są rejestrowane, zanim wszystkie inne programy obsługi w potoku go przetworzyły. 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 następuje to 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 procedury obsługi potoku. 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. Metodę ConfigurePrimaryHttpMessageHandler rozszerzenia można użyć do zdefiniowania 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
        });

Pliki cookie

Wystąpienia w HttpMessageHandler puli powoduje CookieContainer współużytkowanie obiektów. Nieprzewidziane CookieContainer udostępnianie obiektów często powoduje niepoprawny kod. W przypadku aplikacji, które wymagają plików cookie, rozważ następujące kwestie:

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

Wywołanie w ConfigurePrimaryHttpMessageHandler celu wyłączenia automatycznej cookie obsługi:

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 żądanie z di, który z kolei żąda wystąpienia wystąpienia IHttpClientFactory.
• GitHubService używa IHttpClientFactory metody do utworzenia HttpClientwystąpienia klasy , 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 do propagowania nagłówków HTTP z żądania przychodzącego do żądań wychodzących HttpClient . 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, które zawiera dodane nagłówki.

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 przy użyciu wycofywania wykładniczego przy użyciu zasad HttpClientFactory i Polly
• Implementowanie wzorca wyłącznika
• Jak serializować i deserializować kod JSON na platformie .NET