FEATURE: Fallback policy

As I understand it today, if I use Polly to setup a circuit breaker in my policy and that the circuit does break, I will receive a BrokenCircuitException. As a user of the framework, I need to handle this exception and write some code to specify how I want to react to this event. I would prefer to give to Polly that code and let it execute it if the circuit is broken. It would be better performance-wise, and much cleaner.

Policy
  .Handle<DivideByZeroException>()
  .CircuitBreaker(2, TimeSpan.FromMinutes(1))
  .WhenBroken(
  () => throw new BrokenCircuitException(); //Or another fallback method specific to my app.
)

[reisenberger]

@mfjerome @SeanFarrow Great question from both of you, that I’ve kind-of answered here . We could expose the Exception1 in your example in several places:

[1] in the captured PolicyResult somehow (but complicated) [2] as part of an event stream (later) [3] in a simple onFallback delegate (perfect for logging) [4] to the fallbackFunc as well

In detail:

[1] PolicyResult<TResult> could contain an IEnumerable<Exception> property as @SeanFarrow says, that details other exceptions before the fallback (or anything else if part of a bigger wrap) was invoked. A few issues I see with this as stated here: there may be duplicates, it’s hard (in a broader wrap context) to connect which exception occurred with which policy-in-the-wrap, and it’s actually quite hard to implement in the wrap unless I’m missing something (you kind-of want both-at-the-same-time to capture the exception into some PolicyResult you pass back to capture in the enumerable, but also throw the exception to outer layers at the same time so they can handle it … you can’t capture and throw at the same time??)

[2] Eventually we can capture all manner of policy behaviour as an event stream as suggested here (but not soon).

[3] We offer an additional overload taking a simple onFallback delegate, so:

FallbackPolicy<TResult> fallbackPolicy = Policy
  .Handle<Whatever>(...)
  .Fallback<TResult>(Func<TResult> fallbackFunc, Action<DelegateResult<TResult>> onFallback); // for async variants, Func<DelegateResult<TResult>, Task> onFallbackAsync

This is my preferred option: simple, available now, and parallels the onRetry and onBreak delegates already well known to users on the retry and circuit-breaker policies. The classic solution in Polly for logging faults as the policy operated. Shall we go with this?

[4] A final option is to combine [3] with what @mfjerome suggested, ie offer the DelegateResult to the fallbackFunc too, ie offer additional overloads:

FallbackPolicy<TResult> fallbackPolicy = Policy
  .Handle<Whatever>(...)
  .Fallback<TResult>(Func<DelegateResult<TResult>, TResult> fallbackFunc);
// and
FallbackPolicy<TResult> fallbackPolicy = Policy
  .Handle<Whatever>(...)
  .Fallback<TResult>(Func<DelegateResult<TResult>, TResult> fallbackFunc, Action<DelegateResult<TResult>> onFallback); // for async variants, Func<DelegateResult<TResult>, Task> onFallbackAsync

I’m not sure at the moment if this adds value (maybe somebody really wants to include details of the exception in the fallback value…), or just confusion (too many overloads). Either way, I propose we keep [3]. Do you think [4] adds anything?

[mfjerome]

Agreed the idea will be uniform across policies such as onRetry, onBreak, etc