Revising Migrating execution policies section

[peter-csala]

While I was reviewing the Migrating execution policies section I realized that we did not emphasize the following thing:

• In case of V7 you have to define your policies in a way to comfort with the to-be-decorated method
• In case of V8 you don't need that. You have to use the generic ResiliencePipelineBuilder only if your strategy depends on the result of the to-be-decorated method

If the strategy do not care about the result

var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new()
    {
        ShouldHandle = _ => PredicateResult.True(),
        MaxRetryAttempts = 2,
        Delay = TimeSpan.Zero
    }).Build();

int i = 0;
Console.WriteLine("Action");
pipeline.Execute(() => { i++; Console.WriteLine(i); });

i = 0;
Console.WriteLine("ValueTask");
await pipeline.ExecuteAsync(ct => { i++; Console.WriteLine(i); return default; });

i = 0;
Console.WriteLine("Func<int>");
var result = pipeline.Execute(() => { i++; Console.WriteLine(i); return i; });

i = 0;
Console.WriteLine("ValueTask<int>");
result = await pipeline.ExecuteAsync(ct => { i++; Console.WriteLine(i); return ValueTask.FromResult(i); });

if the strategy cares about the result

var pipelineT = new ResiliencePipelineBuilder<int>()
    .AddRetry(new()
    {
        ShouldHandle = new PredicateBuilder<int>().HandleResult(r => r < 5),
        MaxRetryAttempts = 2,
        Delay = TimeSpan.Zero
    }).Build();

i = 0;
Console.WriteLine("Func<int>");
result = pipelineT.Execute(() => { i++; Console.WriteLine(i); return i; });

i = 0;
Console.WriteLine("ValueTask<int>");
result = await pipelineT.ExecuteAsync(ct => { i++; Console.WriteLine(i); return ValueTask.FromResult(i); });    

My question is how do want to make this fundamental difference really explicit in the documentation?
cc: @martintmk , @martincostello

[martintmk]

@peter-csala For Polly v7, isn't the ResiliencePipeline ekvivalent to IAsyncPolicy or ISyncPolicy. Those two also allow executing arbitrary callbacks, albeit you are limited to distinguish between async and sync callbacks.

[peter-csala]

Let me double-check this

[peter-csala]

You are right, my bad...

var syncPolicy = Policy.Handle<Exception>().Retry(2);
syncPolicy.Execute(() => { i++; Console.WriteLine(i); throw new NotSupportedException(); });
var result = syncPolicy.Execute<int>(() => { i++; Console.WriteLine(i); throw new NotSupportedException(); });