feat: Add Dependency Injection and Hosting support for OpenFeature

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.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.0" />
     <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}

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,20 @@
+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>
+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

src/OpenFeature.DependencyInjection/OpenFeature.DependencyInjection.csproj

@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0;net6.0;net8.0;net462</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>OpenFeature.DependencyInjection</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+    <PackageReference Include="Microsoft.Extensions.Options" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\OpenFeature\OpenFeature.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+      <_Parameter1>$(AssemblyName).Tests</_Parameter1>
+    </AssemblyAttribute>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+      <_Parameter1>DynamicProxyGenAssembly2</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
+
+</Project>

src/OpenFeature.DependencyInjection/OpenFeatureBuilder.cs

@@ -0,0 +1,60 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace OpenFeature.DependencyInjection;
+
+/// <summary>
+/// Describes a <see cref="OpenFeatureBuilder"/> backed by an <see cref="IServiceCollection"/>.
+/// </summary>
+/// <param name="services">The services being configured.</param>
+public class OpenFeatureBuilder(IServiceCollection services)
+{
+    /// <summary> The services being configured. </summary>
+    public IServiceCollection Services { get; } = services;
+
+    /// <summary>
+    /// Indicates whether the evaluation context has been configured.
+    /// This property is used to determine if specific configurations or services
+    /// should be initialized based on the presence of an evaluation context.
+    /// </summary>
+    public bool IsContextConfigured { get; internal set; }
+
+    /// <summary>
+    /// Indicates whether the policy has been configured.
+    /// </summary>
+    public bool IsPolicyConfigured { get; internal set; }
+
+    /// <summary>
+    /// Gets a value indicating whether a default provider has been registered.
+    /// </summary>
+    public bool HasDefaultProvider { get; internal set; }
+
+    /// <summary>
+    /// Gets the count of domain-bound providers that have been registered.
+    /// This count does not include the default provider.
+    /// </summary>
+    public int DomainBoundProviderRegistrationCount { get; internal set; }
+
+    /// <summary>
+    /// Validates the current configuration, ensuring that a policy is set when multiple providers are registered
+    /// or when a default provider is registered alongside another provider.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown if multiple providers are registered without a policy, or if both a default provider 
+    /// and an additional provider are registered without a policy configuration.
+    /// </exception>
+    public void Validate()
+    {
+        if (!IsPolicyConfigured)
+        {
+            if (DomainBoundProviderRegistrationCount > 1)
+            {
+                throw new InvalidOperationException("Multiple providers have been registered, but no policy has been configured.");
+            }
+
+            if (HasDefaultProvider && DomainBoundProviderRegistrationCount == 1)
+            {
+                throw new InvalidOperationException("A default provider and an additional provider have been registered without a policy configuration.");
+            }
+        }
+    }
+}