CSharpEssentials.Resilience
8.0.0
dotnet add package CSharpEssentials.Resilience --version 8.0.0
NuGet\Install-Package CSharpEssentials.Resilience -Version 8.0.0
<PackageReference Include="CSharpEssentials.Resilience" Version="8.0.0" />
<PackageVersion Include="CSharpEssentials.Resilience" Version="8.0.0" />
<PackageReference Include="CSharpEssentials.Resilience" />
paket add CSharpEssentials.Resilience --version 8.0.0
#r "nuget: CSharpEssentials.Resilience, 8.0.0"
#:package CSharpEssentials.Resilience@8.0.0
#addin nuget:?package=CSharpEssentials.Resilience&version=8.0.0
#tool nuget:?package=CSharpEssentials.Resilience&version=8.0.0
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
ExecuteAsyncorRetryIfFailedis cancelled and the operation throwsOperationCanceledException, the exception is rethrown andWithFallbackdoes not run the fallback. - If the caller cancels after an attempt returned a retryable failed
Result,ExecuteAsync,RetryIfFailedandWithFallbackthrowOperationCanceledExceptioninstead 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
OperationCanceledExceptionwhile the caller's token is cancelled, that exception is returned as anUnexpectederror. - An
OperationCanceledExceptionfrom another token, such as anHttpClienttimeout, 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 | Versions 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. |
-
.NETStandard 2.1
- CSharpEssentials.Errors (>= 8.0.0)
- CSharpEssentials.Results (>= 8.0.0)
- Polly.Core (>= 8.0.0 && < 9.0.0)
- System.Text.Json (>= 9.0.4)
-
net10.0
- CSharpEssentials.Errors (>= 8.0.0)
- CSharpEssentials.Results (>= 8.0.0)
- Polly.Core (>= 8.0.0 && < 9.0.0)
-
net11.0
- CSharpEssentials.Errors (>= 8.0.0)
- CSharpEssentials.Results (>= 8.0.0)
- Polly.Core (>= 8.0.0 && < 9.0.0)
-
net9.0
- CSharpEssentials.Errors (>= 8.0.0)
- CSharpEssentials.Results (>= 8.0.0)
- Polly.Core (>= 8.0.0 && < 9.0.0)
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 |