Initialization

Constructor


using CanaryGate;
 
var client = new CanaryGateClient("cg_api_key", new Options());

Parameters

Parameter	Type	Required	Description
`apiKey`	`string`	Yes	Environment API Key. Created under Settings → API Keys.
`options`	`Options`	No	Configuration options. See below.

`Options`

Option	Type	Default	Description
`BaseUrl`	`string`	`http://localhost:3001`	API base URL (useful for self-hosted environments or proxies).
`Environment`	`string`	default environment	Environment slug, sent via the `X-Environment` header.
`Stream`	`bool`	`false`	Opt in to real-time SSE streaming.
`ReconnectDelay`	`TimeSpan`	`5s`	Initial delay before reconnecting a dropped stream.
`MaxReconnectDelay`	`TimeSpan`	`30s`	Maximum backoff delay for stream reconnection.
`HeartbeatTimeout`	`TimeSpan`	`65s`	Time without a server heartbeat before the stream is considered dead and reconnects.

`InitAsync()`


await client.InitAsync();

Executes two actions in sequence:

Makes an HTTP fetch to load all flags for the environment (snapshot)
Opens the SSE connection — only when Stream is enabled. Otherwise flags come from the snapshot request only.

After a successful InitAsync(), GetFlag() reads from the local cache; if the connection degrades later, IsStale() reports it and GetFlag() continues to return the last known values.

Examples

ASP.NET Core (singleton with streaming)


// Program.cs
using CanaryGate;
 
var builder = WebApplication.CreateBuilder(args);
 
var canary = new CanaryGateClient(
    builder.Configuration["CANARYGATE_KEY"]!,
    new Options
    {
        Environment = "production",
        Stream = true,
    }
);
await canary.InitAsync();
 
builder.Services.AddSingleton(canary);
 
var app = builder.Build();
 
app.MapGet("/", (CanaryGateClient canary) =>
{
    var flag = canary.GetFlag("new-checkout", new FlagEvaluationContext { UserId = "user-42" });
    return flag?.Enabled == true ? "New checkout" : "Old checkout";
});
 
app.Run();

One-shot script (no stream)


using CanaryGate;
 
var client = new CanaryGateClient("cg_api_key");
await client.InitAsync();
 
var flag = client.GetFlag("run-migration");
if (flag?.Enabled == true)
{
    await RunMigrationAsync();
}
 
// Disconnect (closes any active stream) so the process can exit
client.Disconnect();