feat: Add Dependency Injection and Hosting support for OpenFeature (#310)

This pull request introduces key features and improvements to the
OpenFeature project, focusing on Dependency Injection and Hosting
support:

- **OpenFeature.DependencyInjection Project:**
- Implemented `OpenFeatureBuilder`, including
`OpenFeatureBuilderExtensions` for seamless integration.
  - Added `IFeatureLifecycleManager` interface and its implementation.
- Introduced `AddProvider` extension method for easy provider
configuration.
- Created `OpenFeatureServiceCollectionExtensions` for service
registration.

- **OpenFeature.Hosting Project:**
- Added `HostedFeatureLifecycleService` to manage the lifecycle of
feature providers in hosted environments.

- **Testing Enhancements:**
- Created unit tests for critical methods, including
`OpenFeatureBuilderExtensionsTests` and
`OpenFeatureServiceCollectionExtensionsTests`.
- Replicated and tested `NoOpFeatureProvider` implementation for better
test coverage.

These changes significantly improve OpenFeature's extensibility and
lifecycle management for feature providers within Dependency Injection
(DI) and hosted environments.

Signed-off-by: Artyom Tonoyan <[email protected]>

Author: arttonoyan

Directory.Packages.props

@@ -1,17 +1,20 @@
 <Project>
-
+  
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
-
+  
   <ItemGroup Label="src">
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="8.0.2" />
     <PackageVersion Include="System.Collections.Immutable" Version="1.7.1" />
     <PackageVersion Include="System.Threading.Channels" Version="6.0.0" />
     <PackageVersion Include="System.ValueTuple" Version="4.5.0" />
   </ItemGroup>
-
+  
   <ItemGroup Label="test">
     <PackageVersion Include="AutoFixture" Version="4.18.1" />
     <PackageVersion Include="BenchmarkDotNet" Version="0.14.0" />
@@ -26,10 +29,11 @@
     <PackageVersion Include="SpecFlow.xUnit" Version="3.9.74" />
     <PackageVersion Include="xunit" Version="2.9.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="8.0.1" />
   </ItemGroup>
-
+  
   <ItemGroup Condition="'$(OS)' == 'Unix'">
     <PackageVersion Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" />
   </ItemGroup>
-
+  
 </Project>

OpenFeature.sln

@@ -77,7 +77,13 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.Tests", "test\O
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.Benchmarks", "test\OpenFeature.Benchmarks\OpenFeature.Benchmarks.csproj", "{90E7EAD3-251E-4490-AF78-E758E33518E5}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenFeature.E2ETests", "test\OpenFeature.E2ETests\OpenFeature.E2ETests.csproj", "{7398C446-2630-4F8C-9278-4E807720E9E5}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.E2ETests", "test\OpenFeature.E2ETests\OpenFeature.E2ETests.csproj", "{7398C446-2630-4F8C-9278-4E807720E9E5}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.DependencyInjection", "src\OpenFeature.DependencyInjection\OpenFeature.DependencyInjection.csproj", "{C5415057-2700-48B5-940A-7A10969FA639}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.DependencyInjection.Tests", "test\OpenFeature.DependencyInjection.Tests\OpenFeature.DependencyInjection.Tests.csproj", "{EB35F9F6-8A79-410E-A293-9387BC4AC9A7}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OpenFeature.Hosting", "src\OpenFeature.Hosting\OpenFeature.Hosting.csproj", "{C99DA02A-3981-45A6-B3F8-4A1A48653DEE}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -101,21 +107,36 @@ Global
 		{7398C446-2630-4F8C-9278-4E807720E9E5}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7398C446-2630-4F8C-9278-4E807720E9E5}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{7398C446-2630-4F8C-9278-4E807720E9E5}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C5415057-2700-48B5-940A-7A10969FA639}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C5415057-2700-48B5-940A-7A10969FA639}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C5415057-2700-48B5-940A-7A10969FA639}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C5415057-2700-48B5-940A-7A10969FA639}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EB35F9F6-8A79-410E-A293-9387BC4AC9A7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EB35F9F6-8A79-410E-A293-9387BC4AC9A7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EB35F9F6-8A79-410E-A293-9387BC4AC9A7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{EB35F9F6-8A79-410E-A293-9387BC4AC9A7}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C99DA02A-3981-45A6-B3F8-4A1A48653DEE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C99DA02A-3981-45A6-B3F8-4A1A48653DEE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C99DA02A-3981-45A6-B3F8-4A1A48653DEE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C99DA02A-3981-45A6-B3F8-4A1A48653DEE}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
+		{9392E03B-4E6B-434C-8553-B859424388B1} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
+		{2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
+		{C4746B8C-FE19-440B-922C-C2377F906FE8} = {2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8}
+		{09BAB3A2-E94C-490A-861C-7D1E11BB7024} = {2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8}
+		{4BB69DB3-9653-4197-9589-37FA6D658CB7} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
+		{72005F60-C2E8-40BF-AE95-893635134D7D} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
 		{07A6E6BD-FB7E-4B3B-9CBE-65AE9D0EB223} = {C97E9975-E10A-4817-AE2C-4DD69C3C02D4}
 		{49BB42BA-10A6-4DA3-A7D5-38C968D57837} = {65FBA159-23E0-4CF9-881B-F78DBFF198E9}
 		{90E7EAD3-251E-4490-AF78-E758E33518E5} = {65FBA159-23E0-4CF9-881B-F78DBFF198E9}
 		{7398C446-2630-4F8C-9278-4E807720E9E5} = {65FBA159-23E0-4CF9-881B-F78DBFF198E9}
-		{C4746B8C-FE19-440B-922C-C2377F906FE8} = {2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8}
-		{09BAB3A2-E94C-490A-861C-7D1E11BB7024} = {2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8}
-		{72005F60-C2E8-40BF-AE95-893635134D7D} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
-		{9392E03B-4E6B-434C-8553-B859424388B1} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
-		{2B172AA0-A5A6-4D94-BA1F-B79D59B0C2D8} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
-		{4BB69DB3-9653-4197-9589-37FA6D658CB7} = {E8916D4F-B97E-42D6-8620-ED410A106F94}
+		{C5415057-2700-48B5-940A-7A10969FA639} = {C97E9975-E10A-4817-AE2C-4DD69C3C02D4}
+		{EB35F9F6-8A79-410E-A293-9387BC4AC9A7} = {65FBA159-23E0-4CF9-881B-F78DBFF198E9}
+		{C99DA02A-3981-45A6-B3F8-4A1A48653DEE} = {C97E9975-E10A-4817-AE2C-4DD69C3C02D4}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {41F01B78-FB06-404F-8AD0-6ED6973F948F}

README.md

@@ -79,8 +79,9 @@ public async Task Example()
 | ✅      | [Eventing](#eventing)   | React to state changes in the provider or flag management system.                                                                  |
 | ✅      | [Shutdown](#shutdown)   | Gracefully clean up a provider during application shutdown.                                                                        |
 | ✅      | [Extending](#extending) | Extend OpenFeature with custom providers and hooks.                                                                                |
+| 🔬      | [DependencyInjection](#DependencyInjection) | Integrate OpenFeature with .NET's dependency injection for streamlined provider setup.                         |
 
-> Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌
+> Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌ | Experimental: 🔬
 
 ### Providers
 
@@ -300,6 +301,80 @@ public class MyHook : Hook
 
 Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
 
+### DependencyInjection
+> [!NOTE]
+> The OpenFeature.DependencyInjection and OpenFeature.Hosting packages are currently experimental. They streamline the integration of OpenFeature within .NET applications, allowing for seamless configuration and lifecycle management of feature flag providers using dependency injection and hosting services.
+
+#### Installation
+To set up dependency injection and hosting capabilities for OpenFeature, install the following packages:
+```sh
+dotnet add package OpenFeature.DependencyInjection
+dotnet add package OpenFeature.Hosting
+```
+#### Usage Examples
+For a basic configuration, you can use the InMemoryProvider. This provider is simple and well-suited for development and testing purposes.
+
+**Basic Configuration:**
+```csharp
+builder.Services.AddOpenFeature(featureBuilder => {
+    featureBuilder
+        .AddHostedFeatureLifecycle() // From Hosting package
+        .AddContext((contextBuilder, serviceProvider) => { /* Custom context configuration */ })
+        .AddInMemoryProvider(); 
+});
+```
+**Domain-Scoped Provider Configuration:**
+<br />To set up multiple providers with a selection policy, define logic for choosing the default provider. This example designates `name1` as the default provider:
+```csharp
+builder.Services.AddOpenFeature(featureBuilder => {
+    featureBuilder
+        .AddHostedFeatureLifecycle()
+        .AddContext((contextBuilder, serviceProvider) => { /* Custom context configuration */ })
+        .AddInMemoryProvider("name1")
+        .AddInMemoryProvider("name2")
+        .AddPolicyName(options => {
+            // Custom logic to select a default provider
+            options.DefaultNameSelector = serviceProvider => "name1";
+        });
+});
+```
+#### Creating a New Provider
+To integrate a custom provider, such as InMemoryProvider, you’ll need to create a factory that builds and configures the provider. This section demonstrates how to set up InMemoryProvider as a new provider with custom configuration options.
+
+**Configuring InMemoryProvider as a New Provider**
+<br />Begin by creating a custom factory class, `InMemoryProviderFactory`, that implements `IFeatureProviderFactory`. This factory will initialize your provider with any necessary configurations.
+```csharp
+public class InMemoryProviderFactory : IFeatureProviderFactory
+{
+    internal IDictionary<string, Flag>? Flags { get; set; }
+
+    public FeatureProvider Create() => new InMemoryProvider(Flags);
+}
+```
+**Adding an Extension Method to OpenFeatureBuilder**
+<br />To streamline the configuration process, add an extension method, `AddInMemoryProvider`, to `OpenFeatureBuilder`. This allows you to set up the provider with either a domain-scoped or a default configuration.
+
+```csharp
+public static partial class FeatureBuilderExtensions
+{
+    public static OpenFeatureBuilder AddInMemoryProvider(this OpenFeatureBuilder builder, Action<IDictionary<string, Flag>>? configure = null)
+        => builder.AddProvider<InMemoryProviderFactory>(factory => ConfigureFlags(factory, configure));
+
+    public static OpenFeatureBuilder AddInMemoryProvider(this OpenFeatureBuilder builder, string domain, Action<IDictionary<string, Flag>>? configure = null)
+        => builder.AddProvider<InMemoryProviderFactory>(domain, factory => ConfigureFlags(factory, configure));
+
+    private static void ConfigureFlags(InMemoryProviderFactory factory, Action<IDictionary<string, Flag>>? configure)
+    {
+        if (configure == null)
+            return;
+
+        var flag = new Dictionary<string, Flag>();
+        configure.Invoke(flag);
+        factory.Flags = flag;
+    }
+}
+```
+
 <!-- x-hide-in-docs-start -->
 ## ⭐️ Support the project
 

src/OpenFeature.DependencyInjection/Diagnostics/FeatureCodes.cs

@@ -0,0 +1,38 @@
+namespace OpenFeature.DependencyInjection.Diagnostics;
+
+/// <summary>
+/// Contains identifiers for experimental features and diagnostics in the OpenFeature framework.
+/// </summary>
+/// <remarks>
+/// <c>Experimental</c> - This class includes identifiers that allow developers to track and conditionally enable
+/// experimental features. Each identifier follows a structured code format to indicate the feature domain,
+/// maturity level, and unique identifier. Note that experimental features are subject to change or removal 
+/// in future releases.
+/// <para>
+/// <strong>Basic Information</strong><br/>
+/// These identifiers conform to OpenFeature’s Diagnostics Specifications, allowing developers to recognize 
+/// and manage experimental features effectively.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// Code Structure:
+///     - "OF" - Represents the OpenFeature library.
+///     - "DI" - Indicates the Dependency Injection domain.
+///     - "001" - Unique identifier for a specific feature.
+/// </code>
+/// </example>
+internal static class FeatureCodes
+{
+    /// <summary>
+    /// Identifier for the experimental Dependency Injection features within the OpenFeature framework.
+    /// </summary>
+    /// <remarks>
+    /// <c>OFDI001</c> identifier marks experimental features in the Dependency Injection (DI) domain.
+    /// 
+    /// Usage:
+    /// Developers can use this identifier to conditionally enable or test experimental DI features.
+    /// It is part of the OpenFeature diagnostics system to help track experimental functionality.
+    /// </remarks>
+    public const string NewDi = "OFDI001";
+}

src/OpenFeature.DependencyInjection/Guard.cs

@@ -0,0 +1,20 @@
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace OpenFeature.DependencyInjection;
+
+[DebuggerStepThrough]
+internal static class Guard
+{
+    public static void ThrowIfNull(object? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
+    {
+        if (argument is null)
+            throw new ArgumentNullException(paramName);
+    }
+
+    public static void ThrowIfNullOrWhiteSpace(string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
+    {
+        if (string.IsNullOrWhiteSpace(argument))
+            throw new ArgumentNullException(paramName);
+    }
+}

src/OpenFeature.DependencyInjection/IFeatureLifecycleManager.cs

@@ -0,0 +1,24 @@
+namespace OpenFeature.DependencyInjection;
+
+/// <summary>
+/// Defines the contract for managing the lifecycle of a feature api.
+/// </summary>
+public interface IFeatureLifecycleManager
+{
+    /// <summary>
+    /// Ensures that the feature provider is properly initialized and ready to be used.
+    /// This method should handle all necessary checks, configuration, and setup required to prepare the feature provider.
+    /// </summary>
+    /// <param name="cancellationToken">Propagates notification that operations should be canceled.</param>
+    /// <returns>A Task representing the asynchronous operation of initializing the feature provider.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the feature provider is not registered or is in an invalid state.</exception>
+    ValueTask EnsureInitializedAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gracefully shuts down the feature api, ensuring all resources are properly disposed of and any persistent state is saved.
+    /// This method should handle all necessary cleanup and shutdown operations for the feature provider.
+    /// </summary>
+    /// <param name="cancellationToken">Propagates notification that operations should be canceled.</param>
+    /// <returns>A Task representing the asynchronous operation of shutting down the feature provider.</returns>
+    ValueTask ShutdownAsync(CancellationToken cancellationToken = default);
+}

src/OpenFeature.DependencyInjection/IFeatureProviderFactory.cs

@@ -0,0 +1,23 @@
+namespace OpenFeature.DependencyInjection;
+
+/// <summary>
+/// Provides a contract for creating instances of <see cref="FeatureProvider"/>.
+/// This factory interface enables custom configuration and initialization of feature providers 
+/// to support domain-specific or application-specific feature flag management.
+/// </summary>
+#if NET8_0_OR_GREATER
+[System.Diagnostics.CodeAnalysis.Experimental(Diagnostics.FeatureCodes.NewDi)]
+#endif
+public interface IFeatureProviderFactory
+{
+    /// <summary>
+    /// Creates an instance of a <see cref="FeatureProvider"/> configured according to 
+    /// the specific settings implemented by the concrete factory.
+    /// </summary>
+    /// <returns>
+    /// A new instance of <see cref="FeatureProvider"/>. 
+    /// The configuration and behavior of this provider instance are determined by 
+    /// the implementation of this method.
+    /// </returns>
+    FeatureProvider Create();
+}

src/OpenFeature.DependencyInjection/Internal/FeatureLifecycleManager.cs

@@ -0,0 +1,51 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace OpenFeature.DependencyInjection.Internal;
+
+internal sealed partial class FeatureLifecycleManager : IFeatureLifecycleManager
+{
+    private readonly Api _featureApi;
+    private readonly IServiceProvider _serviceProvider;
+    private readonly ILogger<FeatureLifecycleManager> _logger;
+
+    public FeatureLifecycleManager(Api featureApi, IServiceProvider serviceProvider, ILogger<FeatureLifecycleManager> logger)
+    {
+        _featureApi = featureApi;
+        _serviceProvider = serviceProvider;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async ValueTask EnsureInitializedAsync(CancellationToken cancellationToken = default)
+    {
+        this.LogStartingInitializationOfFeatureProvider();
+
+        var options = _serviceProvider.GetRequiredService<IOptions<OpenFeatureOptions>>().Value;
+        if (options.HasDefaultProvider)
+        {
+            var featureProvider = _serviceProvider.GetRequiredService<FeatureProvider>();
+            await _featureApi.SetProviderAsync(featureProvider).ConfigureAwait(false);
+        }
+
+        foreach (var name in options.ProviderNames)
+        {
+            var featureProvider = _serviceProvider.GetRequiredKeyedService<FeatureProvider>(name);
+            await _featureApi.SetProviderAsync(name, featureProvider).ConfigureAwait(false);
+        }
+    }
+
+    /// <inheritdoc />
+    public async ValueTask ShutdownAsync(CancellationToken cancellationToken = default)
+    {
+        this.LogShuttingDownFeatureProvider();
+        await _featureApi.ShutdownAsync().ConfigureAwait(false);
+    }
+
+    [LoggerMessage(200, LogLevel.Information, "Starting initialization of the feature provider")]
+    partial void LogStartingInitializationOfFeatureProvider();
+
+    [LoggerMessage(200, LogLevel.Information, "Shutting down the feature provider")]
+    partial void LogShuttingDownFeatureProvider();
+}

src/OpenFeature.DependencyInjection/MultiTarget/CallerArgumentExpressionAttribute.cs

@@ -0,0 +1,23 @@
+// @formatter:off
+// ReSharper disable All
+#if NETCOREAPP3_0_OR_GREATER
+// https://github.com/dotnet/runtime/issues/96197
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(System.Runtime.CompilerServices.CallerArgumentExpressionAttribute))]
+#else
+#pragma warning disable
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace System.Runtime.CompilerServices;
+
+[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
+internal sealed class CallerArgumentExpressionAttribute : Attribute
+{
+    public CallerArgumentExpressionAttribute(string parameterName)
+    {
+        ParameterName = parameterName;
+    }
+
+    public string ParameterName { get; }
+}
+#endif

src/OpenFeature.DependencyInjection/MultiTarget/IsExternalInit.cs

@@ -0,0 +1,21 @@
+// @formatter:off
+// ReSharper disable All
+#if NET5_0_OR_GREATER
+// https://github.com/dotnet/runtime/issues/96197
+[assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(System.Runtime.CompilerServices.IsExternalInit))]
+#else
+#pragma warning disable
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.ComponentModel;
+
+namespace System.Runtime.CompilerServices;
+
+/// <summary>
+/// Reserved to be used by the compiler for tracking metadata.
+/// This class should not be used by developers in source code.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+static class IsExternalInit { }
+#endif