feat: Add isolated API instance functionality

samples/Console/README.md

@@ -43,3 +43,14 @@ The sample defines the following flags using the `InMemoryProvider`:
 ## NativeAOT
 
 This sample is published with [NativeAOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot/) enabled (`PublishAot=true`), demonstrating that the OpenFeature .NET SDK is fully compatible with NativeAOT compilation. See the [AOT Compatibility Guide](../../../docs/AOT_COMPATIBILITY.md) for more details.
+
+## Isolated API Instance
+
+The sample also demonstrates how to create an **isolated API instance** using `Api.CreateIsolated()`. The isolated instance has its own provider with different flag values, proving that it operates independently from the global singleton.
+
+| Flag Key       | Type     | Variants                                                                           | Default Variant |
+| -------------- | -------- | ---------------------------------------------------------------------------------- | --------------- |
+| `bool-flag`    | `bool`   | `on` → `true`, `off` → `false`                                                     | `off`           |
+| `string-flag`  | `string` | `greeting` → `"Howdy, Isolated World!"`, `farewell` → `"See ya!"`                  | `greeting`      |
+
+The isolated instance evaluates flags from its own provider, then shuts down without affecting the global singleton. This is useful for testing, multi-tenant applications, and dependency injection scenarios. See the [specification](https://openfeature.dev/specification/sections/flag-evaluation#18-isolated-api-instances) for more details.

samples/Console/app.cs

@@ -44,3 +44,32 @@
 // Evaluate the `object-flag` flag and print the result to the console
 var objectResult = await client.GetObjectValueAsync("object-flag", new Value("Ben"));
 Console.WriteLine("The `object-flag` flag returned {0}", objectResult.AsString);
+
+// --- Isolated API Instance ---
+// Create an independent API instance with its own provider and state.
+// This is useful for testing, multi-tenant apps, and DI scenarios.
+
+var isolatedFlags = new Dictionary<string, Flag>
+{
+    { "bool-flag", new Flag<bool>(new Dictionary<string, bool> { { "on", true }, { "off", false } }, defaultVariant: "off") },
+    { "string-flag", new Flag<string>(new Dictionary<string, string> { { "greeting", "Howdy, Isolated World!" }, { "farewell", "See ya!" } }, defaultVariant: "greeting") },
+};
+
+var isolated = Api.CreateIsolated();
+await isolated.SetProviderAsync(new InMemoryProvider(isolatedFlags));
+
+var isolatedClient = isolated.GetClient();
+
+Console.WriteLine();
+Console.WriteLine("--- Isolated API Instance ---");
+
+// The isolated instance has its own flag values
+var isolatedBool = await isolatedClient.GetBooleanValueAsync("bool-flag", true);
+Console.WriteLine("Isolated `bool-flag`: {0} (singleton was: {1})", isolatedBool, helloWorldResult);
+
+var isolatedString = await isolatedClient.GetStringValueAsync("string-flag", "default");
+Console.WriteLine("Isolated `string-flag`: {0} (singleton was: {1})", isolatedString, stringResult);
+
+// Shut down the isolated instance — does not affect the global singleton
+await isolated.ShutdownAsync();
+Console.WriteLine("Isolated instance shut down. Singleton is unaffected.");

src/OpenFeature/Api.cs

@@ -34,6 +34,24 @@ public sealed class Api : IEventBus
     static Api() { }
     internal Api() { }
 
+    /// <summary>
+    /// Creates a new, independent instance of the OpenFeature API with fully isolated state.
+    /// <para>
+    /// Each isolated instance maintains its own providers, evaluation context, hooks, event handlers,
+    /// and transaction context propagators. It does not share state with the global <see cref="Instance"/>
+    /// singleton or with any other isolated instance.
+    /// </para>
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A single provider instance should not be bound to more than one API instance at a time.
+    /// Attempting to do so will result in an <see cref="InvalidOperationException"/>.
+    /// </para>
+    /// </remarks>
+    /// <returns>A new, independent <see cref="Api"/> instance.</returns>
+    /// <seealso href="https://openfeature.dev/specification/sections/flag-evaluation#18-isolated-api-instances">Specification 1.8 - Isolated API Instances</seealso>
+    public static Api CreateIsolated() => new Api();
+
     /// <summary>
     /// Sets the default feature provider. In order to wait for the provider to be set, and initialization to complete,
     /// await the returned task.
@@ -56,6 +74,7 @@ public Task SetProviderAsync(FeatureProvider featureProvider)
     /// <returns>A <see cref="Task"/> that completes once Provider initialization is complete.</returns>
     public async Task SetProviderAsync(FeatureProvider featureProvider, CancellationToken cancellationToken)
     {
+        this.ValidateProviderOwnership(featureProvider);
         this._eventExecutor.RegisterDefaultFeatureProvider(featureProvider);
         await this._repository.SetProviderAsync(featureProvider, this.GetContext(), this.AfterInitializationAsync, this.AfterErrorAsync, cancellationToken)
             .ConfigureAwait(false);
@@ -91,6 +110,7 @@ public async Task SetProviderAsync(string domain, FeatureProvider featureProvide
         {
             throw new ArgumentNullException(nameof(domain));
         }
+        this.ValidateProviderOwnership(featureProvider);
         this._eventExecutor.RegisterClientFeatureProvider(domain, featureProvider);
         await this._repository.SetProviderAsync(domain, featureProvider, this.GetContext(), this.AfterInitializationAsync, this.AfterErrorAsync, cancellationToken)
             .ConfigureAwait(false);
@@ -401,4 +421,21 @@ internal static void SetInstance(Api api)
     {
         Instance = api;
     }
+
+    /// <summary>
+    /// Validates that the given provider is not already bound to a different API instance.
+    /// Uses <see cref="Interlocked.CompareExchange{T}"/> for thread-safe check-and-set.
+    /// </summary>
+    /// <param name="featureProvider">The provider to validate ownership for.</param>
+    /// <exception cref="InvalidOperationException">Thrown if the provider is already bound to a different API instance.</exception>
+    private void ValidateProviderOwnership(FeatureProvider featureProvider)
+    {
+        var previous = Interlocked.CompareExchange(ref featureProvider._boundApiInstance, this, null);
+        if (previous is not null && !ReferenceEquals(previous, this))
+        {
+            throw new InvalidOperationException(
+                "This provider instance is already bound to a different API instance. " +
+                "A provider should not be registered with more than one API instance simultaneously.");
+        }
+    }
 }

src/OpenFeature/FeatureProvider.cs

@@ -98,6 +98,13 @@ public abstract Task<ResolutionDetails<Value>> ResolveStructureValueAsync(string
     /// </summary>
     internal virtual ProviderStatus Status { get; set; } = ProviderStatus.NotReady;
 
+    /// <summary>
+    /// Tracks which Api instance this provider is currently bound to.
+    /// A provider should not be registered with more than one API instance simultaneously (spec 1.8.4).
+    /// Use <see cref="Interlocked.CompareExchange{T}"/> for thread-safe check-and-set.
+    /// </summary>
+    internal Api? _boundApiInstance;
+
     /// <summary>
     /// <para>
     /// This method is called before a provider is used to evaluate flags. Providers can overwrite this method,

src/OpenFeature/ProviderRepository.cs

@@ -193,6 +193,13 @@ private async Task ShutdownIfUnusedAsync(
             return;
         }
 
+        // Clear ownership while still under the write lock — the provider is confirmed unused.
+        // This prevents a race where async shutdown clears ownership after a re-registration.
+        if (targetProvider != null)
+        {
+            targetProvider._boundApiInstance = null;
+        }
+
         await this.SafeShutdownProviderAsync(targetProvider, cancellationToken).ConfigureAwait(false);
     }
 
@@ -270,6 +277,12 @@ internal async Task ShutdownAsync(Action<FeatureProvider, Exception>? afterError
             // Set a default provider so the Api is ready to be used again.
             this._defaultProvider = new NoOpFeatureProvider();
             this._featureProviders.Clear();
+
+            // Clear ownership under the write lock for all providers being shut down.
+            foreach (var provider in providers)
+            {
+                provider._boundApiInstance = null;
+            }
         }
         finally
         {

test/OpenFeature.AotCompatibility/Program.cs

@@ -27,6 +27,9 @@ private static async Task Main(string[] args)
             // Test basic API functionality
             await TestBasicApiAsync();
 
+            // Test isolated API instances
+            await TestIsolatedApiAsync();
+
             // Test MultiProvider AOT compatibility
             await TestMultiProviderAotCompatibilityAsync();
 
@@ -49,6 +52,41 @@ private static async Task Main(string[] args)
         }
     }
 
+    private static async Task TestIsolatedApiAsync()
+    {
+        Console.WriteLine("\nTesting isolated API instances...");
+
+        // Create an isolated instance
+        var isolated = Api.CreateIsolated();
+        Console.WriteLine($"✓- Isolated API instance created: {isolated.GetType().Name}");
+
+        // Verify it is distinct from the singleton
+        if (ReferenceEquals(isolated, Api.Instance))
+        {
+            throw new InvalidOperationException("Isolated instance should not be the same as the singleton.");
+        }
+        Console.WriteLine("✓- Isolated instance is distinct from singleton");
+
+        // Set a provider on the isolated instance
+        var provider = new TestProvider();
+        await isolated.SetProviderAsync(provider);
+        Console.WriteLine($"✓- Provider set on isolated instance: {isolated.GetProviderMetadata()?.Name}");
+
+        // Create a client and evaluate a flag
+        var client = isolated.GetClient("isolated-client");
+        var result = await client.GetBooleanValueAsync("test-flag", false);
+        Console.WriteLine($"✓- Isolated client flag evaluation: {result}");
+
+        // Set context on isolated instance and verify independence
+        var context = EvaluationContext.Builder().Set("scope", "isolated").Build();
+        isolated.SetContext(context);
+        Console.WriteLine($"✓- Isolated context set with {context.Count} attributes");
+
+        // Shutdown the isolated instance
+        await isolated.ShutdownAsync();
+        Console.WriteLine("✓- Isolated instance shut down successfully");
+    }
+
     private static async Task TestBasicApiAsync()
     {
         Console.WriteLine("\nTesting basic API functionality...");