[Docs] Performance docs improvements (#1618)

docs/advanced/performance.md

@@ -128,3 +128,46 @@ if (outcome.Exception is not null)
 ResilienceContextPool.Shared.Return(context);
 ```
 <!-- endSnippet -->
+
+### Reuse resilience pipeline instances
+
+Creating a resilience pipeline can be resource-intensive, so it's advisable not to discard the instance after each use. Instead, you can either cache the resilience pipeline or use the `GetOrAddPipeline(...)` method from `ResiliencePipelineRegistry<T>` to cache the pipeline dynamically:
+
+<!-- snippet: perf-reuse-pipelines -->
+```cs
+public class MyApi
+{
+    private readonly ResiliencePipelineRegistry<string> _registry;
+
+    // Share a single instance of the registry throughout your application.
+    public MyApi(ResiliencePipelineRegistry<string> registry)
+    {
+        _registry = registry;
+    }
+
+    public async Task UpdateData(CancellationToken cancellationToken)
+    {
+        // Get or create and cache the pipeline for subsequent use.
+        // Choose a sufficiently unique key to prevent collisions.
+        var pipeline = _registry.GetOrAddPipeline("my-app.my-api", builder =>
+        {
+            builder.AddRetry(new()
+            {
+                ShouldHandle = new PredicateBuilder()
+                    .Handle<InvalidOperationException>()
+                    .Handle<HttpRequestException>()
+            });
+        });
+
+        await pipeline.ExecuteAsync(async token =>
+        {
+            // Place your logic here
+        },
+        cancellationToken);
+    }
+}
+```
+<!-- endSnippet -->
+
+> [!NOTE]
+> You can also define your pipeline on startup using [dependency injection](dependency-injection.md#usage) and then use `ResiliencePipelineProvider<T>` to retrieve the instance.

src/Snippets/Docs/Performance.cs

@@ -1,6 +1,7 @@
 using System.Net.Http;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
+using Polly.Registry;
 using Snippets.Docs.Utils;
 
 namespace Snippets.Docs;
@@ -122,4 +123,40 @@ static async (context, state) =>
     public class Member
     {
     }
+
+    #region perf-reuse-pipelines
+
+    public class MyApi
+    {
+        private readonly ResiliencePipelineRegistry<string> _registry;
+
+        // Share a single instance of the registry throughout your application.
+        public MyApi(ResiliencePipelineRegistry<string> registry)
+        {
+            _registry = registry;
+        }
+
+        public async Task UpdateData(CancellationToken cancellationToken)
+        {
+            // Get or create and cache the pipeline for subsequent use.
+            // Choose a sufficiently unique key to prevent collisions.
+            var pipeline = _registry.GetOrAddPipeline("my-app.my-api", builder =>
+            {
+                builder.AddRetry(new()
+                {
+                    ShouldHandle = new PredicateBuilder()
+                        .Handle<InvalidOperationException>()
+                        .Handle<HttpRequestException>()
+                });
+            });
+
+            await pipeline.ExecuteAsync(async token =>
+            {
+                // Place your logic here
+            },
+            cancellationToken);
+        }
+    }
+
+    #endregion
 }