OpenFeature .NET Provider

Introduction

The OpenFeature .NET Provider is intended to be used in combination with the OpenFeature .NET SDK. The provider wraps the ConfigDirector .NET SDK.

The provider targets net8.0 and netstandard2.0, so it runs on .NET 8 and later as well as on .NET Framework 4.6.2 and later. It requires version 2.14.1 or later of the OpenFeature .NET SDK.

The provider is thread safe. Register one instance when your application starts, and shut OpenFeature down when it stops. Evaluations read config state the provider already holds in memory, so they make no network calls on the request path.

In an ASP.NET Core application, the OpenFeature.Hosting package does that wiring for you. Everything on this page applies either way, see ASP.NET Core further below.

Installation

The provider can be installed from NuGet: https://www.nuget.org/packages/ConfigDirector.OpenFeature.ServerProvider

The OpenFeature .NET SDK (OpenFeature) and the ConfigDirector .NET SDK (ConfigDirector.ServerSdk) are included as dependencies.

dotnet add package ConfigDirector.OpenFeature.ServerProvider --version 1.8.0

<ItemGroup>
  <PackageReference Include="ConfigDirector.OpenFeature.ServerProvider" Version="1.8.0" />
</ItemGroup>

Configure and initialize the client

1. Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under SDK keys in the dashboard's navigation panel.
2. Set the OpenFeature provider.
3. Get a client instance from OpenFeature.

using ConfigDirector.OpenFeature;
using OpenFeature;

// IMPORTANT: Do not commit the server SDK key to your source code, it is a secret value.
// Waits until the provider is initialized or it times out.
// If initialization times out, the provider will continue attempting to
// initialize in the background.
await Api.Instance.SetProviderAsync(new ConfigDirectorProvider("YOUR-SERVER-SDK-KEY"));
var client = Api.Instance.GetClient();

SetProviderAsync completes when the initial config state arrives or the configured timeout elapses, and it does not throw on a connection failure. Until config state arrives, evaluations return the default value with the PROVIDER_NOT_READY error code, and the provider continues to connect in the background. Check client.ProviderStatus to find out whether config state actually arrived:

using OpenFeature.Constant;

var ready = client.ProviderStatus == ProviderStatus.Ready;

Additional configuration options

Additional configuration options can be passed into the provider in the optional second argument of the constructor, which takes the same ConfigDirectorClientOptions the .NET SDK client does.

For example, the Metadata can be provided like this:

using ConfigDirector;
using ConfigDirector.OpenFeature;

var provider = new ConfigDirectorProvider("YOUR-SERVER-SDK-KEY", new ConfigDirectorClientOptions
{
    Metadata = new Metadata { AppName = "YOUR-APP-NAME", AppVersion = "1.0.2" },
});

The provider accepts the same Metadata, LoggerFactory, Connection, and Telemetry options as the .NET SDK client, refer to the additional configuration options section of the .NET SDK for a full list.

That includes running without a connection: built with new ConfigDirectorProvider(options) and no server SDK key, the provider serves the values you give it without connecting to ConfigDirector, and if those values cannot be loaded OpenFeature puts the provider in its error state and evaluations return their in-code default values.

Shut down

Shutting OpenFeature down closes the provider, which closes its connections and reports any pending telemetry:

await Api.Instance.ShutdownAsync();

Retrieve config values

To retrieve config values, use the OpenFeature client:

var booleanValue = await client.GetBooleanValueAsync("my-config-key", false);

var stringValue = await client.GetStringValueAsync("my-string-config-key", "Default");

Each OpenFeature getter maps to a ConfigDirector config type:

GetObjectValueAsync returns the config's JSON as an OpenFeature Value: a Structure for a JSON object or a list for a JSON array, with nested values inside. Numbers inside it are doubles, as OpenFeature represents every number. The in-code default value decides the expected shape: provide a structure for a JSON object, or a list for a JSON array. A config holding JSON of another shape, such as 42 or null, gives the in-code default value with the TYPE_MISMATCH error code.

using OpenFeature.Model;

var settings = await client.GetObjectValueAsync("my-json-config-key", new Value(Structure.Empty));
var theme = settings.AsStructure?.GetValue("theme").AsString;

For additional information regarding the OpenFeature client refer to the OpenFeature .NET SDK documentation.

Evaluation details

The detailed getters of the OpenFeature client, such as GetBooleanDetailsAsync, report why an evaluation produced the value that it did:

The Variant is the name of the variation served, such as treatment, when the config has variations and that variation has a name. Otherwise it is ConfigDirector's ID for the value served, a stable hash you can send to analytics in place of the value itself; values served in offline mode have none. Before version 1.8.0 of the provider, the Variant was always the value ID, so an analytics tool that receives Variant now shows an experiment's evaluations under the variation names. In the last five cases, the in-code default value is returned.

To report an experiment to an analytics tool, follow the page for Amplitude, Mixpanel, Google Analytics 4, Segment or PostHog, which names the event that tool reads.

Context

The context can be provided as the third argument to value getter methods of the OpenFeature client. The OpenFeature .NET provider evaluates targeting rules locally without additional network calls for different contexts.

using OpenFeature.Model;

var context = EvaluationContext.Builder()
    .SetTargetingKey("12345") // In OpenFeature, the targeting key represents the context's identifier
    .Set("name", "Example User")
    // Any arbitrary traits which can be referenced in targeting rules
    .Set("traits", Structure.Builder().Set("region", "North America").Build())
    .Build();

var booleanValue = await client.GetBooleanValueAsync("my-config-key", false, context);

To evaluate flags for an entity other than a user, such as a tenant, set the context kind with a top-level kind attribute:

var tenant = EvaluationContext.Builder()
    .SetTargetingKey("acme")
    .Set("kind", "tenant")
    .Set("name", "Acme Inc.")
    .Set("traits", Structure.Builder().Set("plan", "enterprise").Build())
    .Build();

var booleanValue = await client.GetBooleanValueAsync("my-config-key", false, tenant);

Leaving kind out means user. A kind inside traits is an ordinary trait, not the context kind. A context kind is 1 to 64 lowercase letters, digits, dashes, or underscores. A context with an invalid context kind is ignored: the SDK logs an error, and flags still resolve successfully, as if no context had been given. Context kinds are available from version 1.5.0 of the provider.

The evaluation context maps onto the ConfigDirector context as follows:

An evaluation context with neither a targeting key nor an id attribute skips percentage rollouts: a rollout does not apply to it, and the targeting rules after the rollout are tried, as they are after a conditional rule the context does not match. When none of them applies, the flag resolves to the default targeting rule value with the reason DEFAULT; a later rule that applies resolves with TARGETING_MATCH. A rule that serves a single value still applies to it. To keep an anonymous visitor in a rollout, give the context a stable targeting key, such as a session ID. Version 1.8.0 of the provider ended the evaluation at the skipped rollout and resolved to the default targeting rule value even when a later rule matched, and versions before 1.8.0 served every such context the first share of the rollout.

For additional information regarding the OpenFeature client refer to the OpenFeature .NET SDK documentation.

Events

The provider emits PROVIDER_CONFIGURATION_CHANGED whenever configs are updated on the dashboard or via the admin API, carrying the keys of the configs in the update:

using OpenFeature;
using OpenFeature.Constant;

Api.Instance.AddHandler(
    ProviderEventTypes.ProviderConfigurationChanged,
    payload => Console.WriteLine($"Configs updated: {string.Join(", ", payload?.FlagsChanged ?? [])}"));

It emits PROVIDER_READY when the initial config state arrives after SetProviderAsync has already returned.

Track events

The provider implements OpenFeature's tracking API. client.Track reports to ConfigDirector that something happened in your application, such as a completed checkout, and ConfigDirector shows it on the Live feed and counts it for each variation of a running experiment; see Tracked events.

using OpenFeature;
using OpenFeature.Model;

var client = Api.Instance.GetClient();

client.Track(
    "checkout-completed",
    EvaluationContext.Builder().SetTargetingKey("user-123").Build(),
    TrackingEventDetails.Builder().SetValue(49.9).Set("plan", "pro").Set("seats", 3).Build());

The Value of the tracking event details is sent as the event's value, and their other attributes as the event's details, with a DateTime sent as ISO 8601 text and a number that is not finite sent as null. The context the event happened for is the merged evaluation context: its targeting key, or otherwise its id attribute, and its kind.

An event counts for an experiment only when its evaluation context has the targeting key the experiment's flag was evaluated with, so track with the context you evaluate with. Without one, the event is still reported and counts for no experiment. For a context marked anonymous, the event is reported without the targeting key, so it counts for no experiment either.

The provider sends tracked events as the .NET SDK does, with the same limits. OpenFeature's client throws on a null, empty or whitespace event name before the provider is called. Before version 1.8.0 of the provider, a Track call did nothing.

ASP.NET Core

The OpenFeature.Hosting package registers OpenFeature with the host. It initializes the provider as the host starts, before the server begins listening, so no request is served config defaults while the first config state is still in flight, and it shuts the provider down when the host stops, which closes the ConfigDirector client.

dotnet add package OpenFeature.Hosting

Register the provider through the OpenFeature builder, and take IFeatureClient from the container wherever a config is read:

using ConfigDirector;
using ConfigDirector.OpenFeature;
using OpenFeature;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenFeature(openFeature =>
    openFeature.AddProvider(services => new ConfigDirectorProvider(
        builder.Configuration["ConfigDirector:ServerSdkKey"]!,
        new ConfigDirectorClientOptions
        {
            LoggerFactory = services.GetRequiredService<ILoggerFactory>(),
        })));

var app = builder.Build();

app.MapGet("/checkout", async (IFeatureClient client) =>
    await client.GetBooleanValueAsync("new-checkout", false));

app.Run();

Event handlers are registered on the same builder. They attach once the provider has initialized, so they see the updates that follow startup:

using OpenFeature.Constant;

builder.Services.AddOpenFeature(openFeature =>
{
    openFeature.AddProvider(_ => new ConfigDirectorProvider(builder.Configuration["ConfigDirector:ServerSdkKey"]!));

    openFeature.AddHandler(ProviderEventTypes.ProviderConfigurationChanged, services =>
    {
        var logger = services.GetRequiredService<ILoggerFactory>().CreateLogger("ConfigDirector");
        return payload => logger.LogInformation("Configs updated: {Keys}", payload?.FlagsChanged);
    });
});

Test your code

Code that reads flags through OpenFeature is tested by swapping the provider, so it never has to change for a test and nothing from ConfigDirector is involved. The OpenFeature .NET SDK ships an in-memory provider for that, InMemoryProvider in OpenFeature.Providers.Memory, which serves the values your test sets.

Each flag is a Flag<T> built from its named variants and the default variant it resolves to:

using OpenFeature;
using OpenFeature.Providers.Memory;

public class CheckoutTests : IAsyncLifetime
{
    public Task InitializeAsync() => Task.CompletedTask;

    public Task DisposeAsync() => Api.Instance.ShutdownAsync();

    [Fact]
    public async Task ShowsTheNewCheckout()
    {
        var provider = new InMemoryProvider(new Dictionary<string, Flag>
        {
            ["new-checkout"] = new Flag<bool>(new Dictionary<string, bool> { ["on"] = true, ["off"] = false }, "on"),
            ["max-items"] = new Flag<int>(new Dictionary<string, int> { ["default"] = 20 }, "default"),
        });
        await Api.Instance.SetProviderAsync(provider);
        var client = Api.Instance.GetClient();

        Assert.True(await client.GetBooleanValueAsync("new-checkout", false));
        Assert.Equal(20, await client.GetIntegerValueAsync("max-items", 0));

        await provider.UpdateFlagsAsync(new Dictionary<string, Flag>
        {
            ["new-checkout"] = new Flag<bool>(new Dictionary<string, bool> { ["on"] = true, ["off"] = false }, "off"),
        });
        Assert.False(await client.GetBooleanValueAsync("new-checkout", true));
    }
}

UpdateFlagsAsync replaces every flag, so a flag left out of it resolves to its default value with FLAG_NOT_FOUND afterwards, and emits PROVIDER_CONFIGURATION_CHANGED with the keys it held before and the keys it was given. A flag can also carry a context evaluator, a function from the evaluation context to the name of the variant to serve, for a test of code that targets specific users. Api.Instance is one global, so shut it down after each test with ShutdownAsync, as above, which lets the next test register its own provider. An ASP.NET Core application registers its provider through AddOpenFeature, as the section above shows; keep that registration in one place the test host can replace, so a test host registers the in-memory provider there instead.