ℹ️ This documentation describes the previous Polly v7 API. If you are using the new v8 API, please refer to pollydocs.org.

Polly v7 contains the following breaking changes over v6.

No deprecations with [Obsolete] attributes were published for the sync/async changes, because the removed behaviours were runtime exceptions (not valid functionality) in any case.

To Polly v6, it was possibly to call a synchronous .Execute() method on a concrete class of an asynchronously-configured policy (eg .RetryAsync()) - and vice versa - resulting in a runtime exception.

Polly v6 had already reduced the impact of this legacy behaviour by introducing execution interfaces limiting the execution overloads to those appropriate for the policy type (sync for sync policies; async for async policies). You will see no change in behaviour if you have already been referencing policies via the policy execution interfaces:

IAsyncPolicy retryPolicy = Policy.Handle<Exception>().RetryAsync();

Polly v7 gives async policies their own concrete base classes. These entirely eliminate the possibility of calling async execute overloads on sync policies (and vice versa). There are no changes for policies for synchronous executions.

Retry is an example of the pattern, which applies to all policy types.

The change replaces a runtime exception with compile-time validation.

If you are already you are already referencing policies via the policy execution interfaces, no changes will be necessary.

There are no changes for synchronous policies.

Code referencing a configured async policy via the v6 concrete base type will cause a compilation error in v7:

Policy retryPolicy = Policy.Handle<Exception>().RetryAsync(); // intentional compile-time error from v7

Replace the policy type either with the new, concrete async base type:

AsyncPolicy retryPolicy = Policy.Handle<Exception>().RetryAsync();

or the relevant execution interface:

IAsyncPolicy retryPolicy = Policy.Handle<Exception>().RetryAsync();

or var:

var retryPolicy = Policy.Handle<Exception>().RetryAsync();

Similarly for generic policies, replace:

Policy<HttpResponseMessage> retryPolicy = Policy.HandleResult<HttpResponseMessage>(r => /* some predicate on HttpResponseMessage */).RetryAsync(); // intentional compile-time error from v7

with:

AsyncPolicy<HttpResponseMessage> retryPolicy = Policy.HandleResult<HttpResponseMessage>(r => /* etc */).RetryAsync();

or:

IAsyncPolicy<HttpResponseMessage> retryPolicy = Policy.HandleResult<HttpResponseMessage>(r => /* etc */).RetryAsync();

or:

var retryPolicy = Policy.HandleResult<HttpResponseMessage>(r => /* etc */).RetryAsync();

The core Polly cache policy code was changed so that it becomes possible to cache values of type default(TResult).

This necessitated changing the signatures of all methods in the following public interfaces:

• ISyncCacheProvider
• ISyncCacheProvider<TResult>
• IAsyncCacheProvider
• IAsyncCacheProvider<TResult>

Prior this change it was not possible to cache (for example) false of an execution returning a bool. See #523 for more detail.

Cache providers supplied by the Polly team have been updated to align with the changes. This covers:

• Polly.Caching.Memory
• Polly.Caching.Distributed
• Polly.Caching.Serialization.Json

You will need to update for the changes to the cache provider interfaces shown here:

• ISyncCacheProvider and ISyncCacheProvider<TResult>
• IAsyncCacheProvider and IAsyncCacheProvider<TResult>

The changes required are small: to return a bool indicating whether an item was found in the cache, rather than using default(TResult) to signal that.

Diamond dependencies can arise if you have a solution which references one version of Polly via one axis/in one project, and another project which references a different version of Polly, perhaps indirectly. This leads to a so-called diamond-dependency conflict, in which different code is built against different versions of Polly. Where those versions of Polly differ with breaking changes (eg between v6 and v7), this can cause compilation-time or run-time errors, as only one version of Polly.dll can be included in the built output.

To resolve this, ensure all projects reference the same (usually highest) version of Polly. Where a project references a lower version of Polly indirectly, place a reference to the higher version of Polly at the top-level of that project, and the indirect reference should switch to the higher version too, bringing all versions into line.

See this issue for a worked example with Polly v6 and v7, including visual examples of how the direct and indirect references should look.

These procedures work if you have entire control over the build (eg in your visual studio solution), but may not work if either:

• you are referencing third-party nuget packages which have a reference to Polly v6 (and that package does not yet offer a version upgraded for Polly v7)
• you are using one of the official ASPNET Core Docker Images