CSharpEssentials.Resilience 8.0.0

dotnet add package CSharpEssentials.Resilience --version 8.0.0
                    
NuGet\Install-Package CSharpEssentials.Resilience -Version 8.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CSharpEssentials.Resilience" Version="8.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CSharpEssentials.Resilience" Version="8.0.0" />
                    
Directory.Packages.props
<PackageReference Include="CSharpEssentials.Resilience" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CSharpEssentials.Resilience --version 8.0.0
                    
#r "nuget: CSharpEssentials.Resilience, 8.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CSharpEssentials.Resilience@8.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CSharpEssentials.Resilience&version=8.0.0
                    
Install as a Cake Addin
#tool nuget:?package=CSharpEssentials.Resilience&version=8.0.0
                    
Install as a Cake Tool

CSharpEssentials.Resilience

Retry, timeout, circuit breaker and fallback for operations that return Result or Result<T>. ResiliencePolicy is a fluent wrapper over Polly v8 (Polly.Core) that returns failures as Result values instead of throwing.

Benchmarks against Polly.Core (policy overhead, composed policies, RetryIfFailed, Result boxing) are in BENCHMARKS.md.

Installation

dotnet add package CSharpEssentials.Resilience

The package depends on Polly.Core [8.0.0,9.0.0), not the full Polly package. Add Polly yourself if you use the v7 API (Policy, AsyncRetryPolicy).

It is not marked Native AOT compatible. A Native AOT publish gets ILC warning IL3054 from Polly's DelegatingComponent.ExecuteCore (generic recursion; ILC says an exception is thrown at run time if that path is reached), and Polly's AddRetry<TResult> asks for DynamicallyAccessedMemberTypes.All on the result type, which the retry extensions cannot meet for Result<T> without trim warnings.

Namespaces

using CSharpEssentials.Resilience;    // ResiliencePolicy, ResiliencePolicy<T>, options records, Func and Result extensions
using CSharpEssentials.ResultPattern; // Result, Result<T>
using CSharpEssentials.Errors;        // Error, ErrorType

Quick start

// Retry
Result<User> user = await ResiliencePolicy
    .Create()
    .WithRetry(maxAttempts: 3, delay: TimeSpan.FromSeconds(1))
    .ExecuteAsync(_ => _db.GetUser(id));

// Retry, timeout and circuit breaker
Result<Data> data = await ResiliencePolicy
    .Create()
    .WithRetry(3)
    .WithTimeout(TimeSpan.FromSeconds(5))
    .WithCircuitBreaker(minimumThroughput: 10)
    .ExecuteAsync(_ => _api.GetData());

// Circuit breaker and fallback (fallback needs the typed ResiliencePolicy<T>)
Result<Product> product = await ResiliencePolicy<Product>
    .Create()
    .WithCircuitBreaker(minimumThroughput: 10, failureRatio: 0.5)
    .WithFallback(ct => _cache.GetAsync<Product>(id, ct))
    .ExecuteAsync(_ => _productService.GetProduct(id));

The samples build the policy inline for brevity. A policy is immutable, so in real code build it once and reuse it: in the benchmarks a retry policy built per call costs 12 to 15 times a prebuilt one.

Policy builder

ResiliencePolicy and ResiliencePolicy<T> are immutable structs: every With... call returns a new policy. default(ResiliencePolicy) and default(ResiliencePolicy<T>) behave like Create().

Method Parameters (defaults) Notes
WithRetry maxAttempts (3), delay (1 s), exponentialBackoff (true) maxAttempts counts retries after the first attempt, so the operation runs at most maxAttempts + 1 times. With exponentialBackoff the delay doubles after each retry
WithTimeout timeout Polly accepts 1 second to 1 day; any other value throws ValidationException when the policy is built
WithCircuitBreaker minimumThroughput (10), samplingDuration (1 min), breakDuration (30 s), failureRatio (0.5) Counts the same failures as the retry strategy
WithFallback Func<CancellationToken, Task<T>> or Func<CancellationToken, Task<Result<T>>> ResiliencePolicy<T> only; runs after the other strategies are exhausted
Create(ResiliencePolicyOptions) Retry, Timeout, CircuitBreaker records ResiliencePolicy only. WithRetry(RetryOptions), WithTimeout(TimeoutOptions) and WithCircuitBreaker(CircuitBreakerOptions) take the records on both policies
Create(Action<ResiliencePipelineBuilder>), FromPipeline(pipeline), ToPipeline() Interoperate with raw Polly pipelines (ResiliencePipelineBuilder<Result<T>> for ResiliencePolicy<T>)

Strategies nest in the order you add them, the first one outermost. WithRetry(3).WithTimeout(TimeSpan.FromSeconds(1)) applies the timeout to each attempt, while WithTimeout(TimeSpan.FromSeconds(1)).WithRetry(3) limits all attempts together. WithFallback always wraps the strategies of the policy it is called on. Create(ResiliencePolicyOptions) adds retry, then circuit breaker, then timeout.

var options = new ResiliencePolicyOptions
{
    Retry = new RetryOptions { MaxAttempts = 3, Delay = TimeSpan.FromSeconds(1) },
    Timeout = new TimeoutOptions { Timeout = TimeSpan.FromSeconds(5) },
    CircuitBreaker = new CircuitBreakerOptions { MinimumThroughput = 10, FailureRatio = 0.5, BreakDuration = TimeSpan.FromSeconds(30) }
};

Result<User> user = await ResiliencePolicy.Create(options).ExecuteAsync(_ => _db.GetUser(id));

The records default to the same values as the method parameters, plus TimeoutOptions.Timeout = 30 s.

What is retried

Both policies retry exceptions and failed Result / Result<T> values, and the circuit breaker counts the same failures. The non-generic ResiliencePolicy checks any return value that implements IResultBase; other return values count only when the delegate throws.

Errors of type Unauthorized, Forbidden, NotFound and Validation are not retried, because running the operation again gives the same answer. Every other failed result (Failure, Unexpected, Conflict and so on) is treated as transient. When the retries run out, the last failed result is returned.

Result<Order> order = await ResiliencePolicy
    .Create()
    .WithRetry(maxAttempts: 3)
    .ExecuteAsync(ct => _orderService.TryGetOrder(id, ct)); // returns Result<Order>

Delegate extensions

ExecuteAsync on a Func<Task>, Func<Task<T>> or Func<Task<Result<T>>> (with or without a CancellationToken parameter) runs it through an empty policy, so exceptions become failed results:

Func<Task<User>> getUser = () => _db.GetUser(id);
Result<User> user = await getUser.ExecuteAsync();

Func<CancellationToken, Task<User>> getUserWithToken = ct => _db.GetUser(id, ct);
Result<User> userWithToken = await getUserWithToken.ExecuteAsync(cancellationToken);

RetryIfFailed retries a Func<CancellationToken, Task<Result<T>>> or Func<CancellationToken, Task<Result>> with the same classification, parameters and defaults as WithRetry:

Func<CancellationToken, Task<Result<User>>> operation = ct => _db.TryGetUser(id, ct);
Result<User> result = await operation.RetryIfFailed(maxAttempts: 3, delay: TimeSpan.FromSeconds(1));

// Retry only errors you classify as transient
Result<User> classified = await operation.RetryIfFailed(
    shouldRetry: error => error.Code == "Db.Timeout",
    maxAttempts: 3,
    delay: TimeSpan.FromSeconds(1));

Both forms reuse a cached pipeline, keyed by (maxAttempts, delay, exponentialBackoff) and by whether a predicate is used, up to 64 entries per result type. The predicate form passes the delegate through a pooled ResilienceContext, so it does not allocate per call.

shouldRetry replaces the default classification. An exception thrown by the operation is converted to the error that would be returned for it (ErrorType.Unexpected) and passed to the predicate too, so an exception the predicate rejects is not retried. The predicate can run more than once for the same attempt, so keep it pure and cheap. If it throws, retrying stops and the exception is returned as an Unexpected error.

Errors and cancellation

Resilience failures are returned as Error values:

  • Error.Failure("Resilience.Timeout", "Operation timed out.")
  • Error.Failure("Resilience.CircuitBroken", "Circuit breaker is open.")

When retries are exhausted, the last exception is returned as Error.Exception(ex, ErrorType.Unexpected), with the exception type name as code. An exception thrown by the WithFallback delegate is returned the same way.

Cancellation of the caller's token is never converted to an error:

  • When the token passed to ExecuteAsync or RetryIfFailed is cancelled and the operation throws OperationCanceledException, the exception is rethrown and WithFallback does not run the fallback.
  • If the caller cancels after an attempt returned a retryable failed Result, ExecuteAsync, RetryIfFailed and WithFallback throw OperationCanceledException instead of returning that result. This holds whether the cancel lands during an attempt, during the backoff delay or right after the final attempt, and also for policies without a retry strategy (circuit breaker only, timeout only).
  • If the operation throws an exception other than OperationCanceledException while the caller's token is cancelled, that exception is returned as an Unexpected error.
  • An OperationCanceledException from another token, such as an HttpClient timeout, is a normal failure: it is retried and it triggers the fallback.

Polly integration

Create(Action<ResiliencePipelineBuilder>) gives direct access to the Polly builder:

using Polly;
using Polly.Retry;

Result<Data> result = await ResiliencePolicy
    .Create(builder => builder.AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromSeconds(1),
        BackoffType = DelayBackoffType.Exponential
    }))
    .ExecuteAsync(_ => _api.GetData());

A strategy added this way uses Polly's own ShouldHandle, which ignores returned Result values unless you set it.

Upgrading to 8.0

An exception thrown by the WithFallback delegate is now returned as an ErrorType.Unexpected error, like an exception from the operation itself. Earlier versions returned it as ErrorType.Failure. A TimeoutRejectedException or BrokenCircuitException thrown by the fallback delegate now gets the same codes as on the operation, Resilience.Timeout or Resilience.CircuitBroken, instead of the exception type name.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on CSharpEssentials.Resilience:

Package Downloads
CSharpEssentials.GcpSecretManager

A powerful .NET configuration provider for Google Cloud Secret Manager that enables seamless secret management in your applications. Features include region-specific secret handling, flexible filtering options, batch processing, automatic secret rotation, built-in retry policies, and JSON value flattening support. Perfect for cloud-native applications requiring secure and scalable secret management.

CSharpEssentials.Http

HttpClient extensions that bridge HTTP calls to the Result pattern. Provides GetFromJsonAsResultAsync, PostAsJsonAsResultAsync, status code mapping, and Polly resilience integration.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.0.0 192 11/9/2026
7.0.0 209 10/20/2026
6.5.2 198 10/10/2026
6.5.1 196 10/10/2026
6.5.0 191 10/9/2026
6.4.0 184 10/9/2026
6.3.0 190 10/8/2026
6.2.0 191 10/8/2026
6.1.0 206 10/7/2026
6.0.0 197 10/7/2026
5.2.1 193 10/7/2026
5.2.0 201 10/7/2026
5.1.0 180 10/7/2026
5.0.0 195 10/6/2026
4.1.0 184 10/6/2026
4.0.0 198 10/5/2026
3.2.3 359 5/31/2026
3.2.2 211 5/31/2026
3.2.1 200 5/31/2026
3.2.0 195 5/30/2026