Asynchronous action execution - App-vNext/Polly GitHub Wiki
ℹ️ This documentation describes the previous Polly v7 API. If you are using the new v8 API, please refer to pollydocs.org.
For an overview of syntax and policies available, first read the readme This article describes the asynchronous operation of policies in detail.
Polly fully supports asynchronous executions, using the asynchronous methods:
RetryAsync
WaitAndRetryAsync
CircuitBreakerAsync
- (etc)
ExecuteAsync
ExecuteAndCaptureAsync
in place of their synchronous counterparts Retry
, WaitAndRetry
etc.
A policy instance is defined for either sync or async execution but not both. You must use a synchronous execution overload (eg Execute
) with synchronous-defined policies (eg Retry
); and asynchronous execution overloads (eg ExecuteAsync
) with asynchronous-defined policies (eg RetryAsync
).
In asynchronous execution, all delegates are async
and run with await
.
As recommended for libraries offering an async API, by default, async continuations (when a method resumes from an await
) are not run on a captured synchronization context.
If you require the whole .ExecuteAsync(…)
call to continue on the captured synchronization context, use the overloads taking a bool continueOnCapturedContext
, and set this to true
.
Using an .ExecuteAsync(…)
(or similar) method taking a CancellationToken
allows async action execution to be cancelled. Cancellation can occur:
-
Before the delegate is actioned at all: In common with the Base Class Library implementation in
Task.Run(…)
and elsewhere, if the cancellation token is cancelled before execution begins, the delegate is not executed at all. -
During delegate execution: The action delegates taken by the relevant
.ExecuteAsync(…)
overloads take aCancellationToken
input parameter. TheCancellationToken
passed into.ExecuteAsync(…)
call is passed in turn as theCancellationToken
input parameter to the executed delegate, to support cancellation during delegate execution. - During any wait operations policies carry out: for example, waits between retries; waits for a bulkhead execution slot.
All cancellation throws the usual OperationCanceledException
.
If you erroneously combine a synchronous policy with an asynchronous execute overload as below (or vice versa):
// Synchronous policy
var policy = Policy
.Handle<Exception>()
.Retry(3); // sync policy
// Asynchronous execute overload
var something = await policy.ExecuteAsync(async () => await DoSomethingAsync()); // async execute overload
then Polly (up to v6) will throw InvalidOperationException
. (From Polly v7, the above example will not compile.)
With Polly as with any other async code in .NET, beware mixing sync and async code.