NResilience 0.32.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 awareness stops those measurements learning from this process's own thread-pool queue - the one incident where every measured bound loosens at once while the dependency 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.
• It reads the quota the dependency publishes. Most large APIs send how much allowance is left on every response. The HTTP handler reads it, keeps it per host, and refuses an attempt locally before the 429 - no rate to guess, because the dependency supplies it.
• 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.
• Criticality propagation. How much a request matters travels with it, so a backfill stops spending the retry capacity a checkout needs and is never hedged. The library carries the level and holds back amplification; what to shed stays your decision.
• Drain-aware shutdown. When the host starts shutting down, calls stop retrying into the rollout and deadlines clamp to what is left of the grace period. On by default for registered policies, because a retry sent after the load balancer stopped routing here is one nobody will read the answer to.
• Testable. Scripted callbacks, a recording listener, and fault injection make policies deterministic in tests.
• Simulate before you ship. Run your policy against a modeled brownout on a virtual clock and read the load multiplier, the availability, and the p99 it produces. Five simulated minutes cost about as much as a unit test.
• It explains itself. One call prints the worst-case timeline attempt by attempt 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