Improve usability of ResilienceStrategy<T> (#1428)

Author: martintmk

src/Polly.Core/PublicAPI.Unshipped.txt

@@ -248,18 +248,18 @@ Polly.ResilienceStrategy.ExecuteAsync<TState>(System.Func<Polly.ResilienceContex
 Polly.ResilienceStrategy.ExecuteAsync<TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask
 Polly.ResilienceStrategy.ExecuteOutcomeAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
 Polly.ResilienceStrategy.ResilienceStrategy() -> void
-Polly.ResilienceStrategy<TResult>
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<Polly.ResilienceContext!, TResult>! callback, Polly.ResilienceContext! context) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<System.Threading.CancellationToken, TResult>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<TResult>! callback) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<Polly.ResilienceContext!, TState, TResult>! callback, Polly.ResilienceContext! context, TState state) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<TState, System.Threading.CancellationToken, TResult>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<TState, TResult>! callback, TState state) -> TResult
-Polly.ResilienceStrategy<TResult>.ExecuteAsync(System.Func<Polly.ResilienceContext!, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync(System.Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync<TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync<TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteOutcomeAsync<TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
+Polly.ResilienceStrategy<T>
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, TResult>! callback, Polly.ResilienceContext! context, TState state) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<TState, System.Threading.CancellationToken, TResult>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<TState, TResult>! callback, TState state) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<Polly.ResilienceContext!, TResult>! callback, Polly.ResilienceContext! context) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<System.Threading.CancellationToken, TResult>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<TResult>! callback) -> TResult
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult, TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult>(System.Func<Polly.ResilienceContext!, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult>(System.Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteOutcomeAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
 Polly.ResilienceStrategyBuilder
 Polly.ResilienceStrategyBuilder.Build() -> Polly.ResilienceStrategy!
 Polly.ResilienceStrategyBuilder.ResilienceStrategyBuilder() -> void

src/Polly.Core/ResilienceStrategy.TResult.Async.cs

@@ -7,12 +7,12 @@ namespace Polly;
 /// <summary>
 /// Resilience strategy is used to execute the user-provided callbacks.
 /// </summary>
-/// <typeparam name="TResult">The type of result this strategy supports.</typeparam>
+/// <typeparam name="T">The type of result this strategy supports.</typeparam>
 /// <remarks>
-/// Resilience strategy supports various types of callbacks of <typeparamref name="TResult"/> result type
+/// Resilience strategy supports various types of callbacks of <typeparamref name="T"/> result type
 /// and provides a unified way to execute them. This includes overloads for synchronous and asynchronous callbacks.
 /// </remarks>
-public partial class ResilienceStrategy<TResult>
+public partial class ResilienceStrategy<T>
 {
     internal ResilienceStrategy(ResilienceStrategy strategy) => Strategy = strategy;
 
@@ -21,16 +21,18 @@ public partial class ResilienceStrategy<TResult>
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync<TState>(
+    public ValueTask<TResult> ExecuteAsync<TResult, TState>(
         Func<ResilienceContext, TState, ValueTask<TResult>> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -41,13 +43,15 @@ public ValueTask<TResult> ExecuteAsync<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync(
+    public ValueTask<TResult> ExecuteAsync<TResult>(
         Func<ResilienceContext, ValueTask<TResult>> callback,
         ResilienceContext context)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -58,16 +62,18 @@ public ValueTask<TResult> ExecuteAsync(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync<TState>(
+    public ValueTask<TResult> ExecuteAsync<TResult, TState>(
         Func<TState, CancellationToken, ValueTask<TResult>> callback,
         TState state,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -77,11 +83,12 @@ public ValueTask<TResult> ExecuteAsync<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync(
+    public ValueTask<TResult> ExecuteAsync<TResult>(
         Func<CancellationToken, ValueTask<TResult>> callback,
         CancellationToken cancellationToken = default)
     {
@@ -93,6 +100,7 @@ public ValueTask<TResult> ExecuteAsync(
     /// <summary>
     /// Executes the specified outcome-based callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
@@ -103,10 +111,11 @@ public ValueTask<TResult> ExecuteAsync(
     /// This method is for advanced and high performance scenarios. The caller must make sure that the <paramref name="callback"/>
     /// does not throw any exceptions. Instead, it converts them to <see cref="Outcome{TResult}"/>.
     /// </remarks>
-    public ValueTask<Outcome<TResult>> ExecuteOutcomeAsync<TState>(
+    public ValueTask<Outcome<TResult>> ExecuteOutcomeAsync<TResult, TState>(
         Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);

src/Polly.Core/ResilienceStrategy.TResult.Sync.cs

@@ -2,21 +2,23 @@ namespace Polly;
 
 #pragma warning disable RS0027 // API with optional parameter(s) should have the most parameters amongst its public overloads
 
-public partial class ResilienceStrategy<TResult>
+public partial class ResilienceStrategy<T>
 {
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(
+    public TResult Execute<TResult, TState>(
         Func<ResilienceContext, TState, TResult> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -27,13 +29,15 @@ public TResult Execute<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public TResult Execute(
+    public TResult Execute<TResult>(
         Func<ResilienceContext, TResult> callback,
         ResilienceContext context)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -44,13 +48,15 @@ public TResult Execute(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute(
+    public TResult Execute<TResult>(
         Func<CancellationToken, TResult> callback,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -60,10 +66,12 @@ public TResult Execute(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute(Func<TResult> callback)
+    public TResult Execute<TResult>(Func<TResult> callback)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -73,12 +81,14 @@ public TResult Execute(Func<TResult> callback)
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(Func<TState, TResult> callback, TState state)
+    public TResult Execute<TResult, TState>(Func<TState, TResult> callback, TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -88,16 +98,18 @@ public TResult Execute<TState>(Func<TState, TResult> callback, TState state)
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(
+    public TResult Execute<TResult, TState>(
         Func<TState, CancellationToken, TResult> callback,
         TState state,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);