feat: Add multi-provider support

README.md

@@ -113,7 +113,8 @@ Want to contribute a new sample? See our [CONTRIBUTING](CONTRIBUTING.md) guide!
 | ✅     | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                   |
 | ✅     | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread). |
 | ✅     | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                           |
-| 🔬     | [DependencyInjection](#dependency-injection)                         | Integrate OpenFeature with .NET's dependency injection for streamlined provider setup.                                                                        |
+| 🔬     | [Multi-Provider](#multi-provider)                                   | Use multiple feature flag providers simultaneously with configurable evaluation strategies.                                                                   |
+| 🔬     | [DependencyInjection](#dependency-injection)                        | Integrate OpenFeature with .NET's dependency injection for streamlined provider setup.                                                                        |
 
 > Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌ | Experimental: 🔬
 
@@ -433,6 +434,96 @@ Hooks support passing per-evaluation data between that stages using `hook data`.
 
 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!
 
+### Multi-Provider
+
+> [!NOTE]
+> The Multi-Provider feature is currently experimental. Hooks and events are not supported at the moment.
+
+The Multi-Provider enables the use of multiple underlying feature flag providers simultaneously, allowing different providers to be used for different flag keys or based on specific evaluation strategies.
+
+#### Basic Usage
+
+```csharp
+using OpenFeature.Providers.MultiProvider;
+using OpenFeature.Providers.MultiProvider.Models;
+using OpenFeature.Providers.MultiProvider.Strategies;
+
+// Create provider entries
+var providerEntries = new List<ProviderEntry>
+{
+    new(new InMemoryProvider(provider1Flags), "Provider1"),
+    new(new InMemoryProvider(provider2Flags), "Provider2")
+};
+
+// Create multi-provider with FirstMatchStrategy (default)
+var multiProvider = new MultiProvider(providerEntries, new FirstMatchStrategy());
+
+// Set as the default provider
+await Api.Instance.SetProviderAsync(multiProvider);
+
+// Use normally - the multi-provider will handle delegation
+var client = Api.Instance.GetClient();
+var flagValue = await client.GetBooleanValueAsync("my-flag", false);
+```
+
+#### Evaluation Strategies
+
+The Multi-Provider supports different evaluation strategies that determine how multiple providers are used:
+
+##### FirstMatchStrategy (Default)
+
+Evaluates providers sequentially and returns the first result that is not "flag not found". If any provider returns an error, that error is returned immediately.
+
+```csharp
+var multiProvider = new MultiProvider(providerEntries, new FirstMatchStrategy());
+```
+
+##### FirstSuccessfulStrategy
+
+Evaluates providers sequentially and returns the first successful result, ignoring errors. Only if all providers fail will errors be returned.
+
+```csharp
+var multiProvider = new MultiProvider(providerEntries, new FirstSuccessfulStrategy());
+```
+
+##### ComparisonStrategy
+
+Evaluates all providers in parallel and compares results. If values agree, returns the agreed value. If they disagree, returns the fallback provider's value (or first provider if no fallback is specified) and optionally calls a mismatch callback.
+
+```csharp
+// Basic comparison
+var multiProvider = new MultiProvider(providerEntries, new ComparisonStrategy());
+
+// With fallback provider
+var multiProvider = new MultiProvider(providerEntries,
+    new ComparisonStrategy(fallbackProvider: provider1));
+
+// With mismatch callback
+var multiProvider = new MultiProvider(providerEntries,
+    new ComparisonStrategy(onMismatch: (mismatchDetails) => {
+        // Log or handle mismatches between providers
+        foreach (var kvp in mismatchDetails)
+        {
+            Console.WriteLine($"Provider {kvp.Key}: {kvp.Value}");
+        }
+    }));
+```
+
+#### Evaluation Modes
+
+The Multi-Provider supports two evaluation modes:
+
+-   **Sequential**: Providers are evaluated one after another (used by `FirstMatchStrategy` and `FirstSuccessfulStrategy`)
+-   **Parallel**: All providers are evaluated simultaneously (used by `ComparisonStrategy`)
+
+#### Limitations
+
+-   **Hooks are not supported**: Multi-Provider does not currently support hook registration or execution
+-   **Events are not supported**: Provider events are not propagated from underlying providers
+-   **Experimental status**: The API may change in future releases
+
+For a complete example, see the [AspNetCore sample](./samples/AspNetCore/README.md) which demonstrates Multi-Provider usage.
+
 ### Dependency Injection
 
 > [!NOTE]

samples/AspNetCore/Program.cs

@@ -6,6 +6,9 @@
 using OpenFeature.Hooks;
 using OpenFeature.Model;
 using OpenFeature.Providers.Memory;
+using OpenFeature.Providers.MultiProvider;
+using OpenFeature.Providers.MultiProvider.Models;
+using OpenFeature.Providers.MultiProvider.Strategies;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
 using OpenTelemetry.Trace;
@@ -75,6 +78,7 @@
 
     return TypedResults.Ok("Hello world!");
 });
+
 app.MapGet("/test-config", async ([FromServices] IFeatureClient featureClient) =>
 {
     var testConfigValue = await featureClient.GetObjectValueAsync("test-config",
@@ -85,6 +89,56 @@
     return Results.Ok(config);
 });
 
+app.MapGet("/multi-provider", async () =>
+{
+    // Create first in-memory provider with some flags
+    var provider1Flags = new Dictionary<string, Flag>
+    {
+        { "providername", new Flag<string>(new Dictionary<string, string> { { "enabled", "enabled-provider1" }, { "disabled", "disabled-provider1" } }, "enabled") },
+        { "max-items", new Flag<int>(new Dictionary<string, int> { { "low", 10 }, { "high", 100 } }, "high") },
+    };
+    var provider1 = new InMemoryProvider(provider1Flags);
+
+    // Create second in-memory provider with different flags
+    var provider2Flags = new Dictionary<string, Flag>
+    {
+        { "providername", new Flag<string>(new Dictionary<string, string> { { "enabled", "enabled-provider2" }, { "disabled", "disabled-provider2" } }, "enabled") },
+    };
+    var provider2 = new InMemoryProvider(provider2Flags);
+
+    // Create provider entries
+    var providerEntries = new List<ProviderEntry>
+    {
+        new(provider1, "Provider1"),
+        new(provider2, "Provider2")
+    };
+
+    // Create multi-provider with FirstMatchStrategy (default)
+    var multiProvider = new MultiProvider(providerEntries, new FirstMatchStrategy());
+
+    // Set the multi-provider as the default provider using OpenFeature API
+    await Api.Instance.SetProviderAsync(multiProvider);
+
+    // Create a client directly using the API
+    var client = Api.Instance.GetClient();
+
+    try
+    {
+        // Test flag evaluation from different providers
+        var maxItemsFlag = await client.GetIntegerDetailsAsync("max-items", 0);
+        var providerNameFlag = await client.GetStringDetailsAsync("providername", "default");
+
+        // Test a flag that doesn't exist in any provider
+        var unknownFlag = await client.GetBooleanDetailsAsync("unknown-flag", false);
+
+        return Results.Ok();
+    }
+    catch (Exception)
+    {
+        return Results.InternalServerError();
+    }
+});
+
 app.Run();
 
 

src/OpenFeature/Providers/MultiProvider/Models/ChildProviderStatus.cs

@@ -0,0 +1,7 @@
+namespace OpenFeature.Providers.MultiProvider.Models;
+
+internal class ChildProviderStatus
+{
+    public string ProviderName { get; set; } = string.Empty;
+    public Exception? Error { get; set; }
+}

src/OpenFeature/Providers/MultiProvider/Models/ProviderEntry.cs

@@ -0,0 +1,29 @@
+namespace OpenFeature.Providers.MultiProvider.Models;
+
+/// <summary>
+/// Represents an entry for a provider in the multi-provider configuration.
+/// </summary>
+public class ProviderEntry
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ProviderEntry"/> class.
+    /// </summary>
+    /// <param name="provider">The feature provider instance.</param>
+    /// <param name="name">Optional custom name for the provider. If not provided, the provider's metadata name will be used.</param>
+    public ProviderEntry(FeatureProvider provider, string? name = null)
+    {
+        this.Provider = provider ?? throw new ArgumentNullException(nameof(provider));
+        this.Name = name;
+    }
+
+    /// <summary>
+    /// Gets the feature provider instance.
+    /// </summary>
+    public FeatureProvider Provider { get; }
+
+    /// <summary>
+    /// Gets the optional custom name for the provider.
+    /// If null, the provider's metadata name should be used.
+    /// </summary>
+    public string? Name { get; }
+}

src/OpenFeature/Providers/MultiProvider/Models/RegisteredProvider.cs

@@ -0,0 +1,41 @@
+namespace OpenFeature.Providers.MultiProvider.Models;
+
+internal class RegisteredProvider
+{
+#if NET9_0_OR_GREATER
+    private readonly Lock _statusLock = new();
+#else
+    private readonly object _statusLock = new object();
+#endif
+
+    private Constant.ProviderStatus _status = Constant.ProviderStatus.NotReady;
+
+    internal RegisteredProvider(FeatureProvider provider, string name)
+    {
+        this.Provider = provider ?? throw new ArgumentNullException(nameof(provider));
+        this.Name = name ?? throw new ArgumentNullException(nameof(name));
+    }
+
+    internal FeatureProvider Provider { get; }
+
+    internal string Name { get; }
+
+    internal Constant.ProviderStatus Status
+    {
+        get
+        {
+            lock (this._statusLock)
+            {
+                return this._status;
+            }
+        }
+    }
+
+    internal void SetStatus(Constant.ProviderStatus status)
+    {
+        lock (this._statusLock)
+        {
+            this._status = status;
+        }
+    }
+}