[!NOTE] This is documentation for the upcoming Polly v8 release.
Polly targets .NET Standard 2.0+ (coverage: .NET Core 2.0+, .NET Core 3.0, .NET 6.0+ and later Mono, Xamarin and UWP targets). The NuGet package also includes direct targets for .NET Framework 4.6.1 and 4.7.2.
For details of supported compilation targets by version, see the supported targets grid.
Polly provides native support for asynchronous operations through all its resilience strategies by offering the ExecuteAsync
methods on the ResiliencePipeline
class.
By default, asynchronous continuations and retries do not execute on a captured synchronization context. To modify this behavior, you can use the ResilienceContext
class and set its ContinueOnCapturedContext
property to true
. The following example illustrates this:
// Retrieve an instance of ResilienceContext from the pool
// with the ContinueOnCapturedContext property set to true
ResilienceContext context = ResilienceContextPool.Shared.Get(continueOnCapturedContext: true);
await pipeline.ExecuteAsync(
async context =>
{
// Execute your code, honoring the ContinueOnCapturedContext setting
await MyMethodAsync(context.CancellationToken).ConfigureAwait(context.ContinueOnCapturedContext);
},
context);
// Optionally, return the ResilienceContext instance back to the pool
// to minimize allocations and enhance performance
ResilienceContextPool.Shared.Return(context);
Asynchronous pipeline execution in Polly supports cancellation. This is facilitated through the ExecuteAsync(...)
method overloads that accept a CancellationToken
, or by initializing the ResilienceContext
class with the CancellationToken
property.
The CancellationToken
you pass to the ExecuteAsync(...)
method serves multiple functions:
CancellationToken
parameter, enabling cancellation during the delegate’s execution.Task.Run(...)
, if the cancellation token is cancelled before execution begins, the user-defined delegate will not execute at all.// Execute your code with cancellation support
await pipeline.ExecuteAsync(
async token => await MyMethodAsync(token),
cancellationToken);
// Use ResilienceContext for more advanced scenarios
ResilienceContext context = ResilienceContextPool.Shared.Get(cancellationToken: cancellationToken);
await pipeline.ExecuteAsync(
async context => await MyMethodAsync(context.CancellationToken),
context);
All Polly resilience strategies are fully thread-safe. You can safely re-use strategies at multiple call sites, and execute through strategies concurrently on different threads.
[!IMPORTANT] While the internal operation of the strategy is thread-safe, this does not automatically make delegates you execute through the strategy thread-safe: if delegates you execute through the strategy are not thread-safe, they remain not thread-safe.