HttpclientResilienceWrap 1.0.0

Httpclient Resilience Wrap

A resilient HTTP client library for .NET 8+, built on Polly v8, that provides retry, circuit breaker, timeout, and correlation ID propagation out of the box.

Supported frameworks: .NET 8 (LTS) · .NET 9 · .NET 10

Features

• Retry – exponential backoff with configurable attempts and base delay
• Circuit Breaker – trips after a failure ratio threshold, preventing cascading failures
• Timeout – per-attempt timeout independent of the outer cancellation token
• Correlation ID – auto-generated or caller-supplied ID attached to every outbound request header
• Two-tier configuration – service-wide defaults via ExternalServiceConfig, per-request overrides via HttpRequestParameter

Visual overview (pipelines, sequences, response contract): docs/resilience-flow.html — opens the interactive diagram in a new tab.

Request flow (sequence)

sequenceDiagram
  autonumber
  participant C as Caller
  participant R as "Retry (outer)"
  participant B as Circuit breaker
  participant T as "Timeout (per attempt)"
  participant H as HttpClient
  participant S as External API

  C->>+R: GetAsync / PostAsync / …
  R->>+B: execute attempt
  B->>+T: execute attempt
  T->>+H: SendAsync
  H->>+S: HTTP request
  S-->>-H: response
  H-->>-T: build HttpApiResponse
  T-->>-B: HttpApiResponse
  B-->>-R: HttpApiResponse
  R-->>-C: HttpApiResponse

  Note over R,S: On transient outcomes (e.g. 5xx, 429, 408, network errors), Retry may backoff and re-enter from Circuit breaker. If the circuit is open, the library returns a synthetic 503 envelope without calling S.

Demo API

A fully working Minimal API that exercises every feature is available in HttpclientResilienceWrap.Demo. Run dotnet run inside that folder and open Swagger to try retry, circuit breaker, timeout, correlation ID, typed/untyped responses, and config-less registration.

Installation

Install the latest version from NuGet:

dotnet add package HttpclientResilienceWrap

Or via the Package Manager Console:

Install-Package HttpclientResilienceWrap

Tip: Check the NuGet badge above for the latest available version.

Quick start: appsettings.json and Program.cs

Minimal configuration

{
  "MyApi": {
    "BaseUri": "https://api.example.com"
  }
}

Full configuration

Any property you omit keeps the default from the Configuration reference tables.

{
  "MyApi": {
    "ClientName": "MyApi",
    "BaseUri": "https://api.example.com",
    "ApiKey": "your-api-key",
    "Retry": 3,
    "RetryDelayMilliseconds": 1000,
    "TimeoutSeconds": 10,
    "EnableDebugLogging": true,
    "Handler": {
      "LifetimeMinutes": 5,
      "MaxConnectionsPerServer": 20,
      "AllowAutoRedirect": true,
      "MaxAutomaticRedirections": 3
    },
    "CircuitBreaker": {
      "Enabled": true,
      "MinimumThroughput": 10,
      "FailureRatio": 0.5,
      "SamplingDurationSeconds": 30,
      "BreakDurationSeconds": 30
    },
    "CorrelationId": {
      "Enabled": true,
      "HeaderName": "X-Correlation-Id",
      "GenerateIfAbsent": true
    }
  }
}

Register from configuration

Bind each section to a type that inherits ExternalServiceConfig and call InstallHttpClient once per API:

using HttpclientResilienceWrap.Extensions;
using HttpclientResilienceWrap.Options;

public sealed class MyApiConfig : ExternalServiceConfig { }

var myApiConfig = builder.Configuration
    .GetSection("MyApi")
    .Get<MyApiConfig>() ?? new MyApiConfig();

builder.Services.InstallHttpClient(myApiConfig);
// Equivalent: builder.Services.InstallHttpClient<MyApiConfig>(myApiConfig);

You need Microsoft.Extensions.Configuration.Binder (pulled in automatically with typical ASP.NET Core / hosting SDK projects).

Note: ApiKey and ApiPass bind into ExternalServiceConfig but are not attached to outbound requests automatically. Use HttpRequestParameter.Token or Headers, or your own middleware, to send credentials.

Multiple external services

appsettings.json

{
  "PaymentApi": {
    "BaseUri": "https://payments.example",
    "Retry": 3
  },
  "NotificationApi": {
    "BaseUri": "https://notify.example",
    "Retry": 2
  }
}

Program.cs

var paymentConfig = builder.Configuration
    .GetSection("PaymentApi")
    .Get<PaymentApiConfig>() ?? new PaymentApiConfig();

var notificationConfig = builder.Configuration
    .GetSection("NotificationApi")
    .Get<NotificationApiConfig>() ?? new NotificationApiConfig();

builder.Services.InstallHttpClient<PaymentApiConfig>(paymentConfig);
builder.Services.InstallHttpClient<NotificationApiConfig>(notificationConfig);

Dependency injection

InstallHttpClient overloads

Extension methods on IServiceCollection (HttpclientResilienceWrap.Extensions.HttpClientExtension):

Both overloads:

1. Register a named HttpClient with IHttpClientFactory using ClientName as the factory key.
2. Register IHttpClientService as keyed scoped with the same key.

Call once per external API. Different ClientName values stay fully isolated: separate connection pool, handler, and resilience state.

Config-less registration

When you don't need a config class or appsettings.json section — just pass a name and supply the URI per request:

builder.Services.InstallHttpClient("MyService");

Resolve with the same string key and set the target via HttpRequestParameter.Uri:

var response = await http.GetAsync<MyDto>(
    new HttpRequestParameter { Uri = new Uri("https://api.example.com/data") },
    ct);

This uses default resilience settings (no retries, 10s timeout, circuit breaker enabled). Useful for simple or ad-hoc calls where a full config class would be overkill.

Registration without JSON

For tests or hard-coded setup:

using HttpclientResilienceWrap.Extensions;
using HttpclientResilienceWrap.Options;

builder.Services.InstallHttpClient(new PaymentApiConfig
{
    BaseUri = "https://api.payments.example",
    Retry = 3,
});

For section binding from appsettings, see Quick start.

Resolving IHttpClientService

The keyed DI key is always config.ClientName. If you never assign ClientName, it defaults to the concrete config type’s name (e.g. PaymentApiConfig → "PaymentApiConfig"). If you set ClientName in code or configuration, use that exact string when resolving.

Constructor injection (typical in minimal APIs / controllers):

using Microsoft.Extensions.DependencyInjection;

public sealed class CheckoutService(
    [FromKeyedServices(nameof(PaymentApiConfig))] IHttpClientService paymentHttp)
{
    // paymentHttp uses the named HttpClient + pipeline for PaymentApiConfig
}

Manual resolution:

var paymentHttp = serviceProvider.GetRequiredKeyedService<IHttpClientService>(nameof(PaymentApiConfig));

To use the raw HttpClient registered by the same call, resolve it from IHttpClientFactory:

var client = httpClientFactory.CreateClient(nameof(PaymentApiConfig)); // or config.ClientName

IHttpClientService — sending requests

IHttpClientService exposes GetAsync, PostAsync, PutAsync, and DeleteAsync<T>, each taking a HttpRequestParameter (HttpclientResilienceWrap.Extensions) and an optional CancellationToken. They return HttpApiResponse<T> (same namespace).

using HttpclientResilienceWrap.Extensions;

HttpApiResponse<WidgetDto> response = await paymentHttp.GetAsync<WidgetDto>(
    new HttpRequestParameter { Path = "widgets/42" },
    cancellationToken);

Set BaseUri once in configuration; use Path for relative endpoints (combined with BaseUri). For a different host than BaseUri, set Uri instead of Path (if both are set, Path takes precedence).

new HttpRequestParameter
{
    Uri = new Uri("https://other-service.example/endpoint")
}

Inject and call (keyed IHttpClientService)

Resolve the client with [FromKeyedServices(...)] using the same key as ClientName (by default, the config type name):

using HttpclientResilienceWrap.Abstractions;
using HttpclientResilienceWrap.Extensions;
using Microsoft.Extensions.DependencyInjection;

public sealed class MyService(
    [FromKeyedServices(nameof(MyApiConfig))] IHttpClientService httpClient)
{
    public async Task<MyResponse?> GetDataAsync(CancellationToken ct)
    {
        var result = await httpClient.GetAsync<MyResponse>(
            new HttpRequestParameter
            {
                Path = "/data",
                Token = "bearer-token"
            },
            ct);

        return result.IsSuccessStatusCode ? result.Content : null;
    }
}

What each registration gives you

• A dedicated named HttpClient (ClientName, default = config type name)
• Its own base address and connection pool (via the factory + primary handler)
• Isolated resilience per registration — e.g. a payment outage does not trip the circuit for notifications

Configuration Reference

ExternalServiceConfig

Handler — HttpHandlerOption

CircuitBreaker — CircuitBreakerOption

CorrelationId — CorrelationIdOption

HttpRequestParameter — per-request overrides

HttpApiResponse<T>

Synthetic status codes (no exception from the pipeline)

For these cases the library returns an HttpApiResponse<T> instead of throwing; ErrorMessage carries the underlying message (exception or description).

Deserializing Content with System.Text.Json can still throw (e.g. invalid JSON) after a successful HTTP response.

Handling responses

var result = await httpClient.GetAsync<MyDto>(new HttpRequestParameter { Path = "items" }, ct);

if (!result.IsSuccessStatusCode)
{
    // HTTP 4xx/5xx from the API, or a synthetic code from the table above
    var status = result.StatusCode;
    var reason = result.ReasonPhrase;
}

if (result.ErrorMessage is not null)
{
    // Configuration, circuit breaker, network, or timeout — see synthetic table
    var detail = result.ErrorMessage;
}

var data = result.Content; // when successful and body deserialized

License

MIT