Resilience

// Program.cs — Standard resilience handler covers 90% of use casesbuilder.Services.AddHttpClient<IPaymentGateway, PaymentGatewayClient>(client =>{    client.BaseAddress = new Uri("https://api.payments.example.com");}).AddStandardResilienceHandler(); // Retry + circuit breaker + timeout out of the box
// That's it. The standard handler configures:// - Retry: 3 attempts, exponential backoff, jitter// - Circuit breaker: 10% failure ratio over 30s sampling, 30s break// - Attempt timeout: 10s per attempt// - Total request timeout: 30s

builder.Services.AddHttpClient<ICatalogService, CatalogServiceClient>(client =>{    client.BaseAddress = new Uri("https://api.catalog.example.com");}).AddResilienceHandler("catalog", builder =>{    // Total timeout — outermost, caps total elapsed time    builder.AddTimeout(TimeSpan.FromSeconds(15));
    // Retry — exponential backoff with jitter    builder.AddRetry(new HttpRetryStrategyOptions    {        MaxRetryAttempts = 3,        BackoffType = DelayBackoffType.Exponential,        UseJitter = true,        Delay = TimeSpan.FromMilliseconds(500),        ShouldHandle = static args => ValueTask.FromResult(            args.Outcome.Result?.StatusCode is HttpStatusCode.RequestTimeout                or HttpStatusCode.TooManyRequests                or HttpStatusCode.ServiceUnavailable                || args.Outcome.Exception is HttpRequestException)    });
    // Circuit breaker — prevent cascading failures    builder.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions    {        FailureRatio = 0.5,        SamplingDuration = TimeSpan.FromSeconds(10),        MinimumThroughput = 10,        BreakDuration = TimeSpan.FromSeconds(30)    });
    // Per-attempt timeout — innermost    builder.AddTimeout(TimeSpan.FromSeconds(5));});

// For database calls, message queues, or any non-HTTP operationbuilder.Services.AddResiliencePipeline("database", builder =>{    builder        .AddRetry(new RetryStrategyOptions        {            MaxRetryAttempts = 3,            BackoffType = DelayBackoffType.Exponential,            Delay = TimeSpan.FromMilliseconds(200),            ShouldHandle = new PredicateBuilder()                .Handle<TimeoutException>()                .Handle<InvalidOperationException>(ex =>                    ex.Message.Contains("deadlock", StringComparison.OrdinalIgnoreCase))        })        .AddTimeout(TimeSpan.FromSeconds(10));});
// Inject and usepublic sealed class OrderRepository(    AppDbContext db,    [FromKeyedServices("database")] ResiliencePipeline pipeline){    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)    {        return await pipeline.ExecuteAsync(            async token => await db.Orders.FindAsync([id], token),            ct);    }}

// When the operation returns a specific type, use ResiliencePipeline<T>builder.Services.AddResiliencePipeline<string, HttpResponseMessage>("external-api", builder =>{    builder        .AddFallback(new FallbackStrategyOptions<HttpResponseMessage>        {            FallbackAction = static args =>            {                var response = new HttpResponseMessage(HttpStatusCode.OK)                {                    Content = new StringContent("{\"status\":\"degraded\",\"data\":[]}")                };                return Outcome.FromResultAsValueTask(response);            },            ShouldHandle = static args => ValueTask.FromResult(                args.Outcome.Exception is not null                || args.Outcome.Result?.IsSuccessStatusCode == false)        })        .AddRetry(new RetryStrategyOptions<HttpResponseMessage>        {            MaxRetryAttempts = 2,            Delay = TimeSpan.FromMilliseconds(500)        })        .AddTimeout(TimeSpan.FromSeconds(5));});

builder.Services.AddHttpClient<ISearchService, SearchServiceClient>()    .AddResilienceHandler("search-hedging", builder =>    {        builder.AddHedging(new HttpHedgingStrategyOptions        {            MaxHedgedAttempts = 2,            Delay = TimeSpan.FromMilliseconds(500) // Send parallel request after 500ms        });        builder.AddTimeout(TimeSpan.FromSeconds(3));    });

builder.Services.AddResiliencePipeline("monitored", (builder, context) =>{    // Polly v8 emits metrics via System.Diagnostics.Metrics automatically.    // ConfigureTelemetry wires structured logging for strategy events.    builder        .ConfigureTelemetry(new TelemetryOptions        {            LoggerFactory = context.ServiceProvider.GetRequiredService<ILoggerFactory>()        })        .AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 3 })        .AddCircuitBreaker(new CircuitBreakerStrategyOptions())        .AddTimeout(TimeSpan.FromSeconds(10));});
// In Program.cs — wire up OpenTelemetry to capture Polly metricsbuilder.Services.AddOpenTelemetry()    .WithMetrics(metrics => metrics.AddMeter("Polly"));

builder.Services.AddRateLimiter(options =>{    options.AddFixedWindowLimiter("fixed", opt =>    {        opt.PermitLimit = 100;        opt.Window = TimeSpan.FromSeconds(60);        opt.QueueLimit = 0;    });
    // Always return ProblemDetails with Retry-After on 429    options.OnRejected = async (context, ct) =>    {        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;        if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))            context.HttpContext.Response.Headers.RetryAfter =                ((int)retryAfter.TotalSeconds).ToString();        await context.HttpContext.Response.WriteAsJsonAsync(            new ProblemDetails { Title = "Too many requests", Status = 429 }, ct);    };});
app.UseRateLimiter();app.MapGet("/api/orders", ListOrders).RequireRateLimiting("fixed");

// BAD — v7 policy syntax, do not usevar retryPolicy = Policy    .Handle<HttpRequestException>()    .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)));
var response = await retryPolicy.ExecuteAsync(() => httpClient.GetAsync("/api/data"));

// GOOD — v8 pipeline via DIbuilder.Services.AddHttpClient<IDataService, DataServiceClient>()    .AddStandardResilienceHandler();

// BAD — manual resilience per call sitepublic async Task<Order> GetOrderAsync(Guid id){    try    {        return await _pipeline.ExecuteAsync(async ct =>            await _httpClient.GetFromJsonAsync<Order>($"/orders/{id}", ct));    }    catch (TimeoutRejectedException)    {        return Order.Empty;    }    catch (BrokenCircuitException)    {        return Order.Empty;    }}

// GOOD — resilience is configured at the HttpClient levelpublic async Task<Order?> GetOrderAsync(Guid id, CancellationToken ct){    var response = await _httpClient.GetAsync($"/orders/{id}", ct);    if (!response.IsSuccessStatusCode) return null;    return await response.Content.ReadFromJsonAsync<Order>(ct);}

// BAD — retrying a POST that creates a resource risks duplicatesbuilder.AddRetry(new RetryStrategyOptions{    MaxRetryAttempts = 5 // This will create 5 orders on transient failures!});

// GOOD — use idempotency key header for non-idempotent operationsbuilder.AddRetry(new HttpRetryStrategyOptions{    MaxRetryAttempts = 3,    ShouldHandle = static args => ValueTask.FromResult(        args.Outcome.Result?.StatusCode is HttpStatusCode.RequestTimeout            or HttpStatusCode.ServiceUnavailable)});
// Pair with idempotency key in the requesthttpClient.DefaultRequestHeaders.Add("Idempotency-Key", Guid.NewGuid().ToString());

// BAD — circuit breaker with no visibility into state changesbuilder.AddCircuitBreaker(new CircuitBreakerStrategyOptions());// How do you know when it trips? You don't.

// GOOD — Polly v8 metrics captured via OpenTelemetrybuilder.Services.AddOpenTelemetry()    .WithMetrics(metrics => metrics.AddMeter("Polly"));
// Dashboard alerts on: polly.circuit_breaker.state = Open