Stellen von HTTP-Anforderungen mithilfe von IHttpClientFactory in ASP.NET Core

Von Kirk Larkin, Steve Gordon, Glenn Condron und Ryan Nowak.

IHttpClientFactory kann registriert und zum Konfigurieren und Erstellen von HttpClient-Instanzen in einer App verwendet werden. IHttpClientFactory bietet die folgenden Vorteile:

• Ein zentraler Ort für das Benennen und Konfigurieren logischer HttpClient-Instanzen wird damit geboten. Beispielsweise kann ein Client namens github registriert und für den Zugriff auf GitHub konfiguriert werden. Ein Standardclient kann für den allgemeinen Zugriff registriert werden.
• Das Konzept der ausgehenden Middleware wird über delegierende Handler in HttpClient in Code umgesetzt. Außerdem werden Erweiterungen für auf Polly basierende Middleware bereitgestellt, um die delegierenden Handler in HttpClient zu nutzen.
• Das Pooling und die Lebensdauer von zugrunde liegenden HttpClientMessageHandler-Instanzen werden verwaltet. Durch die automatische Verwaltung werden allgemeine DNS-Probleme (Domain Name System) vermieden, die bei der manuellen Verwaltung der Lebensdauer von HttpClient auftreten.
• Eine konfigurierbare Protokollierungsfunktion wird (über ILogger) für alle Anforderungen hinzugefügt, die über Clients gesendet werden, die von der Factory erstellt wurden.

Der Beispielcode in dieser Version des Themas verwendet System.Text.Json, um JSON-Inhalte zu deserialisieren, die in HTTP-Antworten zurückgegeben wurden. Verwenden Sie bei Beispielen, die Json.NET und ReadAsAsync<T> verwenden, die Versionsauswahl, um eine 2.x-Version dieses Themas auszuwählen.

Verbrauchsmuster

Es gibt mehrere Möglichkeiten IHttpClientFactory in einer App zu verwenden:

• Grundlegende Verwendung
• Benannte Clients
• Typisierte Clients
• Generierte Clients

Der beste Ansatz richtet sich nach den Anforderungen der App.

Grundlegende Verwendung

Registrieren Sie IHttpClientFactory, indem Sie AddHttpClient in Program.cs aufrufen:

var builder = WebApplication.CreateBuilder(args);

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

Eine IHttpClientFactory-Schnittstelle kann mithilfe der Dependency Injection (DI) angefordert werden. Im folgenden Code wird IHttpClientFactory verwendet, um eine HttpClient-Instanz zu erstellen:

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 wie im vorhergehenden Beispiel zu verwenden ist eine gute Möglichkeit zum Umgestalten einer vorhandene App. Dies hat keine Auswirkung auf die Verwendung von HttpClient. An Stellen, an denen HttpClient-Instanzen in einer vorhandenen App erstellt werden, können Sie diese Ereignisse mit Aufrufen von CreateClient ersetzen.

Benannte Clients

Benannte Clients sind in folgenden Fällen eine gute Wahl:

• Die App erfordert viele verschiedene Verwendungen von HttpClient.
• Viele HttpClients verfügen über unterschiedliche Konfigurationen.

Geben Sie die Konfiguration für einen benannten HttpClient bei dessen Registrierung in Program.cs an:

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

Im vorangehenden Code wird der Client mit Folgendem konfiguriert:

• der Basisadresse https://api.github.com/
• zwei Header, die für die Arbeit mit der GitHub-API erforderlich sind

CreateClient

Jedes Mal, wenn CreateClient aufgerufen wird, geschieht Folgendes:

• Eine neue Instanz von HttpClient wird erstellt.
• Die Konfigurationsaktion wird aufgerufen.

Übergeben Sie für die Erstellung eines benannten Clients dessen Namen an 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);
        }
    }
}

Im vorangehenden Code muss die Anforderung keinen Hostnamen angeben. Der Code muss nur den Pfad übergeben, da die für den Client konfigurierte Basisadresse verwendet wird.

Typisierte Clients

Typisierte Clients:

• Stellen dieselben Funktionen wie benannte Clients bereit, ohne Zeichenfolgen als Schlüssel verwenden zu müssen.
• Bieten Hilfe durch IntelliSense und Compiler beim Verarbeiten von Clients.
• Stellen einen einzelnen Ort zum Konfigurieren und Interagieren mit einem bestimmten HttpClient bereit. Beispielsweise kann ein einzelner typisierter Client für Folgendes verwendet werden:
  • für einen einzelnen Back-End-Endpunkt
  • um die gesamte Logik zu kapseln, die den Endpunkt behandelt
• Funktionieren mit DI und können überall in der App eingefügt werden, wo sie benötigt werden.

Ein typisierter Client akzeptiert einen HttpClient-Parameter in seinem Konstruktor:

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

Für den Code oben gilt:

• Die Konfiguration wird in den typisierten Client verschoben.
• Die bereitgestellte HttpClient-Instanz wird als privates Feld gespeichert.

Es können API-spezifische Methoden erstellt werden, die die HttpClient-Funktionalität verfügbar machen. Die GetAspNetCoreDocsBranches-Methode kapselt z. B. Code zum Abrufen von GitHub-Branches mit Dokumentation.

Der folgende Code ruft AddHttpClient in Program.cs auf, um die typisierte GitHubService-Clientklasse zu registrieren:

builder.Services.AddHttpClient<GitHubService>();

Der typisierte Client wird mit DI als „vorübergehend“ registriert. Im vorherigen Code registriert AddHttpClientGitHubService als vorübergehenden Dienst. Diese Registrierung verwendet eine Factorymethode für folgende Aktionen:

1. Erstellen Sie eine Instanz von HttpClient:
2. Erstellen einer GitHubService-Instanz, wobei die Instanz von HttpClient an ihren Konstrukt übergeben wird

Der typisierte Client kann direkt eingefügt und verwendet werden:

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

Die Konfiguration kann für einen typisierten Client auch während dessen Registrierung in Program.cs angegeben werden, anstatt im Konstruktor des typisierten Clients:

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

    // ...
});

Generierte Clients

IHttpClientFactory kann in Verbindung mit Bibliotheken von Drittanbietern verwendet werden, z. B. Refit. Refit ist eine REST-Bibliothek für .NET. Sie konvertiert REST-APIs in Live-Schnittstellen. Rufen Sie AddRefitClient auf, um eine dynamische Implementierung einer Schnittstelle zu generieren, die HttpClient zum Durchführen der externen HTTP-Aufrufe verwendet.

Eine benutzerdefinierte Schnittstelle stellt die externe API dar:

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

Rufen Sie AddRefitClient auf, um die dynamische Implementierung zu generieren, und rufen Sie dann ConfigureHttpClient auf, um den zugrunde liegenden HttpClient zu konfigurieren:

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

Verwenden Sie DI, um auf die dynamische Implementierung von IGitHubClient zuzugreifen:

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

Stellen von POST-, PUT- und DELETE-Anforderungen

In den vorangehenden Beispielen verwenden alle Anforderungen das GET-HTTP-Verb. HttpClient unterstützt ebenso andere HTTP-Verben, einschließlich der folgenden:

• POST
• PUT
• DELETE
• PATCH

Eine komplette Liste der unterstützten HTTP-Verben finden Sie unter HttpMethod.

Im folgenden Beispiel wird gezeigt, wie Sie eine HTTP-POST-Anforderung stellen:

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

Für die CreateItemAsync-Methoden im Code oben gilt Folgendes:

• Sie serialisiert den TodoItem-Parameter mithilfe von System.Text.Json in JSON.
• Sie erstellt eine Instanz von StringContent, um den serialisierten JSON-Code zum Senden im HTTP-Anforderungstext zu packen.
• Die Methode ruft PostAsync auf, um den JSON-Inhalt an die angegebene URL zu senden. Dies ist eine relative URL, die zu HttpClient.BaseAddress hinzugefügt wird.
• Sie ruft EnsureSuccessStatusCode auf, um eine Ausnahme auszulösen, wenn der Antwortstatuscode nicht auf Erfolg hinweist.

HttpClient unterstützt auch andere Inhaltstypen. Beispiel: MultipartContent und StreamContent. Eine komplette Liste der unterstützten Inhaltstypen finden Sie unter HttpContent.

Das folgende Beispiel zeigt eine HTTP-PUT-Anforderung.

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

Der vorangehende Code ist dem POST-Beispiel ähnlich. Die SaveItemAsync-Methode ruft PutAsync anstelle von PostAsync auf.

Das folgende Beispiel zeigt eine HTTP-DELETE-Anforderung.

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

    httpResponseMessage.EnsureSuccessStatusCode();
}

Im vorangehenden Code ruft die DeleteItemAsync-Methode DeleteAsync auf. Da HTTP-DELETE-Anforderungen normalerweise keinen Text enthalten, stellt die DeleteAsync-Methode keine Überladung bereit, die eine Instanz von HttpContent akzeptiert.

Weitere Informationen zur Verwendung unterschiedlicher HTTP-Verben mit HttpClient finden Sie unter HttpClient.

Middleware für ausgehende Anforderungen

HttpClient enthält das Konzept, Handler zu delegieren, die für ausgehende HTTP-Anforderungen miteinander verknüpft werden können. IHttpClientFactory:

• Erleichtert das Definieren der Handler, die für jeden benannten Client angewendet werden
• Unterstützt die Registrierung und Verkettung von mehreren Handlern, um eine Pipeline für die Middleware für ausgehende Anforderungen zu erstellen. Jeder dieser Handler kann vor und nach der ausgehenden Anforderung Aufgaben ausführen. Dieses Muster:
  • ähnelt der eingehenden Pipeline für Middleware in ASP.NET Core
  • bietet einen Mechanismus zum Verwalten von übergreifenden Belangen bezüglich HTTP-Anforderungen, z. B.:
    • Zwischenspeicherung
    • Fehlerbehandlung
    • Serialisierung
    • Protokollierung

So erstellen Sie einen delegierenden Handler:

• Leiten Sie von DelegatingHandler ab.
• Überschreiben Sie SendAsync. Führen Sie Code aus, bevor die Anforderung an den nächsten Handler in der Pipeline übergeben wird:

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

Der vorangehende Code überprüft, ob die Anforderung einen X-API-KEY-Header enthält. Wenn X-API-KEY fehlt, wird BadRequest zurückgegeben.

Für eine HttpClient-Klasse mit Microsoft.Extensions.DependencyInjection.HttpClientBuilderExtensions.AddHttpMessageHandler kann mehr als ein Handler zur Konfiguration hinzugefügt werden:

builder.Services.AddTransient<ValidateHeaderHandler>();

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

Im vorangehenden Code ist ValidateHeaderHandler mit DI registriert. Nach der Registrierung kann AddHttpMessageHandler aufgerufen werden, was den Typ für den Handler übergibt.

Mehrere Handler können in der Reihenfolge registriert werden, in der sie ausgeführt werden sollen. Jeder Handler umschließt den nächsten Handler, bis der endgültige HttpClientHandler die Anforderung ausführt:

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

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

Im vorangehenden Code wird SampleHandler1 zuerst ausgeführt, vor SampleHandler2.

Verwenden von DI in Middleware für ausgehende Anforderungen

Wenn IHttpClientFactory einen neuen delegierenden Handler erstellt, wird DI verwendet, um die Konstruktorparameter des Handlers zu erfüllen. IHttpClientFactory erstellt einen separaten DI-Bereich für jeden Handler. Dies kann zu überraschendem Verhalten führen, wenn ein Handler einen bereichsbezogenen Dienst nutzt.

Sehen Sie sich beispielsweise die folgende Schnittstelle und ihre Implementierung an, die eine Aufgabe als Vorgang mit einem Bezeichner OperationId darstellt:

public interface IOperationScoped
{
    string OperationId { get; }
}

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

Wie der Name bereits vermuten lässt, wird IOperationScoped bei DI registriert, wobei eine bereichsbezogene Lebensdauer verwendet wird:

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

Der folgende delegierende Handler verwendet IOperationScoped, um den X-OPERATION-ID-Header für die ausgehende Anforderung festzulegen:

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

Navigieren Sie im HttpRequestsSample-Download zu /Operation, und aktualisieren Sie die Seite. Der Wert für den Anforderungsbereich ändert sich für jede Anforderung, aber der Wert des Handlerbereichs ändert sich nur alle 5 Sekunden.

Handler können von Diensten eines beliebigen Bereichs abhängen. Dienste, von denen Handler abhängig sind, werden verworfen, wenn der Handler verworfen wird.

Verwenden Sie einen der folgenden Ansätze, um den anforderungsspezifischen Zustand mit Meldungshandlern zu teilen:

• Übergeben Sie Daten mit HttpRequestMessage.Options an den Handler.
• Greifen Sie mit IHttpContextAccessor auf die aktuelle Anforderung zu.
• Erstellen Sie ein benutzerdefiniertes AsyncLocal<T>-Speicherobjekt, um die Daten zu übergeben.

Verwenden von Polly-basierten Handlern

IHttpClientFactory ist mit der Drittanbieterbibliothek Polly integriert. Polly ist eine umfassende Bibliothek für die Behandlung von beständigen und vorübergehenden Fehlern für .NET. Entwicklern wird damit ermöglicht, Richtlinien wie Wiederholungsrichtlinien, Trennschalterrichtlinien, Timeout-Richtlinien, Bulkhead Isolation-Richtlinien und Ausweichrichtlinien in einer flüssigen und threadsicheren Art und Weise auszudrücken.

Erweiterungsmethoden werden bereitgestellt, um die Verwendung von Polly-Richtlinien mit konfigurierten HttpClient-Instanzen zu aktivieren. Die Polly-Erweiterungen unterstützen das Hinzufügen von Polly-basierten Handlern zu Clients. Polly erfordert das Microsoft.Extensions.Http.Polly-NuGet-Paket.

Behandeln von vorrübergehenden Fehlern

Fehler treten normalerweise auf, wenn externe HTTP-Aufrufe vorübergehend sind. AddTransientHttpErrorPolicy ermöglicht die Definition einer Richtlinie, um vorübergehende Fehler zu behandeln. Mit AddTransientHttpErrorPolicy konfigurierte Richtlinien behandeln die folgenden Antworten:

• HttpRequestException
• HTTP 5xx
• HTTP 408

AddTransientHttpErrorPolicy ermöglicht den Zugriff auf ein PolicyBuilder-Objekt, das für die Fehlerbehandlung konfiguriert wurde und mögliche vorübergehende Fehler darstellt:

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

Im vorangehenden Code wird eine WaitAndRetryAsync-Richtlinie definiert. Anforderungsfehler werden bis zu dreimal mit einer Verzögerung von 600 ms wiederholt.

Dynamisches Auswählen von Richtlinien

Erweiterungsmethoden werden zum Hinzufügen von Polly-basierten Handlern bereitgestellt, z. B. AddPolicyHandler. Der folgende AddPolicyHandler-Überladung prüft die Anforderung, um zu entscheiden, welche Richtlinie angewendet werden soll:

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

Im vorangehenden Code wird ein 10 Sekunden langer Timeout angewendet, wenn die ausgehende Anforderung eine HTTP GET-Anforderung ist. Für alle anderen HTTP-Methoden wird ein 30 Sekunden langer Timeout verwendet.

Hinzufügen mehrerer Polly-Handler

Es ist üblich, Polly-Richtlinien zu schachteln:

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

Im vorherigen Beispiel:

• Zwei Handler werden hinzugefügt.
• Der erste Handler verwendet AddTransientHttpErrorPolicy, um eine Wiederholungsrichtlinie hinzuzufügen. Fehlgeschlagene Anforderungen werden bis zu drei Mal wiederholt.
• Der zweite AddTransientHttpErrorPolicy-Aufruf fügt eine Trennschalterrichtlinie hinzu. Weitere externe Anforderungen werden 30 Sekunden lang blockiert, wenn fünf Fehlversuche hintereinander stattfinden. Trennschalterrichtlinien sind zustandsbehaftet. Alle Aufrufe über diesen Client teilen den gleichen Schalterzustand.

Hinzufügen von Richtlinien aus der Polly-Registrierung

Eine Methode zum Verwalten regelmäßig genutzter Richtlinien ist, Sie einmal zu definieren und mit PolicyRegistry zu registrieren. Beispiel:

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

Für den Code oben gilt:

• Der Polly-Registrierung werden zwei Richtlinien hinzugefügt: Regular und Long.
• AddPolicyHandlerFromRegistry konfiguriert einzelne benannte Clients für die Verwendung dieser Richtlinien aus der Polly-Registrierung.

Weitere Informationen zu IHttpClientFactory und Polly-Integrationen finden Sie im Polly-Wiki.

HttpClient und die Verwaltung der Lebensdauer

Bei jedem Aufruf von CreateClient in der IHttpClientFactory wird eine neue Instanz von HttpClient zurückgegeben. Pro benannter Client wird ein HttpMessageHandler erstellt. Die Factory verwaltet die Lebensdauer der HttpMessageHandler-Instanzen.

IHttpClientFactory legt die HttpMessageHandler-Instanzen zusammen, die von der Factory zum Reduzieren des Ressourcenverbrauchs erstellt wurden. Eine HttpMessageHandler-Instanz kann aus dem Pool wiederverwendet werden, wenn eine neue HttpClient-Instanz erstellt wird und deren Lebensdauer noch nicht abgelaufen ist.

Das Zusammenlegen von Handlern ist ein wünschenswerter Vorgang, da jeder Handler in der Regel seine zugrunde liegenden HTTP-Verbindungen selbst verwaltet. Wenn mehr Handler als nötig erstellt werden, können Verzögerungen bei Verbindungen entstehen. Einige Handler halten Verbindungen auch unbegrenzt offen, was verhindert, dass der Handler auf DNS-Änderungen (Domain Name System) reagiert.

Die Standardlebensdauer von Handlern beträgt zwei Minuten. Der Standardwert kann für jeden benannten Client überschrieben werden:

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

HttpClient-Instanzen können im Allgemeinen als .NET-Objekte behandelt werden, die nicht verworfen werden müssen. Beim Verwerfen werden ausgehende Anforderungen abgebrochen, und es wird sichergestellt, dass die angegebene HttpClient-Instanz nach dem Aufruf von Dispose nicht mehr verwendet werden kann. IHttpClientFactory verfolgt von HttpClient-Instanzen verwendete Ressourcen nach und verwirft sie.

Das Beibehalten einer einzelnen HttpClient-Instanz für einen langen Zeitraum ist ein allgemeines Muster, das vor der Einführung von IHttpClientFactory verwendet wurde. Dieses Muster wird nach der Migration zu IHttpClientFactory überflüssig.

Alternativen zu IHttpClientFactory

Mit der Verwendung von IHttpClientFactory in einer DI-fähigen App wird Folgendes vermieden:

• Probleme mit der Ressourcenauslastung durch Zusammenlegen von HttpMessageHandler-Instanzen
• Probleme durch veraltetes DNS durch regelmäßigen Wechsel von HttpMessageHandler-Instanzen

Es gibt alternative Möglichkeiten zum Lösen des vorangehenden Problems mithilfe einer langlebigen SocketsHttpHandler-Instanz:

• Erstellen Sie eine SocketsHttpHandler-Instanz, wenn die App gestartet wird, und verwenden Sie diese für die Lebensdauer der App.
• Konfigurieren Sie einen geeigneten Wert für PooledConnectionLifetime basierend auf den DNS-Aktualisierungszeiten.
• Erstellen Sie bei Bedarf HttpClient-Instanzen mithilfe von new HttpClient(handler, disposeHandler: false).

Diese Ansätze lösen die Ressourcenverwaltungsprobleme, die IHttpClientFactory auf ähnliche Weise löst.

• SocketsHttpHandler gibt Verbindungen für HttpClient-Instanzen frei. Durch diese Freigabe wird die Erschöpfung von Sockets vermieden.
• SocketsHttpHandler wechselt die Verbindungen anhand von PooledConnectionLifetime, um Probleme durch veraltetes DNS zu umgehen.

Protokollierung

Über IHttpClientFactory erstellte Clients zeichnen Protokollmeldungen für alle Anforderungen auf. Aktivieren Sie die entsprechende Informationsebene in der Protokollierungskonfiguration, um die Standardprotokollmeldungen anzuzeigen. Zusätzliche Protokollierung, z.B. das Protokollieren von Anforderungsheadern, wird nur auf der Ablaufverfolgungsebene enthalten.

Die Protokollierungskategorie für jeden Client enthält den Namen des Clients. Ein Client namens MyNamedClient protokolliert z. B. Nachrichten mit der Kategorie „System.Net.Http.HttpClient.MyNamedClient.LogicalHandler“. Meldungen mit dem Suffix LogicalHandler treten außerhalb der Anforderungshandlerpipeline auf. In der Anforderung werden Meldungen protokolliert, bevor andere Handler in der Pipeline sie verarbeitet haben. In der Antwort werden Meldungen protokolliert, nachdem andere Handler in der Pipeline die Antwort empfangen haben.

Die Protokollierung tritt ebenfalls innerhalb der Anforderungshandlerpipeline auf. Im Beispiel von MyNamedClient werden diese Nachrichten mit der Protokollkategorie „System.Net.Http.HttpClient.MyNamedClient.ClientHandler“ protokolliert. Für die Anforderung erfolgt dies, nachdem alle anderen Handler ausgeführt wurden und bevor die Anforderung gesendet wird. Diese Protokollierung enthält den Zustand der Antwort in der Antwort, bevor sie an die Handlerpipeline zurückgegeben wird.

Das Aktivieren der Protokollierung außerhalb und innerhalb der Pipeline ermöglicht die Überprüfung der Änderungen, die durch andere Handler in der Pipeline erfolgt sind. Dies kann die Änderungen an Anforderungsheadern oder am Statuscode der Antwort enthalten.

Das Einschließen des Namens des Clients in der Protokollkategorie aktiviert die Protokollfilterung für spezifische benannte Clients.

Konfigurieren von HttpMessageHandler

Es kann notwendig sein, die Konfiguration des inneren von einem Client verwendeten HttpMessageHandler zu steuern.

IHttpClientBuilder wird zurückgegeben, wenn benannte oder typisierte Clients hinzugefügt werden. Die Erweiterungsmethode ConfigurePrimaryHttpMessageHandler kann zum Definieren eines Delegaten verwendet werden. Der Delegat wird verwendet, um den primären HttpMessageHandler zu erstellen und konfigurieren, der von dem Client verwendet wird:

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

Cookie

Die zusammengelegten HttpMessageHandler-Instanzen resultieren in der Freigabe von CookieContainer-Objekten. Die unerwartete Freigabe von CookieContainer-Objekten führt oft zu fehlerhaftem Code. Ziehen Sie für Apps, die cookies erfordern, folgende Vorgehensweisen in Betracht:

• Deaktivieren der automatischen cookieverarbeitung
• Vermeiden der Verwendung von IHttpClientFactory

Rufen Sie ConfigurePrimaryHttpMessageHandler auf, um die automatische cookieverarbeitung zu deaktivieren:

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

Verwenden von IHttpClientFactory in einer Konsolen-App

Fügen Sie in einer Konsolen-App dem Projekt die folgenden Paketverweise hinzu:

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

Im folgenden Beispiel:

• IHttpClientFactory und GitHubService sind im Dienstcontainer des generischen Hosts registriert.
• GitHubService wird über DI angefordert, die wiederum eine Instanz von IHttpClientFactory anfordert.
• GitHubService erstellt über IHttpClientFactory eine Instanz von HttpClient, die verwendet wird, um GitHub-Branches mit Dokumentation abzurufen.

using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddHttpClient();
        services.AddTransient<GitHubService>();
    })
    .Build();

try
{
    var gitHubService = host.Services.GetRequiredService<GitHubService>();
    var gitHubBranches = await gitHubService.GetAspNetCoreDocsBranchesAsync();

    Console.WriteLine($"{gitHubBranches?.Count() ?? 0} GitHub Branches");

    if (gitHubBranches is not null)
    {
        foreach (var gitHubBranch in gitHubBranches)
        {
            Console.WriteLine($"- {gitHubBranch.Name}");
        }
    }
}
catch (Exception ex)
{
    host.Services.GetRequiredService<ILogger<Program>>()
        .LogError(ex, "Unable to load branches from GitHub.");
}

public class GitHubService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public GitHubService(IHttpClientFactory httpClientFactory) =>
        _httpClientFactory = httpClientFactory;

    public async Task<IEnumerable<GitHubBranch>?> GetAspNetCoreDocsBranchesAsync()
    {
        var httpRequestMessage = new HttpRequestMessage(
            HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches")
        {
            Headers =
            {
                { "Accept", "application/vnd.github.v3+json" },
                { "User-Agent", "HttpRequestsConsoleSample" }
            }
        };

        var httpClient = _httpClientFactory.CreateClient();
        var httpResponseMessage = await httpClient.SendAsync(httpRequestMessage);

        httpResponseMessage.EnsureSuccessStatusCode();

        using var contentStream =
            await httpResponseMessage.Content.ReadAsStreamAsync();
        
        return await JsonSerializer.DeserializeAsync
            <IEnumerable<GitHubBranch>>(contentStream);
    }
}

public record GitHubBranch(
    [property: JsonPropertyName("name")] string Name);

Middleware für Headerweitergabe

Für die Headerweitergabe wird eine ASP.NET Core-Middleware verwendet, um HTTP-Header von eingehenden Anforderungen an ausgehende HttpClient-Anforderungen weiterzugeben. So verwenden Sie die Headerweitergabe:

• Installieren Sie das Paket Microsoft.AspNetCore.HeaderPropagation.

• Konfigurieren Sie den HttpClient und die Middlewarepipeline in 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();
  

• Erstellen Sie ausgehende Anforderungen mithilfe der konfigurierten HttpClient-Instanz, die die hinzugefügten Header enthält.

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Verwenden von HttpClientFactory zur Implementierung robuster HTTP-Anforderungen
• Implementieren von Wiederholungen von HTTP-Aufrufen mit exponentiellem Backoff mit HttpClientFactory und Polly-Richtlinien
• Implementieren des Trennschaltermusters
• Serialisieren und Deserialisieren von JSON-Daten in .NET