Polly and interfaces

Polly and interfaces

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

TL/DR

Policy v5.2.0 introduces interfaces.

Polly's interfaces are intended to support PolicyRegistry and to group Policy functionality by the interface segregation principle.

Execution interfaces and policy-type interfaces

There are two kinds of interface:

• Execution interfaces define the executions which can be made through a policy via the Execute(...) (and similar) overloads
• Policy-type interfaces bring together common behaviour and properties of all policies of a given type (for example, circuitbreaker policies)

The execution interfaces

The execution interfaces are ISyncPolicy, ISyncPolicy<TResult>, IAsyncPolicy and IAsyncPolicy<TResult>.

These interfaces define the executions which can be made through a policy: the available Execute(...) and ExecuteAndCapture(...) overloads, and their async equivalents.

Interface	Usage
ISyncPolicy	for synchronous executions returning void; and for delegates returning any TResult, when HandleResult<TResult>(...) and FallbackPolicy<TResult> are not used.
ISyncPolicy<TResult>	for synchronous executions of delegates returning TResult
IAsyncPolicy	for asynchronous executions returning void; and for delegates returning any TResult, when HandleResult<TResult>(...) and FallbackPolicy<TResult> are not used.
IAsyncPolicy<TResult>	for asynchronous executions of delegates returning TResult

The Policy-type interfaces

An orthogonal set of interfaces represents the behaviour and properties particular to a specific policy type (eg ICircuitBreakerPolicy). The full set of policy-type interfaces is:

• IBulkheadPolicy
• ICachePolicy
• ICircuitBreakerPolicy
• IFallbackPolicy
• INoOpPolicy
• IRetryPolicy
• ITimeoutPolicy
• IPolicyWrap

Generic variants

Each also exists in a generic form such as ICircuitBreakerPolicy<TResult>.

Policy-type interfaces expose behaviour and properties specific to that policy type

Where a policy exposes public methods and properties about its state, these are defined on the given interface. For instance, ICircuitBreakerPolicy defines:

• CircuitState CircuitState
• Exception LastException
• void Isolate()
• void Reset()

and ICircuitBreakerPolicy<TResult> adds:

• TResult LastHandledResult.

This can be used, for instance, to establish custom monitoring of the state of all your circuit-breakers across your application (regardless of whether those circuit-breaker policy instances were for sync or async calls, generic or non-generic).

IsPolicy interface

The IsPolicy interface is an empty marker interface simply denoting that the item is a Polly policy of some kind. It is used by PolicyRegistry to hold all kinds of Policy.

Implementing your own policies

It is not intended that the interfaces are used to implement new, custom policies. Fulfilling all the execution overloads of (for example) ISyncPolicy would be a cumbersome approach. Polly's abstract base class Policy already covers this, and provides execution-dispatch which manages context keys and integration into PolicyWrap. Custom policies should instead be implemented by extending the base classes as described in our blog series on custom policies.

Other interfaces

Polly also enables pluggability via interfaces for some extension points which are not themselves policies. For example:

• IPolicyRegistry<in TKey>, for implementing your own policy registry
• ISyncCacheProvider, IAsyncCacheProvider and ICacheItemSerializer<TResult, TSerialized>, for pluggable cache providers and serializers.