Polly and interfaces - 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.
Policy v5.2.0 introduces interfaces.
Polly's interfaces are intended to support PolicyRegistry
and to group Policy functionality by the interface segregation principle.
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 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
|
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
Each also exists in a generic form such as ICircuitBreakerPolicy<TResult>
.
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).
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.
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.
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
andICacheItemSerializer<TResult, TSerialized>
, for pluggable cache providers and serializers.