Asynchronous action execution

Asynchronous action execution

For an overview of syntax and policies available, read first the readme: https://github.com/App-vNext/Polly#asynchronous-support. 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); 

// Asynchronous execute overload
var something = await policy.ExecuteAsync(async () => await DoSomethingAsync());

then Polly will throw InvalidOperationException.

With Polly as with any other async code in .NET, beware mixing sync and async code.