Handling InnerExceptions and AggregateExceptions

Handling InnerExceptions and AggregateExceptions

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

Polly v5.6.0 adds new syntax to natively handle InnerExceptions, both of ordinary exceptions and of AggregateException.

Syntax

.HandleInner<TException>()                       // matches any inner exception of type TException
.HandleInner<TException>(Func<TException, bool>) // matches an inner TException matching the Func
.OrInner<TException>()                           // as above, 'Or' syntax
.OrInner<TException>(Func<TException, bool>)     // as above, 'Or' syntax

Handling inner exceptions can be freely combined with handling non-inner exceptions and with handling returned result values.

Operation

.HandleInner<TException>() matches exceptions at both the top-level (as .Handle<>()), and any inner exceptions.

When the operation executed through the policy throws an AggregateException, the policy will additionally check the flattened InnerExceptions for matches.

When the operation executed through the policy throws an ordinary (non-aggregate) Exception, the policy will additionally recursively check any InnerExceptions for matches.

Communicating matched inner exceptions to calling code

When a .HandleInner<TException>(...) clause matches an inner exception, for convenience, the policy substitutes the matched inner exception (rather than supplying the wrapping outer exception) in any place that communicates matched exceptions to calling code.

Feature	Code element that will be passed the inner exception
Retry policy family	onRetry
Circuit-breaker policy family	onBreak circuitbreaker.LastException the exception rethrown
Fallback policy	onFallback fallbackAction
ExecuteAndCapture	PolicyResult.FinalException

This prevents user code having to duplicate the logic to extract the inner exception, and allows policy event hooks (eg onRetry, onBreak) to be written in a uniform manner whether the given exception is trapped as a top-level or inner exception.

Retaining full AggregateException information

If it is desired to retain the original AggregateException information (rather than substitute the matched inner exception) this can still be achieved, by handling the AggregateException directly:

.Handle<AggregateException>(ae => /* etc */)