ResiliencePipeline

Execute user-provided callbacks with resilience strategies

Overview

The ResiliencePipeline class is used to execute user-provided callbacks with configured resilience strategies. It provides a unified API for synchronous and asynchronous callbacks, with and without return values.

Static Properties

Empty · ResiliencePipeline

A resilience pipeline that executes the user-provided callback without any additional logic.

Synchronous Execute Methods

Execute (Action)

public void Execute(Action callback)

Executes the specified callback.

callback · Action · required

The user-provided callback.

Throws · ArgumentNullException

Thrown when callback is null.

Execute (Action<CancellationToken>)

public void Execute(
    Action<CancellationToken> callback,
    CancellationToken cancellationToken = default)

Executes the specified callback with a cancellation token.

callback · Action<CancellationToken> · required

The user-provided callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Execute (Action<TState>)

public void Execute<TState>(
    Action<TState> callback,
    TState state)

Executes the specified callback with state.

callback · Action<TState> · required

The user-provided callback.

state · TState

The state associated with the callback.

Execute (Action<TState, CancellationToken>)

public void Execute<TState>(
    Action<TState, CancellationToken> callback,
    TState state,
    CancellationToken cancellationToken = default)

Executes the specified callback with state and cancellation token.

callback · Action<TState, CancellationToken> · required

The user-provided callback.

state · TState

The state associated with the callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Execute (Action<ResilienceContext>)

public void Execute(
    Action<ResilienceContext> callback,
    ResilienceContext context)

Executes the specified callback with a resilience context.

callback · Action<ResilienceContext> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

Execute (Action<ResilienceContext, TState>)

public void Execute<TState>(
    Action<ResilienceContext, TState> callback,
    ResilienceContext context,
    TState state)

Executes the specified callback with a resilience context and state.

callback · Action<ResilienceContext, TState> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

state · TState

The state associated with the callback.

Synchronous Execute Methods with Result

Execute (Func<TResult>)

public TResult Execute<TResult>(Func<TResult> callback)

Executes the specified callback and returns a result.

callback · Func<TResult> · required

The user-provided callback.

Returns · TResult

The result of the callback execution.

Execute (Func<CancellationToken, TResult>)

public TResult Execute<TResult>(
    Func<CancellationToken, TResult> callback,
    CancellationToken cancellationToken = default)

Executes the specified callback with a cancellation token and returns a result.

callback · Func<CancellationToken, TResult> · required

The user-provided callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · TResult

The result of the callback execution.

Execute (Func<TState, TResult>)

public TResult Execute<TResult, TState>(
    Func<TState, TResult> callback,
    TState state)

Executes the specified callback with state and returns a result.

callback · Func<TState, TResult> · required

The user-provided callback.

state · TState

The state associated with the callback.

Returns · TResult

The result of the callback execution.

Execute (Func<TState, CancellationToken, TResult>)

public TResult Execute<TResult, TState>(
    Func<TState, CancellationToken, TResult> callback,
    TState state,
    CancellationToken cancellationToken = default)

Executes the specified callback with state and cancellation token and returns a result.

callback · Func<TState, CancellationToken, TResult> · required

The user-provided callback.

state · TState

The state associated with the callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · TResult

The result of the callback execution.

Execute (Func<ResilienceContext, TResult>)

public TResult Execute<TResult>(
    Func<ResilienceContext, TResult> callback,
    ResilienceContext context)

Executes the specified callback with a resilience context and returns a result.

callback · Func<ResilienceContext, TResult> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

Returns · TResult

The result of the callback execution.

Execute (Func<ResilienceContext, TState, TResult>)

public TResult Execute<TResult, TState>(
    Func<ResilienceContext, TState, TResult> callback,
    ResilienceContext context,
    TState state)

Executes the specified callback with a resilience context and state and returns a result.

callback · Func<ResilienceContext, TState, TResult> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

state · TState

The state associated with the callback.

Returns · TResult

The result of the callback execution.

Asynchronous Execute Methods

ExecuteAsync (Func<CancellationToken, ValueTask>)

public ValueTask ExecuteAsync(
    Func<CancellationToken, ValueTask> callback,
    CancellationToken cancellationToken = default)

Executes the specified asynchronous callback.

callback · Func<CancellationToken, ValueTask> · required

The user-provided callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · ValueTask

A task that represents the asynchronous execution.

ExecuteAsync (Func<TState, CancellationToken, ValueTask>)

public ValueTask ExecuteAsync<TState>(
    Func<TState, CancellationToken, ValueTask> callback,
    TState state,
    CancellationToken cancellationToken = default)

Executes the specified asynchronous callback with state.

callback · Func<TState, CancellationToken, ValueTask> · required

The user-provided callback.

state · TState

The state associated with the callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · ValueTask

A task that represents the asynchronous execution.

ExecuteAsync (Func<ResilienceContext, ValueTask>)

public ValueTask ExecuteAsync(
    Func<ResilienceContext, ValueTask> callback,
    ResilienceContext context)

Executes the specified asynchronous callback with a resilience context.

callback · Func<ResilienceContext, ValueTask> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

Returns · ValueTask

A task that represents the asynchronous execution.

ExecuteAsync (Func<ResilienceContext, TState, ValueTask>)

public ValueTask ExecuteAsync<TState>(
    Func<ResilienceContext, TState, ValueTask> callback,
    ResilienceContext context,
    TState state)

Executes the specified asynchronous callback with a resilience context and state.

callback · Func<ResilienceContext, TState, ValueTask> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

state · TState

The state associated with the callback.

Returns · ValueTask

A task that represents the asynchronous execution.

Asynchronous Execute Methods with Result

ExecuteAsync (Func<CancellationToken, ValueTask<TResult>>)

public ValueTask<TResult> ExecuteAsync<TResult>(
    Func<CancellationToken, ValueTask<TResult>> callback,
    CancellationToken cancellationToken = default)

Executes the specified asynchronous callback and returns a result.

callback · Func<CancellationToken, ValueTask<TResult>> · required

The user-provided callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · ValueTask<TResult>

A task that represents the asynchronous execution and returns the result.

ExecuteAsync (Func<TState, CancellationToken, ValueTask<TResult>>)

public ValueTask<TResult> ExecuteAsync<TResult, TState>(
    Func<TState, CancellationToken, ValueTask<TResult>> callback,
    TState state,
    CancellationToken cancellationToken = default)

Executes the specified asynchronous callback with state and returns a result.

callback · Func<TState, CancellationToken, ValueTask<TResult>> · required

The user-provided callback.

state · TState

The state associated with the callback.

cancellationToken · CancellationToken

The cancellation token associated with the callback.

Returns · ValueTask<TResult>

A task that represents the asynchronous execution and returns the result.

ExecuteAsync (Func<ResilienceContext, ValueTask<TResult>>)

public ValueTask<TResult> ExecuteAsync<TResult>(
    Func<ResilienceContext, ValueTask<TResult>> callback,
    ResilienceContext context)

Executes the specified asynchronous callback with a resilience context and returns a result.

callback · Func<ResilienceContext, ValueTask<TResult>> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

Returns · ValueTask<TResult>

A task that represents the asynchronous execution and returns the result.

ExecuteAsync (Func<ResilienceContext, TState, ValueTask<TResult>>)

public ValueTask<TResult> ExecuteAsync<TResult, TState>(
    Func<ResilienceContext, TState, ValueTask<TResult>> callback,
    ResilienceContext context,
    TState state)

Executes the specified asynchronous callback with a resilience context and state and returns a result.

callback · Func<ResilienceContext, TState, ValueTask<TResult>> · required

The user-provided callback.

context · ResilienceContext · required

The context associated with the callback.

state · TState

The state associated with the callback.

Returns · ValueTask<TResult>

A task that represents the asynchronous execution and returns the result.

Advanced Execute Methods

ExecuteOutcomeAsync

public ValueTask<Outcome<TResult>> ExecuteOutcomeAsync<TResult, TState>(
    Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> callback,
    ResilienceContext context,
    TState state)

Executes the specified outcome-based callback for advanced, low-allocation scenarios.

callback · Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> · required

The user-provided callback that returns an Outcome<TResult>.

context · ResilienceContext · required

The context associated with the callback.

state · TState

The state associated with the callback.

Returns · ValueTask<Outcome<TResult>>

A task that represents the asynchronous execution and returns the outcome.

The user callback must not throw an exception. Wrap your code and return Outcome<TResult>: use Outcome.FromResult<TResult>(TResult) on success, or Outcome.FromException<TResult>(Exception) on failure. Do not rely on strategies to catch your exceptions.

ResiliencePipeline<T>

A generic version of ResiliencePipeline that constrains result types to T.

Static Properties

Empty · ResiliencePipeline<T>

A resilience pipeline that executes the user-provided callback without any additional logic.

Execute Methods

All execute methods from ResiliencePipeline are available with an additional constraint that TResult : T.

Example Usage

using Polly;

var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions())
    .AddTimeout(TimeSpan.FromSeconds(10))
    .Build();

// Simple synchronous execution
pipeline.Execute(() => 
{
    Console.WriteLine("Executing with resilience");
});

// Synchronous execution with result
var result = pipeline.Execute(() => 
{
    return "Hello, World!";
});

// Asynchronous execution
await pipeline.ExecuteAsync(async ct => 
{
    await Task.Delay(100, ct);
});

// Asynchronous execution with result
var asyncResult = await pipeline.ExecuteAsync(async ct => 
{
    await Task.Delay(100, ct);
    return "Async Result";
});

// With state to avoid allocations
var state = new MyState { Value = 42 };
await pipeline.ExecuteAsync(
    static (s, ct) => s.DoWorkAsync(ct),
    state);

// Using ResilienceContext for advanced scenarios
var context = ResilienceContextPool.Shared.Get();
context.OperationKey = "my-operation";

try
{
    await pipeline.ExecuteAsync(
        static (ctx, state) => state.DoWorkAsync(ctx.CancellationToken),
        context,
        state);
}
finally
{
    ResilienceContextPool.Shared.Return(context);
}

Generic Pipeline Example

using Polly;

var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
    {
        ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
            .Handle<HttpRequestException>()
            .HandleResult(r => !r.IsSuccessStatusCode)
    })
    .Build();

var response = await pipeline.ExecuteAsync(async ct =>
{
    return await httpClient.GetAsync(url, ct);
});