[Feature] Add support for keyed services (#1881)

Closes #1874

Author: martintmk

README.md

@@ -84,6 +84,9 @@ var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProv
 // Retrieve your resilience pipeline using the name it was registered with
 ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
 
+// Alternatively, you can use keyed services to retrieve the resilience pipeline
+pipeline = serviceProvider.GetRequiredKeyedService<ResiliencePipeline>("my-pipeline");
+
 // Execute the pipeline
 await pipeline.ExecuteAsync(static async token =>
 {

docs/advanced/dependency-injection.md

@@ -100,6 +100,56 @@ await pipeline.ExecuteAsync(
 ```
 <!-- endSnippet -->
 
+## Keyed services
+
+.NET 8 introduced support for [keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services).
+Starting from version 8.3.0, Polly supports the retrieval of `ResiliencePipeline` or `ResiliencePipeline<T>` using keyed services.
+
+To begin, define your resilience pipeline:
+
+<!-- snippet: di-keyed-services-define -->
+```cs
+// Define a resilience pipeline
+services.AddResiliencePipeline<string, HttpResponseMessage>("my-pipeline", builder =>
+{
+    // Configure the pipeline
+});
+
+// Define a generic resilience pipeline
+services.AddResiliencePipeline("my-pipeline", builder =>
+{
+    // Configure the pipeline
+});
+```
+<!-- endSnippet -->
+
+Following the definition above, you can resolve the resilience pipelines using keyed services as shown in the example below:
+
+<!-- snippet: di-keyed-services-use -->
+```cs
+public class MyApi
+{
+    private readonly ResiliencePipeline _pipeline;
+    private readonly ResiliencePipeline<HttpResponseMessage> _genericPipeline;
+
+    public MyApi(
+        [FromKeyedServices("my-pipeline")]
+        ResiliencePipeline pipeline,
+        [FromKeyedServices("my-pipeline")]
+        ResiliencePipeline<HttpResponseMessage> genericPipeline)
+    {
+        // Although the pipelines are registered with the same key, they are distinct instances.
+        // One is generic, the other is not.
+        _pipeline = pipeline;
+        _genericPipeline = genericPipeline;
+    }
+}
+```
+<!-- endSnippet -->
+
+> [!NOTE]
+> The resilience pipelines are registered in the DI container as transient services. This enables the resolution of multiple instances of `ResiliencePipeline` when [complex pipeline keys](#complex-pipeline-keys) are used. The resilience pipeline is retrieved and registered using `ResiliencePipelineProvider` that is responsible for lifetime management of resilience pipelines.
+
 ## Deferred addition of pipelines
 
 If you want to use a key for a resilience pipeline that may not be available
@@ -133,6 +183,9 @@ services
 ```
 <!-- endSnippet -->
 
+> [!NOTE]
+> The `AddResiliencePipelines` method does not support keyed services. To enable the resolution of a resilience pipeline using keyed services, you should use the `AddResiliencePipeline` extension method, which adds a single resilience pipeline and registers it into the keyed services.
+
 ## Dynamic reloads
 
 Dynamic reloading is a feature of the pipeline registry that is also surfaced when

docs/getting-started.md

@@ -54,6 +54,9 @@ var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProv
 // Retrieve your resilience pipeline using the name it was registered with
 ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
 
+// Alternatively, you can use keyed services to retrieve the resilience pipeline
+pipeline = serviceProvider.GetRequiredKeyedService<ResiliencePipeline>("my-pipeline");
+
 // Execute the pipeline
 await pipeline.ExecuteAsync(static async token =>
 {

src/Polly.Extensions/DependencyInjection/PollyServiceCollectionExtensions.cs

@@ -68,6 +68,15 @@ public static IServiceCollection AddResiliencePipeline<TKey, TResult>(
         Guard.NotNull(services);
         Guard.NotNull(configure);
 
+        services.TryAddKeyedTransient(
+            key,
+            (serviceProvider, key) =>
+            {
+                var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<TKey>>();
+
+                return pipelineProvider.GetPipeline<TResult>((TKey)key!);
+            });
+
         return services.AddResiliencePipelines<TKey>((context) =>
         {
             context.AddResiliencePipeline(key, configure);
@@ -125,6 +134,15 @@ public static IServiceCollection AddResiliencePipeline<TKey>(
         Guard.NotNull(services);
         Guard.NotNull(configure);
 
+        services.TryAddKeyedTransient(
+            key,
+            (serviceProvider, key) =>
+            {
+                var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<TKey>>();
+
+                return pipelineProvider.GetPipeline((TKey)key!);
+            });
+
         return services.AddResiliencePipelines<TKey>((context) =>
         {
             context.AddResiliencePipeline(key, configure);

src/Snippets/Docs/DependencyInjection.cs

@@ -10,6 +10,8 @@
 
 namespace Snippets.Docs;
 
+#pragma warning disable IDE0052 // Remove unread private members
+
 internal static class DependencyInjection
 {
     public static async Task AddResiliencePipeline()
@@ -85,6 +87,47 @@ await pipeline.ExecuteAsync(
         #endregion
     }
 
+    public static async Task KeyedServicesDefine(IServiceCollection services)
+    {
+        #region di-keyed-services-define
+
+        // Define a resilience pipeline
+        services.AddResiliencePipeline<string, HttpResponseMessage>("my-pipeline", builder =>
+        {
+            // Configure the pipeline
+        });
+
+        // Define a generic resilience pipeline
+        services.AddResiliencePipeline("my-pipeline", builder =>
+        {
+            // Configure the pipeline
+        });
+
+        #endregion
+    }
+
+    #region di-keyed-services-use
+
+    public class MyApi
+    {
+        private readonly ResiliencePipeline _pipeline;
+        private readonly ResiliencePipeline<HttpResponseMessage> _genericPipeline;
+
+        public MyApi(
+            [FromKeyedServices("my-pipeline")]
+            ResiliencePipeline pipeline,
+            [FromKeyedServices("my-pipeline")]
+            ResiliencePipeline<HttpResponseMessage> genericPipeline)
+        {
+            // Although the pipelines are registered with the same key, they are distinct instances.
+            // One is generic, the other is not.
+            _pipeline = pipeline;
+            _genericPipeline = genericPipeline;
+        }
+    }
+
+    #endregion
+
     public static async Task DeferredAddition(IServiceCollection services)
     {
         #region di-deferred-addition

src/Snippets/Docs/Readme.cs

@@ -47,6 +47,9 @@ public static async Task QuickStartDi()
         // Retrieve your resilience pipeline using the name it was registered with
         ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
 
+        // Alternatively, you can use keyed services to retrieve the resilience pipeline
+        pipeline = serviceProvider.GetRequiredKeyedService<ResiliencePipeline>("my-pipeline");
+
         // Execute the pipeline
         await pipeline.ExecuteAsync(static async token =>
         {

test/Polly.Extensions.Tests/DependencyInjection/PollyServiceCollectionExtensionTests.cs

@@ -197,6 +197,56 @@ public void AddResiliencePipeline_Single_Ok()
         provider.GetPipeline("my-pipeline").Should().BeSameAs(provider.GetPipeline("my-pipeline"));
     }
 
+    [Fact]
+    public void AddResiliencePipeline_KeyedSingleton_Ok()
+    {
+        AddResiliencePipeline(Key);
+
+        var provider = _services.BuildServiceProvider();
+
+        var pipeline = provider.GetKeyedService<ResiliencePipeline>(Key);
+        provider.GetKeyedService<ResiliencePipeline>(Key).Should().BeSameAs(pipeline);
+
+        pipeline.Should().NotBeNull();
+    }
+
+    [Fact]
+    public void AddResiliencePipeline_GenericKeyedSingleton_Ok()
+    {
+        AddResiliencePipeline<string>(Key);
+
+        var provider = _services.BuildServiceProvider();
+
+        var pipeline = provider.GetKeyedService<ResiliencePipeline<string>>(Key);
+        provider.GetKeyedService<ResiliencePipeline<string>>(Key).Should().BeSameAs(pipeline);
+
+        pipeline.Should().NotBeNull();
+    }
+
+    [Fact]
+    public void AddResiliencePipeline_KeyedSingletonOverride_Ok()
+    {
+        var pipeline = new ResiliencePipelineBuilder().AddTimeout(TimeSpan.FromSeconds(1)).Build();
+        _services.AddKeyedSingleton(Key, pipeline);
+        AddResiliencePipeline(Key);
+
+        var provider = _services.BuildServiceProvider();
+
+        provider.GetKeyedService<ResiliencePipeline>(Key).Should().BeSameAs(pipeline);
+    }
+
+    [Fact]
+    public void AddResiliencePipeline_GenericKeyedSingletonOverride_Ok()
+    {
+        var pipeline = new ResiliencePipelineBuilder<string>().AddTimeout(TimeSpan.FromSeconds(1)).Build();
+        _services.AddKeyedSingleton(Key, pipeline);
+        AddResiliencePipeline(Key);
+
+        var provider = _services.BuildServiceProvider();
+
+        provider.GetKeyedService<ResiliencePipeline<string>>(Key).Should().BeSameAs(pipeline);
+    }
+
     [InlineData(true)]
     [InlineData(false)]
     [Theory]