Polly .NET Resilience and Transient-Fault-Handling Library

The ResilienceContext class provides an execution-scoped instance that accompanies an operation through a Polly resilience pipeline. It allows you to share data and information between different phases of execution (pre-execution, mid-execution, and post-execution) and across different strategies within the same pipeline.

Key Properties

• OperationKey: A user-defined identifier for the operation (useful for telemetry).
• CancellationToken: The cancellation token linked to the operation.
• Properties: An instance of ResilienceProperties used to attach custom data.
• ContinueOnCapturedContext: Specifies whether the asynchronous execution should continue on the captured context.

Best Practice: Defining Property Keys

To maintain and discover keys easily, define a static class to hold your ResiliencePropertyKey<T> instances. For simple scenarios, you can create them on the fly as they are cheap, struct-based APIs.

// Recommended: Define keys in a static class
public static class MyResilienceKeys
{
    public static readonly ResiliencePropertyKey<string> Key1 = new("my-key-1");
    public static readonly ResiliencePropertyKey<int> Key2 = new("my-key-2");
}

// Usage in a pipeline strategy
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new() 
    {
        OnRetry = static args => 
        {
            if (args.Context.Properties.TryGetValue(MyResilienceKeys.Key1, out var data)) 
            {
                Console.WriteLine($"OnRetry, Custom Data: {data}");
            }
            return default;
        }
    })
    .Build();

The hedging strategy executes multiple actions concurrently. To prevent concurrency issues when these actions access the same ResilienceContext, the strategy provides each hedged action with its own unique context.

There are two types of contexts:

• Primary context: The original resilience context received by the hedging strategy.
• Action context: A deep copy of the primary context containing a distinct CancellationToken specific to a single hedged action.

Lifecycle and Merging:

1. The strategy deep-clones the primary context to create action contexts.
2. Once a hedged action produces an accepted result, its ActionContext is merged back into the PrimaryContext.
3. During merging, new properties created in the action context are added to the primary context, and existing properties are updated or set to null (soft-deleted).
4. All other ongoing hedged actions are cancelled and discarded, awaiting cancellation propagation before the strategy completes.

The Circuit Breaker is a reactive resilience strategy that prevents execution if an underlying resource is detected as unhealthy via sampling.

How it works:

1. Sampling: The strategy monitors the failure-to-success ratio of executions within a SamplingDuration.
2. Breaking: If the failure ratio exceeds a predefined FailureRatio and a MinimumThroughput is met, the circuit "breaks" (opens).
3. Blocking: While the circuit is open, all new executions are immediately shortcut by throwing a BrokenCircuitException.
4. Probing: After a BreakDuration expires, the circuit enters a HalfOpen state to perform a probe. If the probe succeeds, the circuit closes; otherwise, it remains open.

Important Notes:

• Exception Handling: The Circuit Breaker rethrows all exceptions, including those it is configured to handle. It monitors faults but does not manage retries. To handle retries, combine it with a Retry strategy.
• Throughput Requirement: If the MinimumThroughput is not reached within the SamplingDuration, the FailureRatio is ignored, and the circuit will not break even if all executions failed.

// Example of a circuit breaker that breaks if 50% of actions fail
// within a 10-second window, provided at least 8 actions occurred.
var optionsComplex = new CircuitBreakerStrategyOptions
{
    FailureRatio = 0.5,
    SamplingDuration = TimeSpan.FromSeconds(10),
    MinimumThroughput = 8,
    BreakDuration = TimeSpan.FromSeconds(30),
    ShouldHandle = new PredicateBuilder().Handle<SomeExceptionType>()
};

The OnRejected delegate is called just before the strategy throws a RateLimiterRejectedException.

Use OnRejected when you need to perform an action (like logging) immediately when a limit is hit, especially in pipelines with multiple strategies. For example, if a Retry strategy is wrapping a Rate Limiter, the Retry strategy will catch the exception, but the OnRejected delegate provides the immediate notification that the limit was exceeded.

Note: The RetryAfter value is not available inside the OnRejected callback; it is only available on the caught exception.

var withOnRejected = new ResiliencePipelineBuilder()
    .AddRateLimiter(new RateLimiterStrategyOptions
    {
        DefaultRateLimiterOptions = new ConcurrencyLimiterOptions
        {
            PermitLimit = 10
        },
        OnRejected = args =>
        {
            Console.WriteLine("Rate limit has been exceeded");
            return default;
        }
    }).Build();

Polly v8 introduces several fundamental changes to the API and mental model:

• Terminology Change: The term Policy is replaced by Strategy (e.g., resilience strategies).
• Resilience Pipelines: Instead of individual policies, v8 uses ResiliencePipeline and ResiliencePipeline<T> to combine multiple strategies. This replaces the concept of a Policy Wrap.
• Unified Execution: The separate sync and async interfaces (like ISyncPolicy and IAsyncPolicy) are unified into ResiliencePipeline, which supports both Execute and ExecuteAsync flows.
• No Static APIs: v8 moves away from static APIs to improve testability and extensibility.
• Options-based Configuration: Strategies are configured using options objects (e.g., RetryStrategyOptions), providing better flexibility.
• Performance & Telemetry: v8 features built-in telemetry and low-allocation, high-performance APIs.