Dayanıklı HTTP uygulamaları oluşturma: Temel geliştirme desenleri

Geçici hata hatalarından kurtarabilecek güçlü HTTP uygulamaları oluşturmak yaygın bir gereksinimdir. Bu makalede, aktarılan temel kavramlar genişletildiğinden, dayanıklı uygulama geliştirmeye giriş makalesini okuduğunuz varsayılır. Dayanıklı HTTP uygulamaları oluşturmaya yardımcı olmak için Microsoft.Extensions.Http.Resilience NuGet paketi, özellikle için HttpClientdayanıklılık mekanizmaları sağlar. Bu NuGet paketi, kitaplığı ve Microsoft.Extensions.Resiliencepopüler bir açık kaynak projesi olan Polly'yi kullanır. Daha fazla bilgi için bkz . Polly.

Kullanmaya başlayın

HTTP uygulamalarında dayanıklılık desenlerini kullanmak için Microsoft.Extensions.Http.Resilience NuGet paketini yükleyin.

dotnet add package Microsoft.Extensions.Http.Resilience --version 8.0.0

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

Daha fazla bilgi için bkz . dotnet add package veya Manage package dependencies in .NET applications.

HTTP istemcisine dayanıklılık ekleme

'a dayanıklılık eklemek içinHttpClient, kullanılabilir IHttpClientBuilder yöntemlerden herhangi birini çağırarak döndürülen türe AddHttpClient bir çağrı zincirlersiniz. Daha fazla bilgi için bkz . .NET ile IHttpClientFactory.

Çeşitli dayanıklılık odaklı uzantılar mevcuttur. Bazıları standarttır, bu nedenle çeşitli sektör en iyi uygulamalarını kullanırken diğerleri daha özelleştirilebilir. Dayanıklılık eklerken yalnızca bir dayanıklılık işleyicisi eklemeniz ve yığınlama işleyicilerinden kaçınmanız gerekir. Birden çok dayanıklılık işleyicisi eklemeniz gerekiyorsa, dayanıklılık stratejilerini özelleştirmenizi sağlayan uzantı yöntemini kullanmayı AddResilienceHandler düşünmelisiniz.

Standart dayanıklılık işleyicisi ekleme

Standart dayanıklılık işleyicisi, istekleri göndermek ve geçici hataları işlemek için varsayılan seçeneklerle birlikte birbirinin üzerine yığılmış birden çok dayanıklılık stratejisi kullanır. Standart dayanıklılık işleyicisi, bir AddStandardResilienceHandler örnekte uzantı yöntemi çağrılarak IHttpClientBuilder eklenir.

var services = new ServiceCollection();

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

Yukarıdaki kod:

• Bir ServiceCollection örnek oluşturur.
• Hizmet kapsayıcısına HttpClient türü için bir ExampleClient ekler.
• HttpClient temel adres olarak kullanılacak "https://jsonplaceholder.typicode.com" şekilde yapılandırılır.
• httpClientBuilder Bu makaledeki diğer örneklerde kullanılan öğesini oluşturur.

Daha gerçek bir örnek, .NET Genel Ana Bilgisayar makalesinde açıklandığı gibi barındırmayı temel alır. Microsoft.Extensions.Hosting NuGet paketini kullanarak aşağıdaki güncelleştirilmiş örneği göz önünde bulundurun:

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

Yukarıdaki kod el ile ServiceCollection oluşturma yaklaşımına benzer, ancak bunun yerine hizmetlerini kullanıma sunan bir konak oluşturmak için öğesine dayanır Host.CreateApplicationBuilder() .

ExampleClient aşağıdaki gibi tanımlanır:

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

Yukarıdaki kod:

• kabul eden bir ExampleClient oluşturucuya sahip bir HttpClienttür tanımlar.
• Uç noktaya GET isteği GetCommentsAsync gönderen ve yanıtı döndüren bir /comments yöntemi kullanıma sunar.

Türü Comment aşağıdaki gibi tanımlanır:

namespace Http.Resilience.Example;

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

Bir () oluşturduğunuzu IHttpClientBuilder ve uygulamayı ve buna karşılık gelen httpClientBuilder modeli anladığınıza ExampleClient göre aşağıdaki örneği göz önündeComment bulundurun:

httpClientBuilder.AddStandardResilienceHandler();

Yukarıdaki kod, standart dayanıklılık işleyicisini öğesine HttpClientekler. Çoğu dayanıklılık API'sinde olduğu gibi, varsayılan seçenekleri ve uygulanan dayanıklılık stratejilerini özelleştirmenizi sağlayan aşırı yüklemeler vardır.

Standart dayanıklılık işleyicisi varsayılanları

Varsayılan yapılandırma beş dayanıklılık stratejisini aşağıdaki sırayla zincirler (en dıştan en içe):

Yeniden denemeler ve devre kesiciler

Yeniden deneme ve devre kesici stratejileri belirli HTTP durum kodları ve özel durumlar kümesini işler. Aşağıdaki HTTP durum kodlarını göz önünde bulundurun:

• HTTP 500 ve üzeri (Sunucu hataları)
• HTTP 408 (İstek zaman aşımı)
• HTTP 429 (Çok fazla istek var)

Ayrıca, bu stratejiler aşağıdaki özel durumları işler:

• HttpRequestException
• TimeoutRejectedException

Belirli bir HTTP yöntemleri listesi için yeniden denemeleri devre dışı bırakma

Varsayılan olarak, standart dayanıklılık işleyicisi tüm HTTP yöntemleri için yeniden denemeler yapacak şekilde yapılandırılır. Bazı uygulamalar için bu tür davranışlar istenmeyen ve hatta zararlı olabilir. Örneğin, post isteği veritabanına yeni bir kayıt eklerse, böyle bir istek için yeniden denemeler yapmak verilerin çoğaltılmasıyla sonuçlanabilir. Belirli bir HTTP yöntemleri listesi için yeniden denemeleri devre dışı bırakmanız gerekiyorsa DisableFor(HttpRetryStrategyOptions, HttpMethod[]) yöntemini kullanabilirsiniz:

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

Alternatif olarak, POST, PATCH, PUT, DELETEve CONNECT istekleri için yeniden denemeleri devre dışı bırakan DisableForUnsafeHttpMethods(HttpRetryStrategyOptions) yöntemini kullanabilirsiniz. RFC 'e göre, bu yöntemler güvensiz olarak değerlendirilir; anlamlarına göre salt okunur olmadıkları anlamına gelmektedir.

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

Standart riskten korunma işleyicisi ekleme

Standart riskten korunma işleyicisi, isteğin yürütülmesini standart bir riskten korunma mekanizmasıyla sarmalar. Hedging yavaş istekleri paralel olarak yeniden denenir.

Standart riskten korunma işleyicisini kullanmak için uzantı yöntemini çağırın AddStandardHedgingHandler . Aşağıdaki örnek, ExampleClient öğesini standart riskten korunma işleyicisini kullanacak şekilde yapılandırılır.

httpClientBuilder.AddStandardHedgingHandler();

Yukarıdaki kod, standart riskten korunma işleyicisini öğesine HttpClientekler.

Standart riskten korunma işleyicisi varsayılanları

Standart risk koruması, iyi durumda olmayan uç noktaların hedged edilmediğinden emin olmak için bir devre kesici havuzu kullanır. Varsayılan olarak, havuzdan yapılan seçim URL yetkilisini (scheme + host + port) temel alır.

Yukarıdaki kod, standart riskten korunma işleyicisini öğesine IHttpClientBuilderekler. Varsayılan yapılandırma beş dayanıklılık stratejisini aşağıdaki sırayla zincirler (en dıştan en içe):

Riskten korunma işleyicisi rota seçimini özelleştirme

Standart riskten korunma işleyicisini kullanırken, türdeki çeşitli uzantıları çağırarak istek uç noktalarının IRoutingStrategyBuilder seçilme şeklini özelleştirebilirsiniz. Bu, isteklerin yüzdesini farklı bir uç noktaya yönlendirmek istediğiniz A/B testi gibi senaryolar için yararlı olabilir:

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

Yukarıdaki kod:

• riskten korunma işleyicisini öğesine IHttpClientBuilderekler.
• IRoutingStrategyBuilder öğesini, sıralı grupları yapılandırmak için yöntemini kullanacak ConfigureOrderedGroups şekilde yapılandırılır.
• İsteklerin %3'ünün uç noktaya, isteklerin EndpointGroup %97'sini uç noktaya yönlendiren öğesine orderedGroup bir https://example.net/api/experimentalhttps://example.net/api/stable ekler.
• IRoutingStrategyBuilder öğesini yapılandırmak için yöntemini kullanacak ConfigureWeightedGroups şekilde yapılandırılır

Ağırlıklı bir grup yapılandırmak için türündeki ConfigureWeightedGroups yöntemini çağırın IRoutingStrategyBuilder . Aşağıdaki örnekte IRoutingStrategyBuilder , ağırlıklı grupları yapılandırmak için yöntemini kullanacak ConfigureWeightedGroups şekilde yapılandırılır.

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

Yukarıdaki kod:

• riskten korunma işleyicisini öğesine IHttpClientBuilderekler.
• IRoutingStrategyBuilder ağırlıklı grupları yapılandırmak için yöntemini kullanacak ConfigureWeightedGroups şekilde yapılandırılır.
• öğesini olarak SelectionModeWeightedGroupSelectionMode.EveryAttemptayarlar.
• İsteklerin %33'ünün uç noktaya, isteklerin %33'ünün WeightedEndpointGroup uç noktaya ve %33'ünün uç noktaya yönlendiren weightedGroup öğesine bir https://example.net/api/ahttps://example.net/api/b ekler.https://example.net/api/c

Daha fazla bilgi için bkz . Polly docs: Hedging dayanıklılık stratejisi.

Sıralı grup veya ağırlıklı grup yapılandırmak yaygın bir durum olsa da her ikisini de yapılandırmak için geçerlidir. İsteklerin yüzdesini A/B testi gibi farklı bir uç noktaya göndermek istediğiniz senaryolarda sıralı ve ağırlıklı grupların kullanılması yararlı olur.

Özel dayanıklılık işleyicileri ekleme

Daha fazla denetime sahip olmak için, API'yi kullanarak AddResilienceHandler dayanıklılık işleyicilerini özelleştirebilirsiniz. Bu yöntem, dayanıklılık stratejilerini ResiliencePipelineBuilder<HttpResponseMessage> oluşturmak için kullanılan örneği yapılandıran bir temsilci kabul eder.

Adlandırılmış dayanıklılık işleyicisini yapılandırmak için, işleyicinin adıyla uzantı yöntemini çağırın AddResilienceHandler . Aşağıdaki örnekte adlı "CustomPipeline"adlandırılmış bir dayanıklılık işleyicisi yapılandırılır.

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

Yukarıdaki kod:

• Hizmet kapsayıcısına adıyla "CustomPipeline"pipelineName bir dayanıklılık işleyicisi ekler.
• Dayanıklılık oluşturucusunun üstel geri çekilmesi, beş yeniden deneme ve değişim tercihi ile bir yeniden deneme stratejisi ekler.
• Örnekleme süresi 10 saniye, hata oranı 0,2 (%20), minimum aktarım hızı üç olan bir devre kesici stratejisi ve dayanıklılık oluşturucusunun RequestTimeoutTooManyRequests HTTP durum kodlarını işleyen bir koşul ekler.
• Dayanıklılık oluşturucusunun zaman aşımı süresi beş saniye olan bir zaman aşımı stratejisi ekler.

Dayanıklılık stratejilerinin her biri için birçok seçenek mevcuttur. Daha fazla bilgi için bkz . Polly belgeleri: Stratejiler. Temsilcileri yapılandırma ShouldHandle hakkında daha fazla bilgi için bkz . Polly belgeleri: Reaktif stratejilerde hata işleme.

Dinamik yeniden yükleme

Polly, yapılandırılmış dayanıklılık stratejilerinin dinamik olarak yeniden yüklenmesini destekler. Bu, çalışma zamanında dayanıklılık stratejilerinin yapılandırmasını değiştirebileceğiniz anlamına gelir. Dinamik yeniden yüklemeyi etkinleştirmek için, öğesini kullanıma AddResilienceHandlersunan uygun ResilienceHandlerContext aşırı yüklemeyi kullanın. Bağlam göz önüne alındığında, ilgili dayanıklılık stratejisi seçeneklerinin çağrısı EnableReloads :

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

Yukarıdaki kod:

• Hizmet kapsayıcısına adıyla "AdvancedPipeline"pipelineName bir dayanıklılık işleyicisi ekler.
• Adlandırılmış "AdvancedPipeline" seçenekler değiştiğinde RetryStrategyOptions işlem hattının yeniden yüklenmesini etkinleştirir.
• Hizmetten IOptionsMonitor<TOptions> adlandırılmış seçenekleri alır.
• Dayanıklılık oluşturucusunun alınan seçenekleriyle bir yeniden deneme stratejisi ekler.

Daha fazla bilgi için bkz . Polly belgeleri: Gelişmiş bağımlılık ekleme.

Bu örnek, appsettings.json dosyası gibi değiştirebilen bir seçenekler bölümüne dayanır. Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

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

Şimdi bu seçeneklerin uygulamanın yapılandırmasına bağlı olduğunu ve öğesini şu bölüme HttpRetryStrategyOptions bağladığını "RetryOptions" düşünün:

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

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

Daha fazla bilgi için bkz . .NET'te seçenekler deseni.

Örnek kullanım

Uygulamanız ve buna karşılık gelen öğesini çözümlemek için bağımlılık eklemeye ExampleClientHttpClient. Kod, öğesini IServiceProvider oluşturur ve çözümler ExampleClient .

IHost host = builder.Build();

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

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

Yukarıdaki kod:

• 'den IServiceProvideröğesini ServiceCollection oluşturur.
• 'den öğesini ExampleClientIServiceProviderçözümler.
• açıklamalarını GetCommentsAsync almak için üzerinde ExampleClient yöntemini çağırır.
• Her açıklamayı konsola yazar.

Ağın kapandığı veya sunucunun yanıt vermemeye başladığı bir durum düşünün. Aşağıdaki diyagramda ve yöntemine göre ExampleClient dayanıklılık stratejilerinin durumu nasıl ele alacağını gösterilmektedir GetCommentsAsync :

Yukarıdaki diyagramda aşağıdakiler gösterilmiştir:

• uç ExampleClient noktaya bir HTTP GET isteği /comments gönderir.
• HttpResponseMessage değerlendirilir:
  • Yanıt başarılı olursa (HTTP 200), yanıt döndürülür.
  • Yanıt başarısız olursa (HTTP 200 olmayan), dayanıklılık işlem hattı yapılandırılan dayanıklılık stratejilerini kullanır.

Bu basit bir örnek olsa da, dayanıklılık stratejilerinin geçici hataları işlemek için nasıl kullanılabileceğini gösterir. Daha fazla bilgi için bkz . Polly belgeleri: Stratejiler.

Bilinen sorunlar

Aşağıdaki bölümlerde bilinen çeşitli sorunlar ayrıntılı olarak ele alınıyor.

Paketle Grpc.Net.ClientFactory uyumluluk

Sürüm veya önceki bir sürümü Grpc.Net.ClientFactory kullanıyorsanız2.63.0, gRPC istemcisi için standart dayanıklılık veya riskten korunma işleyicilerinin etkinleştirilmesi çalışma zamanı özel duruma neden olabilir. Özellikle aşağıdaki kod örneğini göz önünde bulundurun:

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

Yukarıdaki kod aşağıdaki özel duruma neden olur:

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

Bu sorunu çözmek için sürüme veya sonraki bir sürüme Grpc.Net.ClientFactory2.64.0 yükseltmenizi öneririz.

Sürüm veya önceki bir sürümü Grpc.Net.ClientFactory kullanıp kullanmadığınızı 2.63.0 doğrulayan bir derleme zamanı denetimi vardır ve denetimin derleme uyarısı oluşturup oluşturmadığını denetler. Proje dosyanızda aşağıdaki özelliği ayarlayarak uyarıyı gizleyebilirsiniz:

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

.NET Application Insights ile uyumluluk

.NET Application Insights kullanıyorsanız, uygulamanızda dayanıklılık işlevselliğini etkinleştirmek tüm Application Insights telemetri verilerinin eksik olmasını sağlayabilir. Dayanıklılık işlevselliği Application Insights hizmetlerinden önce kaydedildiğinde sorun oluşur. Soruna neden olan aşağıdaki örneği göz önünde bulundurun:

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

Bu sorun Application Insights'taki aşağıdaki hatadan kaynaklanır ve aşağıda gösterildiği gibi dayanıklılık işlevselliğinden önce Application Insights hizmetleri kaydedilerek düzeltilebilir:

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