Resiliency in .NET content

docs/core/resilience/index.md

@@ -3,7 +3,7 @@ title: Introduction to resilient app development
 description: Learn about resiliency as it related to .NET and how to build a resilience pipeline.
 author: IEvangelist
 ms.author: dapine
-ms.date: 09/29/2023
+ms.date: 10/19/2023
 ---
 
 # Introduction to resilient app development
@@ -42,32 +42,11 @@ For more information, see [dotnet add package](../tools/dotnet-add-package.md) o
 
 ## Build a resilience pipeline
 
-To use resilience, you must first build a pipeline of resilience-based strategies. Each configured strategy executes in order of configuration. In other words, order is very important. The entry point is an extension method on the <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> type, named `AddResiliencePipeline`. This method takes an identifier of the pipeline and delegate that configures the pipeline. The delegate is passed an instance of `ResiliencePipelineBuilder`, which is used to add resilience strategies to the pipeline.
+To use resilience, you must first build a pipeline of resilience-based strategies. Each configured strategy executes in order of configuration. In other words, order is important. The entry point is an extension method on the <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> type, named `AddResiliencePipeline`. This method takes an identifier of the pipeline and delegate that configures the pipeline. The delegate is passed an instance of `ResiliencePipelineBuilder`, which is used to add resilience strategies to the pipeline.
 
 Consider the following string-based `key` example:
 
-```csharp
-using Microsoft.Extensions.DependencyInjection;
-using Polly;
-using Polly.CircuitBreaker;
-using Polly.Registry;
-using Polly.Retry;
-
-var services = new ServiceCollection();
-
-const string key = "Retry-CircuitBreaker-Timeout";
-
-services.AddResiliencePipeline(key, builder =>
-{
-    builder.AddRetry(new RetryStrategyOptions());
-
-    builder.AddCircuitBreaker(new CircuitBreakerStrategyOptions());
-
-    builder.AddTimeout(TimeSpan.FromSeconds(5));
-
-    // Add other strategies here...
-});
-```
+:::code language="csharp" source="snippets/resilience/Program.cs" id="setup":::
 
 The preceding code:
 
@@ -99,11 +78,9 @@ Imagine 1,000 globally distributed service instances generating logs and metrics
 
 ### Add resilience enrichment
 
-In addition to registering a resilience pipeline, you can also register resilience enrichment. To add enrichment, call the `AddResilienceEnrichment` extensions method on the `IServiceCollection` instance.
+In addition to registering a resilience pipeline, you can also register resilience enrichment. To add enrichment, call the `AddResilienceEnricher` extensions method on the `IServiceCollection` instance.
 
-```csharp
-services.AddResilienceEnrichment();
-```
+:::code language="csharp" source="snippets/resilience/Program.cs" id="enricher":::
 
 By calling the `AddResilienceEnrichment` extension method, you're adding dimensions on top of the default ones that are built in to the underlying Polly library. The following enrichment dimensions are added:
 
@@ -117,17 +94,7 @@ For more information, see [Polly: Telemetry metrics](https://www.pollydocs.org/a
 
 To use a configured resilience pipeline, you must get the pipeline from a `ResiliencePipelineProvider<TKey>`. When you added the pipeline earlier, the `key` was of type `string`, so you must get the pipeline from the `ResiliencePipelineProvider<string>`.
 
-```csharp
-// Build service provider
-using ServiceProvider provider = services.BuildServiceProvider();
-
-// Get pipeline provider
-ResiliencePipelineProvider<string> pipelineProvider =
-    provider.GetRequiredService<ResiliencePipelineProvider<string>>();
-
-// Get the pipeline
-ResiliencePipeline pipeline = pipelineProvider.GetPipeline(key);
-```
+:::code language="csharp" source="snippets/resilience/Program.cs" id="pipeline":::
 
 The preceding code:
 
@@ -139,14 +106,7 @@ The preceding code:
 
 To use the resilience pipeline, call any of the available `Execute*` methods on the `ResiliencePipeline` instance. For example, consider an example call to `ExecuteAsync` method:
 
-```csharp
-await pipeline.ExecuteAsync(static async cancellationToken =>
-{
-    // Code that could potentially fail.
-
-    await ValueTask.CompletedTask;
-});
-```
+:::code language="csharp" source="snippets/resilience/Program.cs" id="execute":::
 
 The preceding code executes the delegate within the `ExecuteAsync` method. When there are failures, the configured strategies are executed. For example, if the `RetryStrategy` is configured to retry three times, the delegate is executed three times before the failure is propagated.
 

docs/core/resilience/snippets/http-resilience/Comment.cs

@@ -1,2 +1,4 @@
-public record class Comment(
+namespace Http.Resilience.Example;
+
+public record class Comment(
     int PostId, int Id, string Name, string Email, string Body);

docs/core/resilience/snippets/http-resilience/ExampleClient.cs

@@ -1,7 +1,16 @@
 using System.Net.Http.Json;
 
+namespace Http.Resilience.Example;
+
+/// <summary>
+/// An example client service, that relies on the <see cref="HttpClient"/> instance.
+/// </summary>
+/// <param name="client">The given <see cref="HttpClient"/> instance.</param>
 internal sealed class ExampleClient(HttpClient client)
 {
+    /// <summary>
+    /// Returns an <see cref="IAsyncEnumerable{T}"/> of <see cref="Comment"/>s.
+    /// </summary>
     public IAsyncEnumerable<Comment?> GetCommentsAsync()
     {
         return client.GetFromJsonAsAsyncEnumerable<Comment>("/comments");

docs/core/resilience/snippets/http-resilience/Program.CustomHandler.cs

@@ -0,0 +1,68 @@
+using System.Net;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Http.Resilience;
+using Polly;
+
+internal partial class Program
+{
+    private static void WithCustomHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <custom>
+        httpClientBuilder.AddResilienceHandler(
+            "CustomPipeline",
+            static builder =>
+        {
+            // See: https://www.pollydocs.org/strategies/retry.html
+            builder.AddRetry(new HttpRetryStrategyOptions
+            {
+                // Customize and configure the retry logic.
+                BackoffType = DelayBackoffType.Exponential,
+                MaxRetryAttempts = 5,
+                UseJitter = true
+            });
+
+            // See: https://www.pollydocs.org/strategies/circuit-breaker.html
+            builder.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
+            {
+                // Customize and configure the circuit breaker logic.
+                SamplingDuration = TimeSpan.FromSeconds(10),
+                FailureRatio = 0.2,
+                MinimumThroughput = 3,
+                ShouldHandle = static args =>
+                {
+                    return ValueTask.FromResult(args is
+                    {
+                        Outcome.Result.StatusCode:
+                            HttpStatusCode.RequestTimeout or
+                                HttpStatusCode.TooManyRequests
+                    });
+                }
+            });
+
+            // See: https://www.pollydocs.org/strategies/timeout.html
+            builder.AddTimeout(TimeSpan.FromSeconds(5));
+        });
+        // </custom>
+    }
+
+    private static void WithAdvancedCustomHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <advanced>
+        httpClientBuilder.AddResilienceHandler(
+            "AdvancedPipeline",
+            static (ResiliencePipelineBuilder<HttpResponseMessage> builder,
+                ResilienceHandlerContext context) =>
+            {
+                // Enable the reloads whenever the named options change
+                context.EnableReloads<HttpRetryStrategyOptions>("RetryOptions");
+
+                // Retrieve the named options
+                var retryOptions =
+                    context.GetOptions<HttpRetryStrategyOptions>("RetryOptions");
+
+                // Add retries using the resolved options
+                builder.AddRetry(retryOptions);
+            });
+        // </advanced>
+    }
+}

docs/core/resilience/snippets/http-resilience/Program.HedgingHandler.cs

@@ -0,0 +1,58 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Http.Resilience;
+
+internal partial class Program
+{
+    private static void WithStandardHedgingHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <standard>
+        httpClientBuilder.AddStandardHedgingHandler();
+        // </standard>
+    }
+
+    private static void WithConfiguredStandardHedgingHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <ordered>
+        httpClientBuilder.AddStandardHedgingHandler(static (IRoutingStrategyBuilder builder) =>
+        {
+            // Hedging allows sending multiple concurrent requests
+            builder.ConfigureOrderedGroups(static options =>
+            {
+                options.Groups.Add(new UriEndpointGroup()
+                {
+                    Endpoints =
+                    {
+                        // Imagine a scenario where 3% of the requests are 
+                        // sent to the experimental endpoint.
+                        new() { Uri = new("https://example.net/api/experimental"), Weight = 3 },
+                        new() { Uri = new("https://example.net/api/stable"), Weight = 97 }
+                    }
+                });
+            });
+        });
+        // </ordered>
+
+        // <weighted>
+        httpClientBuilder.AddStandardHedgingHandler(static (IRoutingStrategyBuilder builder) =>
+        {
+            // Hedging allows sending multiple concurrent requests
+            builder.ConfigureWeightedGroups(static options =>
+            {
+                options.SelectionMode = WeightedGroupSelectionMode.EveryAttempt;
+
+                options.Groups.Add(new WeightedUriEndpointGroup()
+                {
+                    Endpoints =
+                    {
+                        // Imagine a/b testing
+                        new() { Uri = new("https://example.net/api/a"), Weight = 33 },
+                        new() { Uri = new("https://example.net/api/b"), Weight = 33 },
+                        new() { Uri = new("https://example.net/api/c"), Weight = 33 }
+                    }
+                });
+            });
+        });
+        // </weighted>
+    }
+}
+

docs/core/resilience/snippets/http-resilience/Program.ResilienceHandler.cs

@@ -0,0 +1,22 @@
+using Microsoft.Extensions.DependencyInjection;
+using Polly;
+
+internal partial class Program
+{
+    private static void WithStandardHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <standard>
+        httpClientBuilder.AddStandardResilienceHandler();
+        // </standard>
+    }
+
+    private static void WithConfiguredStandardHandler(IHttpClientBuilder httpClientBuilder)
+    {
+        // <configure>
+        httpClientBuilder.AddStandardResilienceHandler(static options =>
+        {
+            options.Retry.BackoffType = DelayBackoffType.Linear;
+        });
+        // </configure>
+    }
+}

docs/core/resilience/snippets/http-resilience/Program.RetryOptions.cs

@@ -0,0 +1,17 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Http.Resilience;
+
+internal partial class Program
+{
+    private static void ConfigureRetryOptions(HostApplicationBuilder builder)
+    {
+        // <options>
+        var section =
+            builder.Configuration.GetSection("RetryOptions");
+
+        builder.Services.Configure<HttpRetryStrategyOptions>(section);
+        // </options>
+    }
+}

docs/core/resilience/snippets/http-resilience/Program.ServiceCollection.cs

@@ -0,0 +1,19 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Http.Resilience.Example;
+
+internal partial class Program
+{
+    private static void CreateServiceCollection()
+    {
+        // <services>
+        var services = new ServiceCollection();
+
+        var httpClientBuilder = services.AddHttpClient<ExampleClient>(
+            configureClient: static client =>
+            {
+                client.BaseAddress = new("https://jsonplaceholder.typicode.com");
+            });
+        // </services>
+    }
+}