Polly.Core

Core classes and interfaces for the Polly resilience library

Overview

The Polly.Core namespace provides the foundational types for building and executing resilience pipelines in .NET applications.

Key Classes

ResilienceContext

A context assigned to a single execution of a ResiliencePipeline. It is created manually or automatically when executing resilience operations.

OperationKey · string?

A key unique to the call site of the current execution. This value should have low cardinality (do not use GUIDs).

CancellationToken · CancellationToken

The cancellation token associated with the execution.

ContinueOnCapturedContext · bool

Indicates whether the execution should continue on the captured context.

Properties · ResilienceProperties

Custom properties attached to the context.

Do not re-use an instance of ResilienceContext across more than one execution. Retrieve contexts from the pool using ResilienceContextPool.Get(CancellationToken) and return them with ResilienceContextPool.Return(ResilienceContext).

Outcome<TResult>

Represents the outcome of an operation, which can be either a result value or an exception. Used in advanced, low-allocation scenarios.

Static Factory Methods

FromResult<TResult> · Outcome<TResult>

Creates an outcome with the given result value.

Show Parameters

value · TResult?

The result value.

FromException<TResult> · Outcome<TResult>

Creates an outcome with the given exception.

Show Parameters

exception · Exception · required

The exception that occurred.

FromResultAsValueTask<TResult> · ValueTask<Outcome<TResult>>

Returns an outcome with the given value wrapped as a completed ValueTask.

Show Parameters

value · TResult

The result value.

FromExceptionAsValueTask<TResult> · ValueTask<Outcome<TResult>>

Returns an outcome with the given exception wrapped as a completed ValueTask.

Show Parameters

exception · Exception · required

The exception that occurred.

Example Usage

using Polly;

// Create a context from the pool
var context = ResilienceContextPool.Shared.Get(cancellationToken);
context.OperationKey = "my-operation";

try
{
    // Use the context in pipeline execution
    await pipeline.ExecuteAsync(
        static (ctx, state) => { /* your logic */ },
        context,
        state);
}
finally
{
    // Always return the context to the pool
    ResilienceContextPool.Shared.Return(context);
}

// Using Outcome for advanced scenarios
public async ValueTask<Outcome<string>> GetDataAsync(
    ResilienceContext context,
    CancellationToken ct)
{
    try
    {
        var result = await FetchDataAsync(ct);
        return Outcome.FromResult(result);
    }
    catch (Exception ex)
    {
        return Outcome.FromException<string>(ex);
    }
}