NResilience 0.26.0

NResilience

Prevent cascading failures in your .NET applications.

A struggling dependency can hang your requests, tie up your threads, and crash your application. Blind retries often make the problem worse by overwhelming the failing service. NResilience wraps your calls in retries, deadlines, attempt timeouts, and circuit breakers so your app degrades gracefully instead of crashing.

Why NResilience?

NResilience replaces complex fluent builders, confusing policy ordering, and mandatory Build() calls with simple values and C# with expressions.

• No fluent builders. Configure policies using with expressions to change one setting while keeping the rest.
• Sensible defaults. Get a working, retried HTTP call with one line of code.
• One method for everything. Use RunAsync for HTTP calls, database queries, or queue reads.
• Measured, not guessed. Attempt ceilings, circuit breaker trips, and even the concurrency limit are measured from what the dependency actually does, so you never guess a millisecond figure per dependency.
• It knows when the problem is local. Saturation.Above(5) stops those measurements learning from a duration that is mostly this process's own thread-pool queue - the one incident where every measured bound would otherwise loosen at once, and the breaker would sit quiet because the dependency really is fine.
• Retry budget. A cap on retries as a fraction of traffic, on by default, so a fleet of clients cannot overwhelm a struggling dependency.
• Hedging. When a call is slow, a duplicate request races it. Hedges pause while the dependency degrades, so they never pile onto a struggling service.
• Deadline propagation. Deadlines travel across services: the gRPC interceptor sends grpc-timeout, and the ASP.NET middleware reads what a caller sent so outbound calls inherit it.
• Testable. Scripted callbacks, a recording listener, and fault injection make policies deterministic in tests.
• It explains itself. policy.Explain() prints the worst case attempt by attempt, names the bound that binds first, and reports which measured terms are warm - so "how long can this call take?" has an answer you can read.
• Telemetry. Every call raises one event carrying its verdict, retries, and delays; meters and an activity source expose them.
• Production-ready. Built-in analyzers catch common mistakes, such as passing the wrong cancellation token.
• Native AOT compatible. Zero external dependencies and no reflection.

Get started

Add NResilience to your project:

dotnet add package NResilience

For most HTTP scenarios, use the pre-configured client:

// Create one client for the application's lifetime
private static readonly HttpClient Client = HttpResilience.CreateClient();

private static async Task<User?> GetUserAsync(int id, CancellationToken cancellationToken) =>
    await Client.GetFromJsonAsync<User>(new Uri($"https://api.example.com/users/{id}"), cancellationToken);

Every call this client makes now uses three attempts with exponential backoff, a 30-second deadline, and HTTP-aware retry logic (for example, it retries a 503 but not a 404).

Simple configuration

Policies in NResilience are values. You can derive a new policy from an existing one using a with expression:

var slowPolicy = Resilience.Http with { Attempts = 5, Deadline = TimeSpan.FromSeconds(20) };

Beyond HTTP

Use RunAsync to wrap any asynchronous work, such as a database call or a third-party SDK:

var api = Resilience.Default;

string name = await api.RunAsync(attempt => db.ReadNameAsync(id, attempt), cancellationToken);

The attempt token is cancelled when the specific attempt hits its timeout, while the cancellationToken cancels the entire call.

Handle failures without exceptions

Use TryRunAsync to branch on the outcome instead of catching exceptions:

CallResult<User> result = await api.TryRunAsync(attempt => FetchAsync(attempt), cancellationToken);
User best = result.TryGetValue(out User? fetched) ? fetched : cache.LastKnownGood;

Performance and correctness

NResilience is built for high-performance .NET applications:

• Low overhead. A flat execution path ensures that cost doesn't grow as you add more policy settings. Overhead is one allocation per call, and that ceiling is gated in CI.
• Built-in analyzers. Seven diagnostics ship with the package to prevent silent failures.
• Native AOT. Fully compatible with net8.0 and net10.0 trimming and AOT publishing.

Documentation

For more information, see these resources:

• Quick start - get a retried HTTP call working in two minutes.
• Key concepts - learn the core terminology.
• Guides - see worked scenarios for common patterns.
• Features - detailed explanations of every configuration option.
• Migrating from Polly - a translation guide and behavioral differences.

Packages