LinKit.Resilience 1.3.1

dotnet add package LinKit.Resilience --version 1.3.1
                    
NuGet\Install-Package LinKit.Resilience -Version 1.3.1
                    
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="LinKit.Resilience" Version="1.3.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="LinKit.Resilience" Version="1.3.1" />
                    
Directory.Packages.props
<PackageReference Include="LinKit.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 LinKit.Resilience --version 1.3.1
                    
#r "nuget: LinKit.Resilience, 1.3.1"
                    
#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 LinKit.Resilience@1.3.1
                    
#: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=LinKit.Resilience&version=1.3.1
                    
Install as a Cake Addin
#tool nuget:?package=LinKit.Resilience&version=1.3.1
                    
Install as a Cake Tool

LinKit.Resilience

LinKit.Resilience provides an explicit async execution pipeline with retries, per-attempt timeout, optional circuit breaker, configurable transient-error filtering, and TimeProvider support for deterministic tests.

Install

dotnet add package LinKit.Resilience

Execute an operation

using LinKit.Core.Resilience;
using LinKit.Resilience;

var options = new ResilienceOptions
{
    MaxRetries = 2, // additional attempts after the first call
    RetryDelay = TimeSpan.FromMilliseconds(200),
    MaxRetryDelay = TimeSpan.FromSeconds(3),
    Backoff = BackoffType.Exponential,
    Timeout = TimeSpan.FromSeconds(5),
    BreakerFailureThreshold = 5,
    BreakerDurationSeconds = 30,
    ShouldRetry = exception => exception is HttpRequestException
};

var response = await ResiliencePipeline.ExecuteAsync(
    "inventory-api",
    cancellationToken => inventoryClient.GetAsync(productId, cancellationToken),
    options,
    cancellationToken);

The order is retry loop, circuit-breaker check, per-attempt timeout, then the action. A successful attempt resets the breaker (see Circuit breaker generations). MaxRetries = 2 permits up to three attempts. A zero breaker threshold disables the breaker.

A result-less overload takes Func<CancellationToken, Task> when the operation returns nothing.

Options reference

Property Default Purpose
MaxRetries 0 Additional attempts after the first failure; 0 disables retries.
RetryDelay 200 ms Base delay between attempts, before backoff and jitter.
Backoff Exponential How RetryDelay grows: Constant (1x), Linear (attempt + 1) or Exponential (2^attempt, capped at 2^20).
MaxRetryDelay 30 s Upper bound for a single retry delay, including the ±10% jitter.
Timeout null Per-attempt timeout; null disables it.
BreakerFailureThreshold 0 Consecutive failures that open the breaker; 0 disables the breaker.
BreakerDurationSeconds 30 Open window before a half-open probe is admitted.
ShouldRetry null Decides whether an exception is transient. The default retries everything except caller cancellation and an open circuit.

ResilienceOptions.Validate() throws ArgumentOutOfRangeException for a negative retry, delay, timeout or breaker value, and for BreakerDurationSeconds <= 0 while the breaker is enabled. ExecuteAsync calls it on every invocation.

Exceptions

Exception When
CircuitBreakerOpenException The breaker is open, so the action is not executed.
TimeoutException An attempt exceeded Timeout and the action observed the cancellation token.
OperationCanceledException The caller's token was cancelled; never retried.
ArgumentException / ArgumentNullException key is blank, or action/options is null.
ArgumentOutOfRangeException A numeric option is outside its supported range.

Circuit breaker generations

The circuit breaker exposes generation-aware overloads:

bool CanExecute(int durationSeconds, out long generation);
void OnSuccess(long generation);

A slow success admitted before the breaker opened can no longer close it: stale generations are ignored, and only the matching half-open probe closes the breaker. ResiliencePipeline uses the new overloads internally; the old parameterless members are kept for compatibility. Half-open probes that never report back are re-admitted after the open duration instead of wedging the breaker.

Cancellation and timeout

Caller cancellation is propagated and is not retried. A timeout cancels the token passed to the action and reports TimeoutException when the action responds to cancellation. An action that ignores its token may continue running after the pipeline times out; do not use this as a mechanism to forcibly stop non-cooperative work.

Retries can repeat side effects. Use only for operations that are idempotent or protected by an idempotency key, and configure ShouldRetry narrowly for transient errors. Circuit breaker state is held in a process-wide registry keyed by string; use unique, stable keys for independent dependencies.

DI registration

AddLinKitResilience() is available for service registration/composition. The pipeline itself is invoked explicitly with ResiliencePipeline.ExecuteAsync; adding the package does not automatically wrap CQRS handlers or apply attributes to requests.

Native AOT

The pipeline uses delegates and does not require dynamic code generation in its direct execution path. Validate the full app and provider composition with trimming/AOT analyzers and publish for the deployment RID.

Testing

Every overload accepts a TimeProvider, so tests can drive delays and the breaker with FakeTimeProvider instead of sleeping. The breaker registry is process-wide and keyed by string, so use unique keys per test to keep state isolated.

License

MIT. See the repository license.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.3.1 88 11/8/2026
1.2.1 106 10/31/2026
1.2.0 104 10/30/2026
1.1.0 98 10/22/2026
1.0.0 111 10/20/2026

v1.3.1: documentation and packaging patch - every public member now carries XML documentation (CS1591 is enforced as a build error) and the README was reviewed for accuracy. Previous release: v1.3.0 - Circuit breaker half-open state now admits exactly one probe, and the retry delay jitter is documented and bounded. Full documentation & release notes: https://quoclinh.id.vn/docs/linkit