Asynchronous action execution

Asynchronous action execution

ℹ️ 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).

Async / await

In asynchronous execution, all delegates are async and run with await.

SynchronizationContext

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.

Cancellation support

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 a CancellationToken input parameter. The CancellationToken passed into .ExecuteAsync(…) call is passed in turn as the CancellationToken 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.

Use async policies consistently for async execution

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.