Polly

https://www.pollydocs.org/
Admin
Polly is a .NET resilience library that helps applications handle transient faults and improve...
Tokens:156,779
Snippets:1,580
Trust Score:7.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Registry in v8

Source: https://www.pollydocs.org/migration-v8.html

Shows how to create a registry, add a pipeline using a builder, try to get a pipeline, and get or add a pipeline using the v8 ResiliencePipelineRegistry API.

```csharp
// Create a registry
var registry = new ResiliencePipelineRegistry<string>();

// Add a pipeline using a builder, when the pipeline is retrieved it will be dynamically built and cached
registry.TryAddBuilder(PipelineKey, (builder, context) => builder.AddTimeout(TimeSpan.FromSeconds(10)));

// Try get a pipeline
registry.TryGetPipeline(PipelineKey, out ResiliencePipeline? pipeline);

// Try get a generic pipeline
registry.TryGetPipeline(PipelineKey, out ResiliencePipeline<string>? genericPipeline);

// Get or add pipeline
registry.GetOrAddPipeline(PipelineKey, builder => builder.AddTimeout(TimeSpan.FromSeconds(10)));
```

--------------------------------

### Example execution with retry and chaos fault strategy

Source: https://www.pollydocs.org/chaos/fault.html

Shows a complete pipeline example that combines a retry strategy with exponential backoff and jitter, followed by a chaos fault strategy. The comment notes that chaos strategies are usually placed as the last ones in the pipeline.

```csharp
var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        ShouldHandle = new PredicateBuilder().Handle<InvalidOperationException>(),
        BackoffType = DelayBackoffType.Exponential,
        UseJitter = true,  // Adds a random factor to the delay
        MaxRetryAttempts = 4,
        Delay = TimeSpan.FromSeconds(3),
    })
    .AddChaosFault(new ChaosFaultStrategyOptions // Chaos strategies are usually placed as the last ones in the pipeline
    {
        FaultGenerator = static args => new ValueTask<Exception?>(new InvalidOperationException("Dummy exception")),
        InjectionRate = 0.1
    })
    .Build();
```

--------------------------------

### Configure and add hedging strategy

Source: https://www.pollydocs.org/strategies/hedging.html

Examples showing how to initialize default hedging options, configure a complex strategy with custom predicates and action generators, subscribe to hedging events, and add the strategy to a pipeline.

```csharp
// Hedging with default options.
// See https://www.pollydocs.org/strategies/hedging#defaults for defaults.
var optionsDefaults = new HedgingStrategyOptions<HttpResponseMessage>();

// A customized hedging strategy that retries up to 3 times if the execution
// takes longer than 1 second or if it fails due to an exception or returns an HTTP 500 Internal Server Error.
var optionsComplex = new HedgingStrategyOptions<HttpResponseMessage>
{
    ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
        .Handle<SomeExceptionType>()
        .HandleResult(response => response.StatusCode == HttpStatusCode.InternalServerError),
    MaxHedgedAttempts = 3,
    Delay = TimeSpan.FromSeconds(1),
    ActionGenerator = static args =>
    {
        Console.WriteLine("Preparing to execute hedged action.");

        // Return a delegate function to invoke the original action with the action context.
        // Optionally, you can also create a completely new action to be executed.
        return () => args.Callback(args.ActionContext);
    }
};

// Subscribe to hedging events.
var optionsOnHedging = new HedgingStrategyOptions<HttpResponseMessage>
{
    OnHedging = static args =>
    {
        Console.WriteLine($"OnHedging: Attempt number {args.AttemptNumber}");
        return default;
    }
};

// Add a hedging strategy with a HedgingStrategyOptions<TResult> instance to the pipeline
new ResiliencePipelineBuilder<HttpResponseMessage>().AddHedging(optionsDefaults);
```

--------------------------------

### Polly Log Examples

Source: https://www.pollydocs.org/advanced/telemetry.html

Examples of log messages recorded under the 'Polly' logger name, including event occurrences, pipeline execution lifecycle, and attempt details.

```text
// This log is recorded whenever a resilience event occurs. EventId = 0
Resilience event occurred. EventName: '{EventName}', Source: '{PipelineName}/{PipelineInstance}/{StrategyName}', Operation Key: '{OperationKey}', Result: '{Result}'

// This log is recorded when a resilience pipeline begins executing. EventId = 1
Resilience pipeline executing. Source: '{PipelineName}/{PipelineInstance}', Operation Key: '{OperationKey}'

// This log is recorded when a resilience pipeline finishes execution. EventId = 2
Resilience pipeline executed. Source: '{PipelineName}/{PipelineInstance}', Operation Key: '{OperationKey}', Result: '{Result}', Execution Health: '{ExecutionHealth}', Execution Time: '{ExecutionTime}ms'

// This log is recorded upon the completion of every execution attempt. EventId = 3
Execution attempt. Source: '{PipelineName}/{PipelineInstance}/{StrategyName}', Operation Key: '{OperationKey}', Result: '{Result}', Handled: '{Handled}', Attempt: '{Attempt}', Execution Time: '{ExecutionTime}ms'
```

--------------------------------

### Configure pipelines at startup using AddResiliencePipeline

Source: https://www.pollydocs.org/pipelines/index.html

Shows how to define multiple pipelines at startup using the AddResiliencePipeline extension on IServiceCollection. Pipelines are resolved by name using ResiliencePipelineProvider<string>.

```csharp
public static void ConfigureMyPipelines(IServiceCollection services)
{
    services.AddResiliencePipeline("pipeline-A", builder => builder.AddConcurrencyLimiter(100));
    services.AddResiliencePipeline("pipeline-B", builder => builder.AddRetry(new()));

    // Later, resolve the pipeline by name using ResiliencePipelineProvider<string> or ResiliencePipelineRegistry<string>
    var pipelineProvider = services.BuildServiceProvider().GetRequiredService<ResiliencePipelineProvider<string>>();
    pipelineProvider.GetPipeline("pipeline-A").Execute(() => { });
}
```

--------------------------------

### Configure ResiliencePipelineRegistryOptions

Source: https://www.pollydocs.org/pipelines/resilience-pipeline-registry.html

Shows how to create a ResiliencePipelineRegistryOptions<string> with custom comparers, builder factory, and name formatters, then instantiate a ResiliencePipelineRegistry<string>. Useful when using complex registry keys.

```csharp
var options = new ResiliencePipelineRegistryOptions<string>
{
    BuilderComparer = StringComparer.OrdinalIgnoreCase,
    PipelineComparer = StringComparer.OrdinalIgnoreCase,
    BuilderFactory = () => new ResiliencePipelineBuilder
    {
        InstanceName = "lets change the default of InstanceName",
        Name = "lets change the default of Name",
    },
    BuilderNameFormatter = key => $"key:{key}",
    InstanceNameFormatter = key => $"instance-key:{key}",
};

var registry = new ResiliencePipelineRegistry<string>();
```

--------------------------------

### GET /408

Source: https://www.pollydocs.org/api/Snippets.Docs.IHttpStatusApi.html

Sends an HTTP GET request to the /408 endpoint. This method is part of the IHttpStatusApi interface and returns a Task<HttpResponseMessage> representing the asynchronous HTTP response.

```APIDOC
## [GET] /408

### Description
Sends an HTTP GET request to the /408 endpoint.

### Method
GET

### Endpoint
/408

### Response
#### Success Response (200)
- **HttpResponseMessage** - The HTTP response message returned by the endpoint.

#### Response Example
```json
{
  "statusCode": 408,
  "reasonPhrase": "Request Timeout"
}
```
```

--------------------------------

### ResilienceStrategyDescriptor.StrategyInstance

Source: https://www.pollydocs.org/api/Polly.Testing.ResilienceStrategyDescriptor.html

Gets the strategy instance.

```APIDOC
## [GET] ResilienceStrategyDescriptor.StrategyInstance

### Description
Gets the strategy instance.

### Property
- **StrategyInstance** (object) - Gets the strategy instance.

### Property Value
- **object** - The strategy instance.
```

--------------------------------

### Rate limit in v8

Source: https://www.pollydocs.org/migration-v8.html

Shows how to create a rate limiter strategy using the AddRateLimiter extension and the SlidingWindowRateLimiter. Requires the Polly.RateLimiting package. The generic pipeline creation is almost identical.

```csharp
// The equivalent to Polly v7's RateLimit is the SlidingWindowRateLimiter.
//
// Polly exposes just a simple wrapper to the APIs exposed by the System.Threading.RateLimiting APIs.
// There is no need to create separate instances for sync and async flows as ResiliencePipeline handles both scenarios.
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRateLimiter(new SlidingWindowRateLimiter(new SlidingWindowRateLimiterOptions
    {
        PermitLimit = 100,
        SegmentsPerWindow = 4,
        Window = TimeSpan.FromMinutes(1),
    }))
    .Build();

// The creation of generic pipeline is almost identical.
//
// Polly exposes the same set of rate-limiter extensions for both ResiliencePipeline<HttpResponseMessage> and ResiliencePipeline.
ResiliencePipeline<HttpResponseMessage> pipelineT = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddRateLimiter(new SlidingWindowRateLimiter(new SlidingWindowRateLimiterOptions
    {
        PermitLimit = 100,
        SegmentsPerWindow = 4,
        Window = TimeSpan.FromMinutes(1),
    }))
    .Build();
```

--------------------------------

### SeverityProviderArguments.Event Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.SeverityProviderArguments.html

Gets the resilience event.

```APIDOC
## Event Property

### Description
Gets the resilience event.

### Property Value
ResilienceEvent

### Signature
public ResilienceEvent Event { get; }

```

--------------------------------

### SeverityProviderArguments.Context Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.SeverityProviderArguments.html

Gets the resilience context.

```APIDOC
## Context Property

### Description
Gets the resilience context.

### Property Value
ResilienceContext

### Signature
public ResilienceContext Context { get; }

```

--------------------------------

### Register and retrieve pipelines with TryAddBuilder

Source: https://www.pollydocs.org/pipelines/resilience-pipeline-registry.html

Shows how to register pipeline builders for both non-generic and generic pipelines using TryAddBuilder, then retrieve them with GetPipeline and TryGetPipeline. Note that calling Build is not required after configuring the builder. The example also demonstrates handling KeyNotFoundException when retrieving an unregistered pipeline.

```csharp
var registry = new ResiliencePipelineRegistry<string>();

// Register builder for pipeline "A"
registry.TryAddBuilder("A", (builder, context) =>
{
    // Define your pipeline
    builder.AddRetry(new RetryStrategyOptions());
});

// Register generic builder for pipeline "A"; you can use the same key
// because generic and non-generic pipelines are stored separately
registry.TryAddBuilder<HttpResponseMessage>("A", (builder, context) =>
{
    // Define your pipeline
    builder.AddRetry(new RetryStrategyOptions<HttpResponseMessage>());
});

// Fetch pipeline "A"
ResiliencePipeline pipelineA = registry.GetPipeline("A");

// Fetch generic pipeline "A"
ResiliencePipeline<HttpResponseMessage> genericPipelineA = registry.GetPipeline<HttpResponseMessage>("A");

// Returns false since pipeline "unknown" isn't registered
var doesPipelineExist = registry.TryGetPipeline("unknown", out var pipeline);

// Throws KeyNotFoundException because pipeline "unknown" isn't registered
try
{
    registry.GetPipeline("unknown");
}
catch (KeyNotFoundException)
{
    // Handle the exception
}
```

--------------------------------

### Duration

Source: https://www.pollydocs.org/api/Polly.Telemetry.PipelineExecutedArguments.html

Gets the pipeline execution duration.

```APIDOC
## Duration

### Description
Gets the pipeline execution duration.

### Property
`public TimeSpan Duration { get; }`

### Property Value
TimeSpan

```

--------------------------------

### Rate limit in v7

Source: https://www.pollydocs.org/migration-v8.html

Shows how to create sync, async, generic sync, and generic async rate limiters using the v7 RateLimit and RateLimitAsync methods.

```csharp
// Create sync rate limiter
ISyncPolicy syncPolicy = Policy.RateLimit(
    numberOfExecutions: 100,
    perTimeSpan: TimeSpan.FromMinutes(1));

// Create async rate limiter
IAsyncPolicy asyncPolicy = Policy.RateLimitAsync(
    numberOfExecutions: 100,
    perTimeSpan: TimeSpan.FromMinutes(1));

// Create generic sync rate limiter
ISyncPolicy<HttpResponseMessage> syncPolicyT = Policy.RateLimit<HttpResponseMessage>(
    numberOfExecutions: 100,
    perTimeSpan: TimeSpan.FromMinutes(1));

// Create generic async rate limiter
IAsyncPolicy<HttpResponseMessage> asyncPolicyT = Policy.RateLimitAsync<HttpResponseMessage>(
    numberOfExecutions: 100,
    perTimeSpan: TimeSpan.FromMinutes(1));
```

--------------------------------

### Add Polly.Core package

Source: https://www.pollydocs.org/getting-started.html

Install the Polly.Core package to use the core resilience pipeline APIs.

```bash
dotnet add package Polly.Core
```

--------------------------------

### ExecutionAttemptArguments.AttemptNumber Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.ExecutionAttemptArguments.html

Gets the attempt number.

```APIDOC
## AttemptNumber Property

### Description
Gets the attempt number.

### Property Value
int
```

--------------------------------

### StrategyBuilderContext.TimeProvider

Source: https://www.pollydocs.org/api/Polly.StrategyBuilderContext.html

Gets the TimeProvider used by this strategy.

```APIDOC
## Property: TimeProvider

### Description
Gets the TimeProvider used by this strategy.

### Property Signature
public TimeProvider TimeProvider { get; }

### Property Value
- **Type**: TimeProvider
- **Description**: The time provider instance.

```

--------------------------------

### Output of failure handling example

Source: https://www.pollydocs.org/strategies/circuit-breaker.html

Shows the console output from the failure handling example: three 'Operation failed please try again.' messages followed by seven 'Operation failed too many times please try again later.' messages, demonstrating the circuit opening after the minimum throughput is reached.

```text
Operation failed please try again.
Operation failed please try again.
Operation failed please try again.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
Operation failed too many times please try again later.
```

--------------------------------

### Registry in v7

Source: https://www.pollydocs.org/migration-v8.html

Shows how to create a registry, add a policy, try to get a policy, and update a policy using the v7 PolicyRegistry API.

```csharp
// Create a registry
var registry = new PolicyRegistry();

// Add a policy
registry.Add(PolicyKey, Policy.Timeout(TimeSpan.FromSeconds(10)));

// Try get a policy
registry.TryGet<IAsyncPolicy>(PolicyKey, out IAsyncPolicy? policy);

// Try get a generic policy
registry.TryGet<IAsyncPolicy<string>>(PolicyKey, out IAsyncPolicy<string>? genericPolicy);

// Update a policy
registry.AddOrUpdate(
    PolicyKey,
    Policy.Timeout(TimeSpan.FromSeconds(10)),
    (key, previous) => Policy.Timeout(TimeSpan.FromSeconds(10)));
```

--------------------------------

### Latency Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Latency.OnLatencyInjectedArguments.html

Gets the latency that was injected.

```APIDOC
## Latency Property

### Description
Gets the latency that was injected.

### Property Signature
```csharp
public TimeSpan Latency { get; }
```

### Property Value
- **TimeSpan** - The latency that was injected.

```

--------------------------------

### OnFaultInjectedArguments.Fault Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Fault.OnFaultInjectedArguments.html

Gets the fault that was injected.

```APIDOC
## Fault Property

### Description
Gets the fault that was injected.

### Property Signature
`public Exception Fault { get; }`

### Property Value
- **Type**: Exception

```

--------------------------------

### Dispose rate limiters with OnPipelineDisposed callback

Source: https://www.pollydocs.org/pipelines/resilience-pipeline-registry.html

This example creates a registry with a concurrency strategy and a chained rate limiter strategy, and manually disposes the rate limiters in the OnPipelineDisposed callback. It uses a PipelineRegistryAdapter that wraps a ResiliencePipelineRegistry<string> and creates pipelines with partitioned rate limiters. The rate limiters are disposed manually because they are not automatically disposed by the pipeline.

```csharp
public static class Program
{
    public static void Main()
    {
        using var registryAdapter = new PipelineRegistryAdapter();
        registryAdapter.GetOrCreateResiliencePipeline("Pipeline foo", 1, 10, 100, 1000);
        registryAdapter.GetOrCreateResiliencePipeline("Pipeline bar", 2, 20, 200, 2000);
    }
}

public sealed class PipelineRegistryAdapter : IDisposable
{
    private readonly ResiliencePipelineRegistry<string> _resiliencePipelineRegistry = new();
    private bool _disposed;

    public void Dispose()
    {
        if (!_disposed)
        {
            _resiliencePipelineRegistry.Dispose();
            _disposed = true;
        }
    }

    private static PartitionedRateLimiter<ResilienceContext> CreateConcurrencyLimiter(string partitionKey, int permitLimit) =>
        PartitionedRateLimiter.Create<ResilienceContext, string>(context =>
            RateLimitPartition.GetConcurrencyLimiter(
                partitionKey: partitionKey,
                factory: partitionKey => new ConcurrencyLimiterOptions { PermitLimit = permitLimit, QueueLimit = 0 }));

    private static PartitionedRateLimiter<ResilienceContext> CreateFixedWindowLimiter(string partitionKey, int permitLimit, TimeSpan window) =>
        PartitionedRateLimiter.Create<ResilienceContext, string>(context =>
            RateLimitPartition.GetFixedWindowLimiter(
                partitionKey: partitionKey,
                factory: partitionKey => new FixedWindowRateLimiterOptions { PermitLimit = permitLimit, QueueLimit = 0, Window = window }));

    public ResiliencePipeline GetOrCreateResiliencePipeline(string partitionKey, int maximumConcurrentThreads, int sendLimitPerSecond, int sendLimitPerHour, int sendLimitPerDay)
    {
        return _resiliencePipelineRegistry.GetOrAddPipeline(partitionKey, (builder, context) =>
        {
            PartitionedRateLimiter<ResilienceContext>? threadLimiter = null;
            PartitionedRateLimiter<ResilienceContext>? requestLimiter = null;

            // outer strategy: limit threads
            builder.AddRateLimiter(new RateLimiterStrategyOptions
            {
                RateLimiter = args =>
                {
                    threadLimiter = CreateConcurrencyLimiter(partitionKey, maximumConcurrentThreads);
                    return threadLimiter.AcquireAsync(args.Context, permitCount: 1, args.Context.CancellationToken);
                }
            });

            // inner strategy: limit requests (by second, hour, day)
            builder.AddRateLimiter(new RateLimiterStrategyOptions
            {
                RateLimiter = args =>
                {
                    PartitionedRateLimiter<ResilienceContext>[] limiters = [
                        CreateFixedWindowLimiter(partitionKey, sendLimitPerSecond, TimeSpan.FromSeconds(1)),
                        CreateFixedWindowLimiter(partitionKey, sendLimitPerHour,   TimeSpan.FromHours(1)),
                        CreateFixedWindowLimiter(partitionKey, sendLimitPerDay,    TimeSpan.FromDays(1)),
                    ];
                    requestLimiter = PartitionedRateLimiter.CreateChained(limiters);
                    return requestLimiter.AcquireAsync(args.Context, permitCount: 1, args.Context.CancellationToken);
                }
            });

            // unlike other strategies, rate limiters disposed manually
            context.OnPipelineDisposed(() =>
            {
                threadLimiter?.Dispose();
                requestLimiter?.Dispose();
            });
        });
    }
}
```

--------------------------------

### ResilienceContextPool.Shared

Source: https://www.pollydocs.org/api/Polly.ResilienceContextPool.html

Gets the shared pool instance.

```APIDOC
## Property: Shared

### Description
Gets the shared pool instance.

### Signature
public static ResilienceContextPool Shared { get; }

### Property Value
ResilienceContextPool
```

--------------------------------

### TryAddBuilder<TResult>(TKey, Action<ResiliencePipelineBuilder<TResult>, ConfigureBuilderContext<TKey>>)

Source: https://www.pollydocs.org/api/Polly.Registry.ResiliencePipelineRegistry-1.html

Tries to add a generic resilience pipeline builder to the registry. Use this method when you want to create the pipeline on-demand when it's first accessed.

```APIDOC
## TryAddBuilder<TResult>(TKey, Action<ResiliencePipelineBuilder<TResult>, ConfigureBuilderContext<TKey>>)

### Description
Tries to add a generic resilience pipeline builder to the registry. Use this method when you want to create the pipeline on-demand when it's first accessed.

### Method
TryAddBuilder<TResult>

### Signature
public bool TryAddBuilder<TResult>(TKey key, Action<ResiliencePipelineBuilder<TResult>, ConfigureBuilderContext<TKey>> configure)

### Parameters
- **key** (TKey) - The key used to identify the pipeline builder.
- **configure** (Action<ResiliencePipelineBuilder<TResult>, ConfigureBuilderContext<TKey>>) - The action that configures the resilience pipeline builder.

### Type Parameters
- **TResult** - The type of result that the resilience pipeline handles.

### Returns
- **bool** - true if the builder was added successfully, false otherwise.

### Exceptions
- **ArgumentNullException** - Thrown when `configure` is null.
- **ObjectDisposedException** - Thrown when the registry is already disposed.

```

--------------------------------

### ResilienceContextCreationArguments.OperationKey Property

Source: https://www.pollydocs.org/api/Polly.ResilienceContextCreationArguments.html

Gets the operation key, if any.

```APIDOC
## OperationKey Property

### Description
Gets the operation key, if any.

### Property Signature
public string? OperationKey { get; }

### Property Value
string

```

--------------------------------

### Partitioned rate limiter with custom partition key

Source: https://www.pollydocs.org/strategies/rate-limiter.html

Illustrates creating a partitioned rate limiter that extracts a partition key from ResilienceContext using GetPartitionKey, and using it in a resilience pipeline with a custom RateLimiter delegate.

```csharp
var partitionedLimiter = PartitionedRateLimiter.Create<ResilienceContext, string>(context =>
{
    // Extract the partition key.
    string partitionKey = GetPartitionKey(context);

    return RateLimitPartition.GetConcurrencyLimiter(
        partitionKey,
        key => new ConcurrencyLimiterOptions
        {
            PermitLimit = 100
        });
});

new ResiliencePipelineBuilder()
    .AddRateLimiter(new RateLimiterStrategyOptions
    {
        // Provide a custom rate limiter delegate.
        RateLimiter = args =>
        {
            return partitionedLimiter.AcquireAsync(args.Context, 1, args.Context.CancellationToken);
        }
    });
```

--------------------------------

### TelemetryListeners Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.TelemetryOptions.html

Gets the collection of telemetry listeners.

```APIDOC
## TelemetryListeners Property

### Description
Gets the collection of telemetry listeners.

### Property Signature
```csharp
public ICollection<TelemetryListener> TelemetryListeners { get; }
```

### Property Value
- **ICollection<TelemetryListener>** - The default value is an empty collection.

```

--------------------------------

### Create and execute a ResiliencePipeline with various callback overloads

Source: https://www.pollydocs.org/pipelines/index.html

Shows how to build a ResiliencePipeline with a concurrency limiter and execute different callback types: async void, sync void, async returning a value, async with state, and async with custom data via ResilienceContext. Includes retrieving and returning a context from the shared pool.

```csharp
// Creating a new resilience pipeline
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddConcurrencyLimiter(100)
    .Build();

// Executing an asynchronous void callback
await pipeline.ExecuteAsync(
    async token => await MyMethodAsync(token),
    cancellationToken);

// Executing a synchronous void callback
pipeline.Execute(() => MyMethod());

// Executing an asynchronous callback that returns a value
await pipeline.ExecuteAsync(
    async token => await httpClient.GetAsync(endpoint, token),
    cancellationToken);

// Executing an asynchronous callback without allocating a lambda
await pipeline.ExecuteAsync(
    static async (state, token) => await state.httpClient.GetAsync(state.endpoint, token),
    (httpClient, endpoint),  // State provided here
    cancellationToken);

// Executing an asynchronous callback and passing custom data

// 1. Retrieve a context from the shared pool
ResilienceContext context = ResilienceContextPool.Shared.Get(cancellationToken);

// 2. Add custom data to the context
context.Properties.Set(new ResiliencePropertyKey<string>("my-custom-data"), "my-custom-data");

// 3. Execute the callback
await pipeline.ExecuteAsync(static async context =>
{
    // Retrieve custom data from the context
    var customData = context.Properties.GetValue(
        new ResiliencePropertyKey<string>("my-custom-data"),
        "default-value");

    Console.WriteLine("Custom Data: {0}", customData);

    await MyMethodAsync(context.CancellationToken);
},
context);

// 4. Optionally, return the context to the shared pool
ResilienceContextPool.Shared.Return(context);
```

--------------------------------

### Timeout Property

Source: https://www.pollydocs.org/api/Polly.Timeout.TimeoutStrategyOptions.html

Gets or sets the default timeout.

```APIDOC
## Property

### Timeout

Gets or sets the default timeout.

```csharp
[Range(typeof(TimeSpan), "00:00:00.010", "1.00:00:00")]
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Addressed with DynamicDependency on ValidationHelper.Validate method")]
public TimeSpan Timeout { get; set; }
```

#### Property Value

- Type: `TimeSpan`
- Default: 30 seconds
- Constraints: Must be greater than 10 milliseconds and less than 24 hours.
```

--------------------------------

### Example execution with RateLimiterRejectedException handling

Source: https://www.pollydocs.org/strategies/rate-limiter.html

Builds a pipeline with a concurrency limiter and executes an asynchronous text search operation. Catches RateLimiterRejectedException and optionally prints the RetryAfter value.

```csharp
var pipeline = new ResiliencePipelineBuilder().AddConcurrencyLimiter(100, 50).Build();

try
{
    // Execute an asynchronous text search operation.
    var result = await pipeline.ExecuteAsync(
        token => TextSearchAsync(query, token),
        cancellationToken);
}
catch (RateLimiterRejectedException ex)
{
    // Handle RateLimiterRejectedException,
    // that can optionally contain information about when to retry.
    if (ex.RetryAfter is TimeSpan retryAfter)
    {
        Console.WriteLine($"Retry After: {retryAfter}");
    }
}
```

--------------------------------

### ResilienceStrategyDescriptor.Options

Source: https://www.pollydocs.org/api/Polly.Testing.ResilienceStrategyDescriptor.html

Gets the options used by the resilience strategy, if any.

```APIDOC
## [GET] ResilienceStrategyDescriptor.Options

### Description
Gets the options used by the resilience strategy, if any.

### Property
- **Options** (ResilienceStrategyOptions?) - Gets the options used by the resilience strategy, if any.

### Property Value
- **ResilienceStrategyOptions** - The options used by the resilience strategy, or null if none.
```

--------------------------------

### ResilienceEvent.Severity Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.ResilienceEvent.html

Gets the severity of the resilience event.

```APIDOC
## Severity Property

### Description
Gets the severity of the event.

### Property Signature
`public ResilienceEventSeverity Severity { get; }`

### Property Value
- **ResilienceEventSeverity** - The severity of the event.
```

--------------------------------

### Recommended: Use ResiliencePipelineBuilder to chain strategies

Source: https://www.pollydocs.org/strategies/fallback.html

Shows the recommended approach using ResiliencePipelineBuilder to chain timeout and fallback strategies. This leverages Polly's escalation mechanism and automatically propagates CancellationToken values between strategies.

```csharp
var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddPipeline(timeout)
    .AddPipeline(fallback)
    .Build();

return await pipeline.ExecuteAsync(CallExternalSystem, CancellationToken.None);
```

--------------------------------

### Visual Basic example using ResiliencePipelineBuilder with timeout

Source: https://www.pollydocs.org/advanced/use-with-fsharp-and-visual-basic.html

Complete Visual Basic module showing how to build a ResiliencePipeline with a 5-second timeout and execute it synchronously and asynchronously, with and without results. Note that asynchronous callbacks must be wrapped in ValueTask and AsTask() is used to convert the returned ValueTask to a Task because VB.NET cannot await ValueTask directly.

```vb
Imports System.Threading
Imports Polly

Module Program
    Sub Main()
        Demo().Wait()
    End Sub

    Async Function Demo() As Task
        ' The ResiliencePipelineBuilder creates a ResiliencePipeline
        ' that can be executed synchronously or asynchronously
        ' and for both void and result-returning user-callbacks.
        Dim pipeline = New ResiliencePipelineBuilder().AddTimeout(TimeSpan.FromSeconds(5)).Build()

        ' Synchronously
        pipeline.Execute(Sub()
                             Console.WriteLine("Hello, world!")
                         End Sub)

        ' Asynchronously
        ' Note that the function is wrapped in a ValueTask for Polly to use as VB.NET cannot
        ' await ValueTask directly, and AsTask() is used to convert the ValueTask returned by
        ' ExecuteAsync() to a Task so it can be awaited.
        Await pipeline.ExecuteAsync(Function(token)
                                        Return New ValueTask(GreetAndWaitAsync(token))
                                    End Function,
                                    CancellationToken.None).AsTask()

        ' Synchronously with result
        Dim someResult = pipeline.Execute(Function(token)
                                              Return "some-result"
                                          End Function)

        ' Asynchronously with result
        ' Note that the function is wrapped in a ValueTask(Of String) for Polly to use as VB.NET cannot
        ' await ValueTask directly, and AsTask() is used to convert the ValueTask(Of String) returned by
        ' ExecuteAsync() to a Task(Of String) so it can be awaited.
        Dim bestFilm = Await pipeline.ExecuteAsync(Function(token)
                                                       Return New ValueTask(Of String)(GetBestFilmAsync(token))
                                                   End Function,
                                    CancellationToken.None).AsTask()

        Console.WriteLine("Link to the best film: {0}", bestFilm)

    End Function

    Async Function GreetAndWaitAsync(token As CancellationToken) As Task
        Console.WriteLine("Hello, world! Waiting for 1 second...")
        Await Task.Delay(1000, token)
    End Function

    Async Function GetBestFilmAsync(token As CancellationToken) As Task(Of String)
        Await Task.Delay(1000, token)
        Return "https://www.imdb.com/title/tt0080684/"
    End Function
End Module
```

--------------------------------

### LatencyGeneratorArguments.Context Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Latency.LatencyGeneratorArguments.html

Gets the resilience context instance.

```APIDOC
## Context Property

### Description
Gets the resilience context instance.

### Property
`public ResilienceContext Context { get; }`

### Property Value
- **ResilienceContext** - The resilience context instance.

```

--------------------------------

### F# example: Using Polly ResiliencePipeline with ValueTask conversion

Source: https://www.pollydocs.org/advanced/use-with-fsharp-and-visual-basic.html

Shows how to use Polly v8 in F# with the IcedTasks library to handle ValueTask. The example creates a ResiliencePipeline with a timeout, executes it synchronously and asynchronously, and demonstrates both void and result-returning callbacks. Note that Polly expects ValueTask, so the valueTask builder from IcedTasks is used.

```F#
open FSharp.Control
open System
open System.Threading
open System.Threading.Tasks
open IcedTasks
open Polly

let getBestFilmAsync token =
    task {
        do! Task.Delay(1000, token)
        return "https://www.imdb.com/title/tt0080684/"
    }

let demo () =
    task {
        // The ResiliencePipelineBuilder creates a ResiliencePipeline
        // that can be executed synchronously or asynchronously
        // and for both void and result-returning user-callbacks.
        let pipeline =
            ResiliencePipelineBuilder()
                .AddTimeout(TimeSpan.FromSeconds(5))
                .Build()

        let token = CancellationToken.None

        // Synchronously
        pipeline.Execute(fun () -> printfn "Hello, world!")

        // Asynchronously
        // Note that Polly expects a ValueTask to be returned, so the function uses the valueTask builder
        // from IcedTasks to make it easier to use ValueTask. See https://github.com/TheAngryByrd/IcedTasks.
        do! pipeline.ExecuteAsync(
            fun token ->
                valueTask {
                    printfn "Hello, world! Waiting for 2 seconds..."
                    do! Task.Delay(1000, token)
                    printfn "Wait complete."
                }
            , token
        )

        // Synchronously with result
        let someResult = pipeline.Execute(fun token -> "some-result")

        // Asynchronously with result
        // Note that Polly expects a ValueTask<T> to be returned, so the function uses the valueTask builder
        // from IcedTasks to make it easier to use ValueTask<T>. See https://github.com/TheAngryByrd/IcedTasks.
        let! bestFilm = pipeline.ExecuteAsync(
            fun token ->
                valueTask {
                    let! url = getBestFilmAsync(token)
                    return url
                }
            , token
        )

        printfn $"Link to the best film: {bestFilm}"
    }
```

--------------------------------

### ExecutionAttemptArguments.Duration Property

Source: https://www.pollydocs.org/api/Polly.Telemetry.ExecutionAttemptArguments.html

Gets the execution duration of the attempt.

```APIDOC
## Duration Property

### Description
Gets the execution duration of the attempt.

### Property Value
TimeSpan
```

--------------------------------

### ChaosStrategy(ChaosStrategyOptions)

Source: https://www.pollydocs.org/api/Polly.Simmy.ChaosStrategy.html

Initializes a new instance of the ChaosStrategy class with the specified options.

```APIDOC
## Constructor: ChaosStrategy(ChaosStrategyOptions)

### Description
Initializes a new instance of the ChaosStrategy class.

### Signature
protected ChaosStrategy(ChaosStrategyOptions options)

### Parameters
- **options** (ChaosStrategyOptions) - Required - The chaos strategy options.

```

--------------------------------

### OnFaultInjectedArguments.Context Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Fault.OnFaultInjectedArguments.html

Gets the resilience context instance.

```APIDOC
## Context Property

### Description
Gets the resilience context instance.

### Property Signature
`public ResilienceContext Context { get; }`

### Property Value
- **Type**: ResilienceContext

```

--------------------------------

### Convert v8 ResiliencePipeline to v7 policies with AsSyncPolicy and AsAsyncPolicy

Source: https://www.pollydocs.org/migration-v8.html

Create a ResiliencePipeline with AddRateLimiter, then convert it to v7 sync and async policies using AsSyncPolicy and AsAsyncPolicy. Requires the Polly.RateLimiting package in v8. The resulting policies can be used in a Policy.Wrap.

```csharp
// First, create a resilience pipeline.
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRateLimiter(new FixedWindowRateLimiter(new FixedWindowRateLimiterOptions
    {
        Window = TimeSpan.FromSeconds(10),
        PermitLimit = 100
    }))
    .Build();

// Now, convert it to a v7 policy. Note that it can be converted to both sync and async policies.
ISyncPolicy syncPolicy = pipeline.AsSyncPolicy();
IAsyncPolicy asyncPolicy = pipeline.AsAsyncPolicy();

// Finally, use it in a policy wrap.
ISyncPolicy wrappedPolicy = Policy.Wrap(
    syncPolicy,
    Policy.Handle<SomeExceptionType>().Retry(3));
```

--------------------------------

### OnBehaviorInjectedArguments.Context Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Behavior.OnBehaviorInjectedArguments.html

Gets the resilience context instance.

```APIDOC
## Context Property

### Description
Gets the resilience context instance.

### Property Signature
`public ResilienceContext Context { get; }`

### Property Value
- **ResilienceContext** - The resilience context instance.

```

--------------------------------

### Context Property

Source: https://www.pollydocs.org/api/Polly.Simmy.Behavior.BehaviorGeneratorArguments.html

Gets the resilience context instance.

```APIDOC
## Property: Context

### Description
Gets the resilience context instance.

### Signature
public ResilienceContext Context { get; }

### Property Value
- **ResilienceContext** - The resilience context instance.

```

--------------------------------

### TryAddBuilder(TKey, Action<ResiliencePipelineBuilder, ConfigureBuilderContext<TKey>>)

Source: https://www.pollydocs.org/api/Polly.Registry.ResiliencePipelineRegistry-1.html

Tries to add a resilience pipeline builder to the registry. Returns true if the builder was added successfully, false otherwise.

```APIDOC
## TryAddBuilder(TKey, Action<ResiliencePipelineBuilder, ConfigureBuilderContext<TKey>>)

### Description
Tries to add a resilience pipeline builder to the registry.

### Method
TryAddBuilder

### Signature
public bool TryAddBuilder(TKey key, Action<ResiliencePipelineBuilder, ConfigureBuilderContext<TKey>> configure)

### Parameters
- **key** (TKey) - The key used to identify the pipeline builder.
- **configure** (Action<ResiliencePipelineBuilder, ConfigureBuilderContext<TKey>>) - The action that configures the resilience pipeline builder.

### Returns
- **bool** - true if the builder was added successfully, false otherwise.

### Remarks
Use this method when you want to create the pipeline on-demand when it's first accessed.

### Exceptions
- **ArgumentNullException** - Thrown when `configure` is null.
- **ObjectDisposedException** - Thrown when the registry is already disposed.
```

--------------------------------

### ResiliencePipelineRegistry<TKey> Constructors

Source: https://www.pollydocs.org/api/Polly.Registry.ResiliencePipelineRegistry-1.html

Initializes a new instance of the ResiliencePipelineRegistry<TKey> class, either with default settings or with custom options.

```APIDOC
## ResiliencePipelineRegistry<TKey> Constructors

### Description
Initializes a new instance of the ResiliencePipelineRegistry<TKey> class.

### Constructors

#### ResiliencePipelineRegistry()
Initializes a new instance of the ResiliencePipelineRegistry<TKey> class with the default comparer.

```csharp
public ResiliencePipelineRegistry()
```

#### ResiliencePipelineRegistry(ResiliencePipelineRegistryOptions<TKey> options)
Initializes a new instance of the ResiliencePipelineRegistry<TKey> class with a custom builder factory and comparer.

```csharp
public ResiliencePipelineRegistry(ResiliencePipelineRegistryOptions<TKey> options)
```

##### Parameters
- **options** (ResiliencePipelineRegistryOptions<TKey>) - The registry options.

##### Exceptions
- **ValidationException** - Thrown when `options` are invalid.
- **ArgumentNullException** - Thrown when `options` are null.
```

--------------------------------

### Configure resilience pipeline with AddResiliencePipeline

Source: https://www.pollydocs.org/advanced/dependency-injection.html

Sets up a resilience pipeline named "my-key" using the AddResiliencePipeline extension method. The first overload adds a timeout strategy; the second overload provides access to IServiceProvider via the builder context to resolve services from DI. Both pipelines are resolved through ResiliencePipelineProvider<string> and executed with ExecuteAsync.

```csharp
var services = new ServiceCollection();

// Define a resilience pipeline
services.AddResiliencePipeline("my-key", builder =>
{
    // Add strategies to your pipeline here, timeout for example
    builder.AddTimeout(TimeSpan.FromSeconds(10));
});

// You can also access IServiceProvider by using the alternate overload
services.AddResiliencePipeline("my-key", (builder, context) =>
{
    // Resolve any service from DI
    var loggerFactory = context.ServiceProvider.GetRequiredService<ILoggerFactory>();

    // Add strategies to your pipeline here
    builder.AddTimeout(TimeSpan.FromSeconds(10));
});

// Resolve the resilience pipeline
ServiceProvider serviceProvider = services.BuildServiceProvider();
ResiliencePipelineProvider<string> pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<string>>();
ResiliencePipeline pipeline = pipelineProvider.GetPipeline(
```

--------------------------------

### TimeoutRejectedException.Timeout Property

Source: https://www.pollydocs.org/api/Polly.Timeout.TimeoutRejectedException.html

Gets the timeout value that caused this exception.

```APIDOC
## Timeout Property

### Description
Gets the timeout value that caused this exception.

### Property Signature
public TimeSpan Timeout { get; }

### Property Value
- **Timeout** (TimeSpan) - The timeout value that caused this exception.
```
Tokens:
Raw