Tolerante HTTP-apps bouwen: Belangrijke ontwikkelingspatronen

Het bouwen van robuuste HTTP-apps die kunnen worden hersteld na tijdelijke foutfouten is een veelvoorkomende vereiste. In dit artikel wordt ervan uitgegaan dat u inleiding tot tolerante app-ontwikkeling al hebt gelezen, omdat in dit artikel de belangrijkste concepten worden uitgebreid. Om tolerante HTTP-apps te bouwen, biedt het NuGet-pakket Microsoft.Extensions.Http.Resilience tolerantiemechanismen specifiek voor de HttpClient. Dit NuGet-pakket is afhankelijk van de Microsoft.Extensions.Resilience bibliotheek en Polly, een populair opensource-project. Zie Polly voor meer informatie.

Aan de slag

Als u tolerantiepatronen in HTTP-apps wilt gebruiken, installeert u het NuGet-pakket Microsoft.Extensions.Http.Resilience .

dotnet add package Microsoft.Extensions.Http.Resilience

<PackageReference Include="Microsoft.Extensions.Http.Resilience" />

Zie dotnet-pakket toevoegen of beheren van pakketafhankelijkheden in .NET-toepassingen voor meer informatie.

Tolerantie toevoegen aan een HTTP-client

Als u veerkracht wilt toevoegen aan een HttpClient, koppelt u een aanroep van het type IHttpClientBuilder dat wordt geretourneerd door een van de beschikbare AddHttpClient methoden aan te roepen. Zie IHttpClientFactory met .NET voor meer informatie.

Er zijn verschillende tolerantiegerichte extensies beschikbaar. Sommige zijn standaard, waardoor verschillende aanbevolen procedures voor de branche worden gebruikt, en andere zijn beter aanpasbaar. Wanneer u tolerantie toevoegt, moet u slechts één tolerantiehandler toevoegen en stackinghandlers voorkomen. Als u meerdere handlers voor tolerantie moet toevoegen, moet u overwegen de AddResilienceHandler extensiemethode te gebruiken, zodat u de strategieën voor tolerantie kunt aanpassen.

Standaard veerkrachtbeheerder toevoegen

De standaardtolerantiehandler maakt gebruik van meerdere strategieën voor tolerantie die op elkaar zijn gestapeld, met standaardopties voor het verzenden van aanvragen en het afhandelen van tijdelijke fouten. De standaardtolerantiehandler wordt toegevoegd door de AddStandardResilienceHandler extensiemethode op een IHttpClientBuilder exemplaar aan te roepen.

var services = new ServiceCollection();

var httpClientBuilder = services.AddHttpClient<ExampleClient>(
    configureClient: static client =>
    {
        client.BaseAddress = new("https://jsonplaceholder.typicode.com");
    });

De voorgaande code:

• Hiermee maakt u een ServiceCollection instantie.
• Hiermee voegt u een HttpClient voor het ExampleClient type toe aan de servicecontainer.
• Hiermee configureert u HttpClient om "https://jsonplaceholder.typicode.com" als het basisadres te gebruiken.
• Maakt de httpClientBuilder component aan die in de andere voorbeelden in dit artikel wordt gebruikt.

Een praktijkvoorbeeld is afhankelijk van hosting, zoals die wordt beschreven in het artikel .NET Generic Host . Bekijk het volgende bijgewerkte voorbeeld met behulp van het NuGet-pakket Microsoft.Extensions.Hosting :

using Http.Resilience.Example;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

IHttpClientBuilder httpClientBuilder = builder.Services.AddHttpClient<ExampleClient>(
    configureClient: static client =>
    {
        client.BaseAddress = new("https://jsonplaceholder.typicode.com");
    });

De voorgaande code is vergelijkbaar met de aanpak voor handmatige ServiceCollection creatie, maar berust in plaats daarvan op Host.CreateApplicationBuilder() om een host te bouwen die de services beschikbaar stelt.

De ExampleClient definitie is als volgt:

using System.Net.Http.Json;

namespace Http.Resilience.Example;

/// <summary>
/// An example client service, that relies on the <see cref="HttpClient"/> instance.
/// </summary>
/// <param name="client">The given <see cref="HttpClient"/> instance.</param>
internal sealed class ExampleClient(HttpClient client)
{
    /// <summary>
    /// Returns an <see cref="IAsyncEnumerable{T}"/> of <see cref="Comment"/>s.
    /// </summary>
    public IAsyncEnumerable<Comment?> GetCommentsAsync()
    {
        return client.GetFromJsonAsAsyncEnumerable<Comment>("/comments");
    }
}

De voorgaande code:

• Definieert een type ExampleClient dat een constructor heeft die een HttpClient accepteert.
• Hiermee wordt een GetCommentsAsync methode weergegeven waarmee een GET-aanvraag naar het /comments eindpunt wordt verzonden en het antwoord wordt geretourneerd.

Het Comment type wordt als volgt gedefinieerd:

namespace Http.Resilience.Example;

public record class Comment(
    int PostId, int Id, string Name, string Email, string Body);

Gezien het feit dat u een IHttpClientBuilder (httpClientBuilder) hebt gemaakt en u nu de implementatie en het ExampleClient bijbehorende Comment model begrijpt, kunt u het volgende voorbeeld overwegen:

httpClientBuilder.AddStandardResilienceHandler();

Met de voorgaande code wordt de standaard resiliencehandler toegevoegd aan de HttpClient. Net als bij de meeste tolerantie-API's zijn er overbelastingen waarmee u de standaardopties en toegepaste tolerantiestrategieën kunt aanpassen.

Verwijder standaardhandlers voor veerkracht

Er is een methode RemoveAllResilienceHandlers waarmee alle eerder geregistreerde tolerantiehandlers worden verwijderd. Het is handig wanneer u bestaande veerkrachthandlers moet wissen om uw aangepaste handler toe te voegen. In het volgende voorbeeld ziet u hoe u een aangepaste HttpClient configureert met behulp van de methode AddHttpClient, alle vooraf gedefinieerde strategieën voor tolerantie verwijdert en deze vervangt door nieuwe handlers. Met deze aanpak kunt u bestaande configuraties wissen en nieuwe configuraties definiëren op basis van uw specifieke vereisten.

// By default, we want all HttpClient instances to include the StandardResilienceHandler.
services.ConfigureHttpClientDefaults(builder => builder.AddStandardResilienceHandler());
// For a named HttpClient "custom" we want to remove the StandardResilienceHandler and add the StandardHedgingHandler instead.
services.AddHttpClient("custom")
    .RemoveAllResilienceHandlers()
    .AddStandardHedgingHandler();

De voorgaande code:

• Hiermee maakt u een ServiceCollection instantie.
• Voegt de standaardhandler voor veerkracht toe aan alle HttpClient instanties.
• Voor de 'aangepaste' HttpClient:
  • Hiermee verwijdert u alle vooraf gedefinieerde tolerantiehandlers die eerder zijn geregistreerd. Dit is handig als u wilt beginnen met een schone status om uw eigen aangepaste strategieën toe te voegen.
  • Voegt een StandardHedgingHandler toe aan de HttpClient. U kunt AddStandardHedgingHandler() vervangen door elke strategie die aansluit bij de behoeften van uw toepassing, zoals mechanismen voor opnieuw proberen, circuitonderbrekers of andere tolerantietechnieken.

Standaardinstellingen voor tolerantiehandler

De standaardconfiguratie koppelt vijf tolerantiestrategieën in de volgende volgorde (van buitenste naar binnenste):

Herhaalde pogingen en circuitonderbrekers

De strategieën voor opnieuw proberen en circuitonderbrekers verwerken beide een set specifieke HTTP-statuscodes en uitzonderingen. Houd rekening met de volgende HTTP-statuscodes:

• HTTP 500 en hoger (serverfouten)
• HTTP 408 (time-out bij aanvraag)
• HTTP 429 (te veel aanvragen)

Daarnaast verwerken deze strategieën de volgende uitzonderingen:

• HttpRequestException
• TimeoutRejectedException

Nieuwe pogingen voor een bepaalde lijst met HTTP-methoden uitschakelen

De standaard-resilience-handler is geconfigureerd om nieuwe pogingen te doen voor alle HTTP-methoden. Voor sommige toepassingen kan dergelijk gedrag ongewenst of zelfs schadelijk zijn. Als een POST-aanvraag bijvoorbeeld een nieuwe record invoegt in een database, kan het maken van nieuwe pogingen voor een dergelijke aanvraag leiden tot duplicatie van gegevens. Als u nieuwe pogingen voor een bepaalde lijst met HTTP-methoden wilt uitschakelen, kunt u de methode DisableFor(HttpRetryStrategyOptions, HttpMethod[]) gebruiken:

httpClientBuilder.AddStandardResilienceHandler(options =>
{
    options.Retry.DisableFor(HttpMethod.Post, HttpMethod.Delete);
});

U kunt ook de methode DisableForUnsafeHttpMethods(HttpRetryStrategyOptions) gebruiken, waarmee nieuwe pogingen voor POST, PATCH, PUT, DELETEen CONNECT aanvragen worden uitgeschakeld. Volgens RFC worden deze methoden als onveilig beschouwd, wat betekent dat hun semantiek niet uitsluitend uit lezen bestaat.

httpClientBuilder.AddStandardResilienceHandler(options =>
{
    options.Retry.DisableForUnsafeHttpMethods();
});

Standaardhandler voor hedging toevoegen

De standaard hedginghandler wikkelt de uitvoering van het verzoek in met een standaard hedgingsmechanisme. Het parallel uitvoeren van herhaalde pogingen voor trage aanvragen.

Als u de standaardhandler voor hedging wilt gebruiken, roept u AddStandardHedgingHandler de extensiemethode aan. In het volgende voorbeeld wordt de ExampleClient geconfigureerd om de standaard hedging handler te gebruiken.

httpClientBuilder.AddStandardHedgingHandler();

Met de voorgaande code wordt de standaardhandler voor hedging toegevoegd aan de HttpClient.

Standaardinstellingen voor hedging-handler

De standaard hedging maakt gebruik van een groep circuitonderbrekers om ervoor te zorgen dat ongezonde eindpunten niet worden afgedekt. De selectie uit de pool is standaard gebaseerd op de URL-instantie (schema + host + poort).

Met de voorgaande code wordt de standaardhandler voor hedging toegevoegd aan de IHttpClientBuilder. De standaardconfiguratie koppelt vijf tolerantiestrategieën in de volgende volgorde (van buitenste naar binnenste):

De routekeuze van de hedginghandler aanpassen

Wanneer u de standaardhandler voor hedging gebruikt, kunt u de manier aanpassen waarop de aanvraageindpunten worden geselecteerd door verschillende extensies voor het IRoutingStrategyBuilder type aan te roepen. Dit kan handig zijn voor scenario's zoals A/B-tests, waarbij u een percentage van de aanvragen naar een ander eindpunt wilt routeren:

httpClientBuilder.AddStandardHedgingHandler(static (IRoutingStrategyBuilder builder) =>
{
    // Hedging allows sending multiple concurrent requests
    builder.ConfigureOrderedGroups(static options =>
    {
        options.Groups.Add(new UriEndpointGroup()
        {
            Endpoints =
            {
                // Imagine a scenario where 3% of the requests are 
                // sent to the experimental endpoint.
                new() { Uri = new("https://example.net/api/experimental"), Weight = 3 },
                new() { Uri = new("https://example.net/api/stable"), Weight = 97 }
            }
        });
    });
});

De voorgaande code:

• Voegt de hedging-handler toe aan de IHttpClientBuilder.
• Hiermee configureert u de IRoutingStrategyBuilder om de ConfigureOrderedGroups-methode te gebruiken voor het configureren van de geordende groepen.
• Hiermee wordt een EndpointGroup aan de orderedGroup aanvraag toegevoegd waarmee 3% van de aanvragen naar het https://example.net/api/experimental eindpunt wordt gerouteerd en 97% van de aanvragen naar het https://example.net/api/stable eindpunt.
• Hiermee configureert u de IRoutingStrategyBuilder om de ConfigureWeightedGroups methode te gebruiken voor het configureren van de

Als u een gewogen groep wilt configureren, roept u de ConfigureWeightedGroups methode voor het IRoutingStrategyBuilder type aan. Het volgende voorbeeld configureert de IRoutingStrategyBuilder om de ConfigureWeightedGroups methode te gebruiken voor het configureren van de gewogen groepen.

httpClientBuilder.AddStandardHedgingHandler(static (IRoutingStrategyBuilder builder) =>
{
    // Hedging allows sending multiple concurrent requests
    builder.ConfigureWeightedGroups(static options =>
    {
        options.SelectionMode = WeightedGroupSelectionMode.EveryAttempt;

        options.Groups.Add(new WeightedUriEndpointGroup()
        {
            Endpoints =
            {
                // Imagine A/B testing
                new() { Uri = new("https://example.net/api/a"), Weight = 33 },
                new() { Uri = new("https://example.net/api/b"), Weight = 33 },
                new() { Uri = new("https://example.net/api/c"), Weight = 33 }
            }
        });
    });
});

De voorgaande code:

• Voegt de hedging-handler toe aan de IHttpClientBuilder.
• Configureert de IRoutingStrategyBuilder om de ConfigureWeightedGroups methode te gebruiken voor het configureren van de gewogen groepen.
• Stelt de SelectionMode in op WeightedGroupSelectionMode.EveryAttempt.
• Hiermee wordt een WeightedEndpointGroup aan de weightedGroup aanvraag toegevoegd waarmee 33% van de aanvragen naar het https://example.net/api/a eindpunt wordt gerouteerd, 33% van de aanvragen naar het https://example.net/api/b eindpunt en 33% van de aanvragen naar het https://example.net/api/c eindpunt.

Zie Voor meer informatie Polly docs: Hedging resilience strategy.

Het is gebruikelijk om een geordende groep of gewogen groep te configureren, maar het is geldig om beide te configureren. Het gebruik van geordende en gewogen groepen is handig in scenario's waarin u een percentage van de aanvragen naar een ander eindpunt wilt verzenden. Dit is het geval bij A/B-tests.

Aangepaste tolerantiehandlers toevoegen

Als u meer controle wilt hebben, kunt u de tolerantiehandlers aanpassen met behulp van de AddResilienceHandler API. Deze methode accepteert een delegaat die het ResiliencePipelineBuilder<HttpResponseMessage> exemplaar configureert dat wordt gebruikt om de strategieën voor tolerantie te creëren.

Als u een benoemde tolerantiehandler wilt configureren, roept u de AddResilienceHandler extensiemethode aan met de naam van de handler. In het volgende voorbeeld wordt een benoemde tolerantiehandler geconfigureerd met de naam "CustomPipeline".

httpClientBuilder.AddResilienceHandler(
    "CustomPipeline",
    static builder =>
{
    // See: https://www.pollydocs.org/strategies/retry.html
    builder.AddRetry(new HttpRetryStrategyOptions
    {
        // Customize and configure the retry logic.
        BackoffType = DelayBackoffType.Exponential,
        MaxRetryAttempts = 5,
        UseJitter = true
    });

    // See: https://www.pollydocs.org/strategies/circuit-breaker.html
    builder.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
    {
        // Customize and configure the circuit breaker logic.
        SamplingDuration = TimeSpan.FromSeconds(10),
        FailureRatio = 0.2,
        MinimumThroughput = 3,
        ShouldHandle = static args =>
        {
            return ValueTask.FromResult(args is
            {
                Outcome.Result.StatusCode:
                    HttpStatusCode.RequestTimeout or
                        HttpStatusCode.TooManyRequests
            });
        }
    });

    // See: https://www.pollydocs.org/strategies/timeout.html
    builder.AddTimeout(TimeSpan.FromSeconds(5));
});

De voorgaande code:

• Voegt een resiliencehandler toe met de naam "CustomPipeline" als pipelineName aan de servicecontainer.
• Voegt een herhalingsstrategie toe met exponentiële terugschakeling, vijf keer opnieuw proberen, en jitter-voorkeur aan de weerstandsinstellingen.
• Voegt een circuitonderbrekerstrategie toe met een steekproefduur van 10 seconden, een foutverhouding van 0,2 (20%), een minimale doorvoer van drie en een predicaat dat HTTP-statuscodes RequestTimeout en TooManyRequests verwerkt aan de resilience builder.
• Hiermee voegt u een time-outstrategie met een time-out van vijf seconden toe aan de resilience builder.

Er zijn veel opties beschikbaar voor elk van de tolerantiestrategieën. Zie de Documenten van Polly: Strategieën voor meer informatie. Voor meer informatie over het configureren van ShouldHandle gedelegeerden, zie de Polly-documenten Foutafhandeling in reactieve strategieën.

Dynamisch opnieuw laden

Polly biedt ondersteuning voor dynamisch opnieuw laden van de geconfigureerde tolerantiestrategieën. Dit betekent dat u de configuratie van de tolerantiestrategieën tijdens runtime kunt wijzigen. Als u dynamisch opnieuw laden wilt inschakelen, gebruikt u de juiste AddResilienceHandler overload-functie die de ResilienceHandlerContext blootlegt. Gezien de context, kies EnableReloads van de bijbehorende opties voor de veerkrachtstrategie:

httpClientBuilder.AddResilienceHandler(
    "AdvancedPipeline",
    static (ResiliencePipelineBuilder<HttpResponseMessage> builder,
        ResilienceHandlerContext context) =>
    {
        // Enable reloads whenever the named options change
        context.EnableReloads<HttpRetryStrategyOptions>("RetryOptions");

        // Retrieve the named options
        var retryOptions =
            context.GetOptions<HttpRetryStrategyOptions>("RetryOptions");

        // Add retries using the resolved options
        builder.AddRetry(retryOptions);
    });

De voorgaande code:

• Voegt een resiliencehandler toe met de naam "AdvancedPipeline" als pipelineName aan de servicecontainer.
• Hiermee kunt u de "AdvancedPipeline"-pijplijn opnieuw laden wanneer de genoemde RetryStrategyOptions opties veranderen.
• Haalt de benoemde opties op uit de IOptionsMonitor<TOptions> service.
• Voegt een retry-strategie toe met de opgehaalde opties aan de resilience builder.

Zie Polly-documenten voor meer informatie: Geavanceerde afhankelijkheidsinjectie.

Dit voorbeeld is afhankelijk van een sectie met opties die kan worden gewijzigd, zoals een appsettings.json-bestand . Houd rekening met het volgende appsettings.json-bestand :

{
    "RetryOptions": {
        "Retry": {
            "BackoffType": "Linear",
            "UseJitter": false,
            "MaxRetryAttempts": 7
        }
    }
}

Stel nu dat deze opties zijn gebonden aan de configuratie van de app, waarbij HttpRetryStrategyOptions wordt gekoppeld aan de "RetryOptions" sectie:

var section = builder.Configuration.GetSection("RetryOptions");

builder.Services.Configure<HttpStandardResilienceOptions>(section);

Zie het patroon Opties in .NET voor meer informatie.

Voorbeeld van gebruik

Uw app is afhankelijk van afhankelijkheidsinjectie om het ExampleClient en bijbehorende probleem HttpClientop te lossen. De code bouwt de IServiceProvider en lost de ExampleClient ervan op.

IHost host = builder.Build();

ExampleClient client = host.Services.GetRequiredService<ExampleClient>();

await foreach (Comment? comment in client.GetCommentsAsync())
{
    Console.WriteLine(comment);
}

De voorgaande code:

• De IServiceProvider wordt opgebouwd vanuit de ServiceCollection.
• Los de ExampleClient op uit de IServiceProvider.
• Roept de GetCommentsAsync methode aan op de ExampleClient om de opmerkingen op te halen.
• Schrijft elke opmerking naar de console.

Stel dat het netwerk uitvalt of dat de server niet meer reageert. In het volgende diagram ziet u hoe de tolerantiestrategieën de situatie afhandelen, gezien de ExampleClient en de GetCommentsAsync methode:

In het voorgaande diagram ziet u:

• ExampleClient stuurt een HTTP GET-verzoek naar de /comments-endpoint.
• De HttpResponseMessage waarde wordt geëvalueerd:
  • Als het antwoord is geslaagd (HTTP 200), wordt het antwoord geretourneerd.
  • Als het antwoord mislukt (HTTP-niet-200), gebruikt de tolerantiepijplijn de geconfigureerde strategieën voor tolerantie.

Hoewel dit een eenvoudig voorbeeld is, ziet u hoe de tolerantiestrategieën kunnen worden gebruikt voor het afhandelen van tijdelijke fouten. Zie Polly-documenten voor meer informatie: Strategieën.

Bekende problemen

In de volgende secties worden verschillende bekende problemen beschreven.

Compatibiliteit met het Grpc.Net.ClientFactory pakket

Als u versie Grpc.Net.ClientFactory of eerder gebruikt2.63.0, kan het inschakelen van de standaardtolerantie- of hedging-handlers voor een gRPC-client een runtime-uitzondering veroorzaken. Bekijk met name het volgende codevoorbeeld:

services
    .AddGrpcClient<Greeter.GreeterClient>()
    .AddStandardResilienceHandler();

De voorgaande code resulteert in de volgende uitzondering:

System.InvalidOperationException: The ConfigureHttpClient method isn't supported when creating gRPC clients. Unable to create client with name 'GreeterClient'.

U kunt dit probleem oplossen door een upgrade naar Grpc.Net.ClientFactory versie 2.64.0 of hoger uit te voeren.

Er is een buildtijdcontrole die verifieert of u versie Grpc.Net.ClientFactory of eerder gebruikt, en als dat zo is, genereert de controle een compilatiewaarschuwing. U kunt de waarschuwing onderdrukken door de volgende eigenschap in uw projectbestand in te stellen:

<PropertyGroup>
  <SuppressCheckGrpcNetClientFactoryVersion>true</SuppressCheckGrpcNetClientFactoryVersion>
</PropertyGroup>

Compatibiliteit met .NET Application Insights

Als u .NET Application Insights versie 2.22.0 of lager gebruikt, kan het inschakelen van tolerantiefunctionaliteit in uw toepassing ertoe leiden dat alle Application Insights-telemetrie ontbreekt. Het probleem treedt op wanneer de tolerantiefunctionaliteit wordt geregistreerd vóór Application Insights-services. Bekijk het volgende voorbeeld dat het probleem veroorzaakt:

// At first, we register resilience functionality.
services.AddHttpClient().AddStandardResilienceHandler();

// And then we register Application Insights. As a result, Application Insights doesn't work.
services.AddApplicationInsightsTelemetry();

Het probleem kan worden opgelost door .NET Application Insights bij te werken naar versie 2.23.0 of hoger. Als u deze niet kunt bijwerken, los dan het probleem op door Application Insights-services te registreren voordat de resilientiefunctionaliteit, zoals hieronder getoond, wordt uitgevoerd.

// We register Application Insights first, and now it is working correctly.
services.AddApplicationInsightsTelemetry();
services.AddHttpClient().AddStandardResilienceHandler();