Flagmesh.Client 0.1.0-preview.2

Flagmesh .NET SDK

Flagmesh.Client is the official .NET SDK for evaluating Flagmesh feature flags in .NET applications. It supports:

• remote evaluation through the Flagmesh API
• local evaluation from cached SDK config
• polling and SSE-based config refresh
• optional on-disk config persistence for warm starts

Client API key requirement

ClientApiKey is required for normal production or hosted use.

• Required for config fetch, polling refresh, SSE updates, and remote evaluation.
• May be omitted only for local development scenarios or when the SDK is evaluating previously persisted cached config without contacting the server.
• If the SDK needs to contact the Flagmesh server and ClientApiKey is missing, it throws a clear configuration error instead of failing later with a vague HTTP error.

Installation

dotnet add package Flagmesh.Client

Minimum supported runtime: .NET 8.

Quick start

using Flagmesh.Client;

await using var client = new FlagmeshClient(new FlagmeshOptions
{
    BaseUrl = "https://api.flagmesh.com",
    ProjectKey = "checkout-service",
    EnvironmentKey = "production",
    ClientApiKey = Environment.GetEnvironmentVariable("FLAGMESH_CLIENT_API_KEY")
});

var user = new FlagmeshUserContext
{
    Id = "user-123",
    Attributes = new Dictionary<string, object?>
    {
        ["country"] = "GB",
        ["plan"] = "pro"
    }
};

var enabled = await client.IsEnabledAsync("new-checkout", user);

ASP.NET Core DI registration

Program.cs:

using Flagmesh.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFlagmeshClient(builder.Configuration.GetSection("Flagmesh"));

var app = builder.Build();
app.Run();

appsettings.json:

{
  "Flagmesh": {
    "BaseUrl": "https://api.flagmesh.com",
    "ProjectKey": "checkout-service",
    "EnvironmentKey": "production",
    "ClientApiKey": "set-via-user-secrets-or-env",
    "CacheTtl": "00:00:30",
    "PollingInterval": "00:00:30",
    "UsePushUpdates": true,
    "PersistConfigToDisk": true,
    "LocalConfigCachePath": "flagmesh-cache/checkout-service-production.json"
  }
}

You can also register with a delegate:

builder.Services.AddFlagmeshClient(options =>
{
    options.BaseUrl = "https://api.flagmesh.com";
    options.ProjectKey = "checkout-service";
    options.EnvironmentKey = "production";
    options.ClientApiKey = builder.Configuration["Flagmesh:ClientApiKey"];
    options.CacheTtl = TimeSpan.FromSeconds(30);
    options.PollingInterval = TimeSpan.FromSeconds(30);
    options.UsePushUpdates = true;
});

Manual construction

using Flagmesh.Client;

var options = new FlagmeshOptions
{
    BaseUrl = "https://api.flagmesh.com",
    ProjectKey = "checkout-service",
    EnvironmentKey = "production",
    ClientApiKey = Environment.GetEnvironmentVariable("FLAGMESH_CLIENT_API_KEY"),
    CacheTtl = TimeSpan.FromSeconds(30)
};

await using var client = new FlagmeshClient(options);

If you already manage HttpClient yourself:

var httpClient = new HttpClient
{
    BaseAddress = new Uri("https://api.flagmesh.com")
};

await using var client = new FlagmeshClient(httpClient, options);

Configuration options

Local evaluation

When polling, push updates, or disk cache are enabled, the SDK keeps a local compiled config and evaluates flags in-process:

var user = new FlagmeshUserContext { Id = "user-123" };
var enabled = await client.IsEnabledAsync("new-checkout", user);
var variant = await client.GetValueAsync("checkout-variant", user, defaultValue: "control");

Polling example

var client = new FlagmeshClient(new FlagmeshOptions
{
    BaseUrl = "https://api.flagmesh.com",
    ProjectKey = "checkout-service",
    EnvironmentKey = "production",
    ClientApiKey = Environment.GetEnvironmentVariable("FLAGMESH_CLIENT_API_KEY"),
    PollingInterval = TimeSpan.FromSeconds(30),
    UsePushUpdates = false
});

Push update example

Push updates are enabled by default:

var client = new FlagmeshClient(new FlagmeshOptions
{
    BaseUrl = "https://api.flagmesh.com",
    ProjectKey = "checkout-service",
    EnvironmentKey = "production",
    ClientApiKey = Environment.GetEnvironmentVariable("FLAGMESH_CLIENT_API_KEY"),
    UsePushUpdates = true,
    PollingInterval = TimeSpan.FromMinutes(1)
});

The SDK uses SSE to receive config-change notifications and refetches config when a new version is announced. Polling can remain enabled as a fallback. Push updates require ClientApiKey.

Disk cache example

var client = new FlagmeshClient(new FlagmeshOptions
{
    BaseUrl = "https://api.flagmesh.com",
    ProjectKey = "checkout-service",
    EnvironmentKey = "production",
    ClientApiKey = Environment.GetEnvironmentVariable("FLAGMESH_CLIENT_API_KEY"),
    PersistConfigToDisk = true,
    LocalConfigCachePath = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
        "Flagmesh",
        "checkout-service-production.json")
});

JSON flag values

public sealed class CheckoutConfig
{
    public bool NewFlowEnabled { get; init; }
    public int TimeoutSeconds { get; init; }
}

var config = await client.GetJsonAsync(
    "checkout-config",
    new FlagmeshUserContext { Id = "user-123" },
    defaultValue: new CheckoutConfig());

Error handling and fallback behaviour

• IsEnabledAsync() and GetValueAsync() throw when the request fails and no fallback path is available.
• TryIsEnabledAsync() returns the supplied fallback instead of throwing.
• When local config is available, the SDK prefers local evaluation.
• When local config is unavailable, the SDK falls back to the remote /api/evaluate endpoint.
• Remote config fetch, polling, SSE refresh, and remote evaluation require ClientApiKey.
• Disk cache load and disk cache writes are best-effort and never crash the process.

Thread safety and lifecycle

• Register IFlagmeshClient as a singleton in DI.
• FlagmeshClient is safe for concurrent use across requests.
• The SDK starts polling and/or SSE background work when configured.
• Dispose the client during shutdown. await using is recommended for manually created instances.
• If you pass your own HttpClient, the SDK does not dispose it.

Troubleshooting

• Ensure BaseUrl is an absolute http or https URL.
• Ensure ProjectKey and EnvironmentKey match the configured project and environment.
• Ensure ClientApiKey is set for production or hosted use and that it is a client key, not an admin credential.
• If you intentionally omit ClientApiKey, disable UsePushUpdates and PollingInterval unless you are only using previously persisted cached config.
• If using disk persistence, set LocalConfigCachePath.
• If you want local evaluation without SSE, set PollingInterval to a positive value.
• If evaluations unexpectedly call the server, confirm the SDK config endpoint is reachable and returning data.

Support

Hosted service: flagmesh.com