FeatCtrl 1.0.0

Based on the common specifications FeatCtrl SDK Specifications.

Server-side C# SDK for FeatCtrl — feature flag management.

This package provides an SSE client that connects to https://sdk.featctrl.com and keeps an in-memory flag store up to date in real time. It targets .NET 8 and has no external runtime dependencies beyond the .NET base class library.

Installation

dotnet add package FeatCtrl

Requires .NET 8 or later.

Quick start

using FeatCtrl;

// Build a client from environment variables.
// Requires FEATCTRL_SDK_KEY to be set.
var client = FeatCtrlClient.FromEnvironment();

// Start the SSE connection in the background.
client.Connect();

// Wait until the first flag snapshot has been received.
await client.ReadyAsync();

// Evaluate a flag (returns the default value when the flag is absent).
if (client.Flags.IsEnabled("new-checkout", defaultValue: false))
{
    // render new checkout flow
}

// Clean up when your application shuts down.
await client.DisconnectAsync();

Environment variables used by FromEnvironment():

Manual construction

You can also create a client programmatically instead of reading from environment variables:

var client = new FeatCtrlClient(
    sdkKey: "my-sdk-key",
    options: new FeatCtrlOptions
    {
        BaseUrl = "https://sdk.featctrl.com",
        Mode = ConnectionMode.Livestreaming,
        HeartbeatWatchdogSeconds = 120,
        MaxRetries = null,      // unlimited
        BackoffBaseSeconds = 3,
        BackoffMaxSeconds = 30,
    });

Lifecycle hooks

Register event handlers on the client to react to connection events and flag changes.

client.Connected += (_, e) =>
    Console.WriteLine($"[FeatCtrl] connected  conn={e.ConnectionUuid}  inst={e.InstanceUuid}");

client.Disconnected += (_, _) =>
    Console.WriteLine("[FeatCtrl] disconnected");

client.SnapshotReceived += (_, e) =>
    Console.WriteLine($"[FeatCtrl] snapshot — {e.Flags.Count} flag(s)");

client.FlagChanged += (_, e) =>
    Console.WriteLine($"[FeatCtrl] flag updated: {e.Flag.Key} = {e.Flag.Enabled}");

client.FlagDeleted += (_, e) =>
    Console.WriteLine($"[FeatCtrl] flag deleted: {e.Key}");

client.WatchdogTimeout += (_, _) =>
    Console.Error.WriteLine("[FeatCtrl] heartbeat watchdog timed out — reconnecting");

client.Forbidden += (_, _) =>
    Console.Error.WriteLine("[FeatCtrl] 403 Forbidden — SDK key rejected, retries disabled");

// On application shutdown:
await client.DisconnectAsync();

Waiting for the first snapshot

FeatCtrlClient exposes two readiness APIs:

await pattern — useful at application startup to block until flags are available:

client.Connect();
await client.ReadyAsync();

// FlagStore is now populated with the initial snapshot.
bool enabled = client.Flags.IsEnabled("new-checkout", defaultValue: false);

Boolean guard — useful for synchronous checks:

if (client.IsReady)
{
    // flags are available right now
}

Connection modes

Livestreaming (default)

The client maintains a persistent SSE connection and keeps its flag cache up to date in real time.

var client = new FeatCtrlClient("my-sdk-key");
// or: FEATCTRL_MODE=livestreaming

Snapshot

The client connects once to receive the initial flags.snapshot, then immediately calls DELETE /disconnect and closes the stream. Suitable for short-lived processes, batch jobs, or AWS Lambda.

var options = new FeatCtrlOptions { Mode = ConnectionMode.Snapshot };
var client = new FeatCtrlClient("my-sdk-key", options);
// or: FEATCTRL_MODE=snapshot

API reference

FeatCtrlClient

FlagStore

FeatCtrlFlag

public sealed record FeatCtrlFlag
{
    public required string Key { get; init; }
    public required string Name { get; init; }
    public required string FlagType { get; init; }   // always "boolean" in this version
    public required bool Enabled { get; init; }
}

Dependency injection (.NET Generic Host)

FeatCtrlClient implements IAsyncDisposable and integrates naturally with IHostedService or background workers. A minimal setup:

// Program.cs
builder.Services.AddSingleton(_ =>
{
    var client = FeatCtrlClient.FromEnvironment();
    client.Connect();
    return client;
});

// In any service:
public class MyService(FeatCtrlClient featCtrl)
{
    public async Task DoWorkAsync()
    {
        await featCtrl.ReadyAsync();
        if (featCtrl.Flags.IsEnabled("my-feature"))
            // ...
    }
}

Building from source

git clone https://github.com/featctrl/sdk-c-sharp.git
cd sdk-c-sharp
dotnet build FeatCtrl.sln
dotnet test FeatCtrl.sln

Running the sample console

export FEATCTRL_SDK_KEY=your-sdk-key
dotnet run --project samples/FeatCtrl.SampleConsole

Releasing

Releases are created by pushing a version tag. The Pack NuGet workflow builds, tests, packs and publishes to NuGet.org automatically.

git tag v1.0.0
git push origin v1.0.0

The NUGET_API_KEY secret must be configured in the repository settings.