Feature Toggles for .NET

💡 Why FtrIO?

• Zero call-site noise. [Toggle] is woven directly into the method's IL at compile time. A toggled method looks and calls like any normal method — no if (flags.IsEnabled(...)), no injected service, no wrapper at every call site. Remove the attribute and the method is back to normal.

• appsettings.json as a read-through cache. Other libraries make your app depend on an external flag service being online. FtrIO flips this: providers run in the background and write their state into appsettings.json; ToggleParser always reads from the file. If the remote source goes offline, the last known state is served automatically from disk — no fallback code, no circuit breaker, no TTL to configure.

• Escape hatch built in. The same appsettings.json you already deploy works as a fully functional toggle store without any provider. Swap from a static file to Azure App Config — or back — without touching a single call site.

⚖️ How it compares

🚀 Quick start

1. Install the package

dotnet add package FtrIO

2. Add AspectInjector to your consuming project

AspectInjector weaves [Toggle] IL at compile time, per project. Any project that decorates its own methods needs this:

<PackageReference Include="AspectInjector" Version="2.9.0" />

3. Create appsettings.json

{
  "Toggles": {
    "SendWelcomeEmail": true,
    "NewCheckoutFlow": false
  }
}

4. Copy it to the build output

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>

5. Decorate and call

using FtrIO;

public class EmailService
{
    [Toggle]
    public void SendWelcomeEmail()
    {
        // runs only when "SendWelcomeEmail": true in config
    }
}

Call it like any normal method — FtrIO intercepts the call via IL weaving and checks the config before the body runs. No if, no wrapper, nothing extra at the call site.

🎯 Target frameworks

One NuGet package, five targets:

🔍 Compile-time validation

FtrIO ships a Roslyn analyzer (FTRIO001) that catches missing config entries at build time. If you register your appsettings.json as an AdditionalFile, any [Toggle]-decorated method whose name has no matching entry in Toggles produces a compiler error — the build fails rather than the method misbehaving silently at runtime.

Opt in

<ItemGroup>
  <AdditionalFiles Include="appsettings.json" />
</ItemGroup>

Without this line the analyzer is silent — runtime behaviour is unchanged. The analyzer is included automatically with the NuGet package; no separate install is needed.

Example

<!-- appsettings.json has Toggles.SendWelcomeEmail but not Toggles.NewCheckoutFlow -->

[Toggle] public void SendWelcomeEmail() {}  // ✓ fine
[Toggle] public void NewCheckoutFlow()  {}  // ✗ FTRIO001: 'NewCheckoutFlow' has no entry in Toggles

⚡ Async support

[ToggleAsync] attribute

For methods that return Task or Task<T>, use [ToggleAsync] instead of [Toggle]. It gates the method by its own name against config, but handles the "off" path correctly — returning Task.CompletedTask or Task.FromResult(default) rather than null, so the result is always safely awaitable.

[ToggleAsync]
public async Task SendWelcomeEmailAsync()
{
    await emailClient.SendAsync(...);
}

await SendWelcomeEmailAsync();  // safely awaitable whether the toggle is on or off

ExecuteMethodIfToggleOnAsync

The manual-control equivalent for async. Accepts Func<Task> and Func<Task<TResult>> and always returns an awaitable result:

var featureToggle = new FeatureToggle<bool>();

// Gate a Task-returning method
await featureToggle.ExecuteMethodIfToggleOnAsync(
    () => emailClient.SendAsync(), "SendWelcomeEmail");

// Gate a Task<T>-returning method
var result = await featureToggle.ExecuteMethodIfToggleOnAsync(
    () => orderService.PlaceOrderAsync(), "NewCheckoutFlow");

🔄 Hot-reload

By default, ToggleParser reads appsettings.json once at startup. Set ReloadOnChange: true in the FtrIO section to pick up file changes on disk without a restart.

This is strongly recommended for all applications. If you are using any dynamic provider it is mandatory — without it, ToggleParser reads the file once and never sees the values providers flush to it.

{
  "FtrIO": {
    "ReloadOnChange": true
  },
  "Toggles": {
    "SendWelcomeEmail": true
  }
}

When set, ToggleParser attaches a file watcher via Microsoft.Extensions.Configuration. The next call to any [Toggle]-decorated method after the file changes will reflect the updated values — no restart required.

🌍 Multi-environment support

FtrIO supports unlimited environments. The right approach depends on your infrastructure:

Separate servers per environment

This is the common case and requires no special FtrIO configuration. Each server has its own appsettings.json — they are completely independent. Prod server has prod toggles, staging server has staging toggles. There is no upper limit on how many environments or servers you run.

prod-server/appsettings.json    ← production toggle state
staging-server/appsettings.json ← staging toggle state
dev-machine/appsettings.json    ← dev toggle state

Each deployment is fully self-contained. [Toggle] call sites read from whichever appsettings.json is local to that server — nothing else to configure.

Single machine, multiple environments

When you want to share a base config and override specific keys per environment on one machine, set FtrIO:Environment in appsettings.json to activate an overlay file. ToggleParser layers appsettings.{env}.json on top — env-specific values win, the base fills the gaps.

// appsettings.json
{
  "FtrIO": { "ReloadOnChange": true, "Environment": "Staging" },
  "Toggles": { "SendWelcomeEmail": true, "NewCheckout": false }
}

// appsettings.Staging.json — only what differs from the base
{
  "Toggles": { "NewCheckout": "50%" }
}

When FtrIO:Environment is set, ToggleProviderBuffer also writes provider flushes to the env file — the base file is never modified by providers in this mode.

Remote config sources

For toggle state that lives on a remote server, use a provider. It pulls from the remote source and flushes to the local appsettings.json — works across any number of environments with no file management:

// Azure App Config — one store, one label per environment
new AzureAppConfigToggleParser(connectionString, buffer, label: "staging");

// HTTP config server
new HttpToggleParser("https://config.internal/toggles/staging", buffer);

If the remote source goes offline, the last flushed state in appsettings.json persists automatically — no fallback code needed.

🔌 Custom parser / Dependency Injection

By default, [Toggle], [ToggleAsync], and ExecuteMethodIfToggleOn all use the built-in ToggleParser which reads from appsettings.json. To swap in a custom IToggleParser — one that reads from a database, a feature-flag service, or a DI container — call ToggleParserProvider.Configure once at application startup before any toggled methods run:

using FtrIO;
using FtrIO.Classes;

// Manual — use default ToggleParser at a custom path
ToggleParserProvider.Configure(new ToggleParser());

// With Microsoft.Extensions.DependencyInjection
ToggleParserProvider.Configure(
    host.Services.GetRequiredService<IToggleParser>());

If Configure is never called, the default ToggleParser is used automatically — existing consumers don't need to change anything.

ExecuteMethodIfToggleOn and ExecuteMethodIfToggleOnAsync also accept an IToggleParser directly for per-call control:

await featureToggle.ExecuteMethodIfToggleOnAsync(
    () => SendAsync(), myCustomParser, "SendWelcomeEmail");

Analyzer behaviour with a custom parser

The Roslyn analyzer checks [Toggle]-decorated methods against appsettings.json at build time. If your custom parser does not use appsettings.json, do not register it as an AdditionalFiles entry — doing so will produce false FTRIO001 errors for keys that exist in your custom source but not in the file.

To silence FTRIO001 entirely regardless of parser:

<PropertyGroup>
  <NoWarn>FTRIO001</NoWarn>
</PropertyGroup>

🎲 Strategy-based decisions

StrategyToggleParser is a drop-in replacement for ToggleParser that routes raw config values through a chain of IToggleDecisionStrategy implementations. BooleanStrategy is always appended as the final fallback so existing true/false values continue to work with no changes.

Percentage rollout

Any value ending in % is handled by PercentageRolloutStrategy. The check is probabilistic per-call — a 20% rollout means roughly 1 in 5 calls execute the method body:

// appsettings.json
{ "Toggles": { "NewCheckout": "20%" } }

// startup
ToggleParserProvider.Configure(new StrategyToggleParser(new PercentageRolloutStrategy()));

[Toggle]
public void NewCheckout() { ... }  // runs ~20% of the time

Blue-green deployment

BlueGreenStrategy routes by named deployment slot. The current slot is declared at startup; the config value is the slot that should be active:

// appsettings.json
{ "Toggles": { "PaymentV2": "blue" } }

// startup — currentSlot, knownSlots...
ToggleParserProvider.Configure(new StrategyToggleParser(
    new BlueGreenStrategy("blue", "blue", "green")));

[Toggle]
public void PaymentV2() { ... }  // runs only on the "blue" slot

Combining strategies

Strategies are tried in registration order — the first whose CanHandle returns true wins. BooleanStrategy is always appended automatically as the final fallback.

ToggleParserProvider.Configure(new StrategyToggleParser(
    new PercentageRolloutStrategy(),
    new BlueGreenStrategy("blue", "blue", "green")
    // BooleanStrategy auto-appended — handles true/false/1/0
));

Custom strategies

Implement IToggleDecisionStrategy to add any decision logic your application needs:

public class TimeWindowStrategy : IToggleDecisionStrategy
{
    public bool CanHandle(string rawValue) => rawValue.Contains(".."); // e.g. "09:00..17:00"
    public bool ShouldExecute(string key, string rawValue)
    {
        // parse the window and check the current time
    }
}

🌐 Dynamic providers

ToggleProviderBuffer — the one required piece

Everything in the provider pipeline flows through one object. Create it once at startup and pass it to every provider you use:

var buffer = new ToggleProviderBuffer();

The buffer reads FlushInterval from appsettings.json automatically, serialises all file writes so providers never race each other, and performs atomic replacement (tmp file → replace) so a crash mid-write can never corrupt the file. Call buffer.Dispose() at shutdown to flush any remaining staged changes before the process exits.

Write storms: staging uses a ConcurrentDictionary — rapid successive updates to the same key collapse to the last value before flush. If a write is in progress when the timer fires, that tick is skipped; staged values accumulate for the next tick and are never dropped.

Configuration

{
  "FtrIO": {
    "ReloadOnChange": true,   // mandatory when using providers
    "FlushInterval": 5         // seconds between buffer flushes, default 5
  },
  "Toggles": {
    "SendWelcomeEmail": true
  }
}

HTTP provider

dotnet add package FtrIO.Providers.Http

The endpoint must return a Toggles object at the root — the same shape as appsettings.json:

{ "Toggles": { "SendWelcomeEmail": "true", "NewCheckout": "50%" } }

var buffer = new ToggleProviderBuffer();
new HttpToggleParser("https://flags.example.com/toggles", buffer,
    pollInterval: TimeSpan.FromSeconds(30));

ToggleParserProvider.Configure(new StrategyToggleParser(new PercentageRolloutStrategy()));

Azure App Config provider

dotnet add package FtrIO.Providers.AzureAppConfig

Keys in App Config should be prefixed with FtrIO:Toggles: so FtrIO:Toggles:SendWelcomeEmail maps to toggle key SendWelcomeEmail.

var buffer = new ToggleProviderBuffer();

// Connection string
new AzureAppConfigToggleParser("Endpoint=https://...;Id=...;Secret=...", buffer);

// Managed Identity / DefaultAzureCredential
new AzureAppConfigToggleParser(
    new Uri("https://myconfig.azconfig.io"), new DefaultAzureCredential(), buffer);

// With label filter (e.g. separate staging vs. production values)
new AzureAppConfigToggleParser(connectionString, buffer, label: "production");

Environment variable provider

Set env vars with the default FTRIO__Toggles__ prefix (double-underscore follows .NET config hierarchy conventions):

FTRIO__Toggles__SendWelcomeEmail=true
FTRIO__Toggles__NewCheckout=50%

var buffer = new ToggleProviderBuffer();
new EnvironmentVariableToggleParser(buffer);  // snapshot at startup

// Or re-snapshot periodically (e.g. Docker secrets volumes)
new EnvironmentVariableToggleParser(buffer, pollInterval: TimeSpan.FromMinutes(5));

Full wiring example

// 1. Create the buffer — reads FlushInterval from appsettings.json
var buffer = new ToggleProviderBuffer();

// 2. Start providers — push updates to the buffer in the background
new HttpToggleParser("https://flags.example.com/toggles", buffer);
new EnvironmentVariableToggleParser(buffer);

// 3. Configure the reader — always reads from appsettings.json
ToggleParserProvider.Configure(new StrategyToggleParser(
    new PercentageRolloutStrategy(),
    new BlueGreenStrategy("blue", "blue", "green")
));

// 4. Call sites are completely unchanged
emailService.SendWelcomeEmail();

// 5. Flush remaining staged changes on shutdown
buffer.Dispose();

Multiple providers

Multiple providers writing to the same buffer work independently. Each polls its own source and stages its keys. If two providers update the same key before a flush, the last staged value wins — no coordination required.

CompositeToggleParser

For cases where you want one source to override another at read time without the buffer, CompositeToggleParser chains parsers with first-wins fallthrough:

// Env var overrides appsettings.json — no buffer, direct read fallthrough
ToggleParserProvider.Configure(new CompositeToggleParser(
    new EnvironmentVariableToggleParser(),  // standalone mode — reads on demand
    new ToggleParser()
));

🎮 Manual control

ExecuteMethodIfToggleOn is available when you want explicit control — passing a key name override, gating a lambda, or gating a method you can't decorate:

var toggle = new FeatureToggle<EmailService>(new EmailService());

// Key resolved from method name via [Toggle] attribute
toggle.ExecuteMethodIfToggleOn(svc => svc.SendWelcomeEmail());

// Explicit key override
toggle.ExecuteMethodIfToggleOn(svc => svc.SendWelcomeEmail(), "MyCustomKey");

⚠️ Exceptions

All exceptions live in the ToggleExceptions namespace:

using ToggleExceptions;

try
{
    emailService.SendWelcomeEmail();
}
catch (ToggleDoesNotExistException)
{
    // "SendWelcomeEmail" key is missing from appsettings.json
}
catch (ToggleParsedOutOfRangeException)
{
    // The value isn't true/false/1/0
}

🧩 How the three tools work together

FtrIO is three tools with a single shared contract: appsettings.json is always the source of truth. Each tool has a distinct role — write, gate, audit — and they compose without any coupling between them.

🍞 FtrIO.Toaster

FtrIO.Toaster is a lightweight Docker-hosted web UI for managing FtrIO feature toggles. It lets you view, edit, add, and delete toggles without touching appsettings.json directly. Changes are written through ToggleProviderBuffer — the same flush pipeline your app uses — so updates land in appsettings.json on the next flush interval and are picked up live via ReloadOnChange.

Capabilities

• Boolean on/off toggles
• Percentage rollout controls
• Blue/green deployment switching
• Multi-environment support
• Audit log with timestamps, acting user, old value, and new value

Quick start

The image is published to Docker Hub. Create a compose.yml and run docker compose up -d:

services:
  toaster:
    image: thescottbot/ftrio:latest
    ports:
      - "8000:8000"
    environment:
      APPSETTINGS_PATH: /data/appsettings.json
      APP_NAME: MyApp
      # AUTH_USERNAME: admin
      # AUTH_PASSWORD: secret
    volumes:
      - /path/to/your/appsettings.json:/data/appsettings.json
      - toaster-logs:/log
volumes:
  toaster-logs:

Then open http://localhost:8000. Point the volume mount at the same appsettings.json your app reads — Toaster and your app will stay in sync automatically.

To clone the repo instead (for contributors or self-building the image): git clone https://github.com/FtrOnOff/FtrIO.Toaster && cd FtrIO.Toaster && docker compose up -d.

Configuration

Toaster is configured entirely via environment variables:

Authentication

Toaster supports two authentication modes:

• HTTP Basic Auth — set AUTH_USERNAME and AUTH_PASSWORD. Suitable for development or internal tooling.
• OAuth2 Proxy — place an OAuth2 Proxy in front of the container for SSO with Google, Microsoft, GitHub, GitLab, or any OIDC provider. The acting user's identity is then captured in the audit log.

Audit log

Every change is recorded to /log/changes.log as JSONL (one JSON object per line). Each entry captures:

• Timestamp
• Environment
• Toggle key
• Old value → new value
• Acting user (from Basic Auth or OAuth2 Proxy identity)

How it integrates with FtrIO

Toaster writes toggle values through ToggleProviderBuffer — the same class providers use. This means:

• Writes are atomic (tmp file → replace) — a crash mid-write never corrupts appsettings.json
• Your running app picks up changes via ReloadOnChange with no restart
• The base appsettings.json remains the fallback if Toaster is offline — last known state persists

Point APPSETTINGS_PATH at the same file your app reads — typically via a shared Docker volume — and Toaster and your app stay automatically in sync.

1️⃣2️⃣ FtrIO.onetwo

FtrIO.onetwo is a .NET CLI audit tool. It walks your project's source tree, finds every FtrIO toggle reference, cross-references each against appsettings.json, and outputs a table showing the current state — file and line number included. Because FtrIO always resolves toggle state from appsettings.json at runtime, the tool gives you an instant at-a-glance view of exactly what is enabled or disabled right now without opening a single source file manually.

Installation

dotnet tool install -g FtrIO.onetwo

Available on NuGet.

Usage

FtrIO.onetwo [--source <path>] [--config <path>] [--env <name>] [--markdown <output.md>]

What it detects

Toggle states

Example output

Without --env, each appsettings*.json found is shown as a separate table:

Scanning C:\Projects\MyApp...

── appsettings.json
╭──────────────────┬──────────────────┬──────────┬───────┬───────────────────┬──────╮
│ Toggle Key       │ Method           │ Source   │ State │ File              │ Line │
├──────────────────┼──────────────────┼──────────┼───────┼───────────────────┼──────┤
│ NewCheckoutFlow  │ NewCheckoutFlow  │ [Toggle] │  OFF  │ Services\Order.cs │    9 │
│ SendWelcomeEmail │ SendWelcomeEmail │ [Toggle] │  ON   │ Services\Email.cs │   22 │
╰──────────────────┴──────────────────┴──────────┴───────┴───────────────────┴──────╯
2 toggle(s). 1 ON, 1 OFF, 0 PERCENTAGE, 0 BLUE/GREEN, 0 MISSING.

── Staging  (appsettings.Staging.json)
╭──────────────────┬──────────────────┬────────────┬─────────┬───────────────────┬──────╮
│ Toggle Key       │ Method           │ Source     │  State  │ File              │ Line │
├──────────────────┼──────────────────┼────────────┼─────────┼───────────────────┼──────┤
│ NewCheckoutFlow  │ NewCheckoutFlow  │ [Toggle]   │   50%   │ Services\Order.cs │    9 │
│ PaymentV2        │ PaymentV2        │ [Toggle]   │  BLUE   │ Services\Pay.cs   │    6 │
│ SendWelcomeEmail │ SendWelcomeEmail │ [Toggle]   │   ON    │ Services\Email.cs │   22 │
│ UnknownFeature   │ UnknownFeature   │ ManualCall │ MISSING │ Controllers\Ho... │   42 │
╰──────────────────┴──────────────────┴────────────┴─────────┴───────────────────┴──────╯
4 toggle(s). 1 ON, 0 OFF, 1 PERCENTAGE, 1 BLUE/GREEN, 1 MISSING.

With --env Staging, a single merged table is shown applying the overlay:

FtrIO.onetwo --source C:\Projects\MyApp --env Staging

Multi-environment support

Without --env, FtrIO.onetwo finds every appsettings*.json in the --config directory (defaulting to --source) and renders a separate table for each. The environment name is derived from the filename — appsettings.Staging.json → Staging. Each table header includes the full path so there is no ambiguity.

With --env, the tool applies FtrIO's overlay model: the environment-specific file's values win, and the base appsettings.json fills any gaps — the same resolution logic your app uses at runtime.

Separating source and config paths

In real-world deployments the source tree and the live config files often live in different places — e.g. source on a dev machine and appsettings.json on a build output or server share. Use --config to point at the config location independently:

# Source and config in the same place (default)
FtrIO.onetwo --source C:\Projects\MyApp

# Config lives in the build output, not alongside source
FtrIO.onetwo --source C:\Projects\MyApp --config C:\Projects\MyApp\bin\Debug\net10.0

# Config on a remote share or separate server path
FtrIO.onetwo --source C:\Projects\MyApp --config C:\Server\configs --env Production

Generating a markdown report

FtrIO.onetwo --source C:\Projects\MyApp --config C:\Server\configs --env Production --markdown toggles.md

Writes the same table output to a .md file — useful for including toggle state snapshots in PRs or release notes.

📄 Optional config

Without providers: appsettings.json is entirely optional. If the file is absent, every toggle is treated as on — nothing is gated off. You can ship without a config file and nothing breaks.

With providers: appsettings.json becomes the persistent store that ToggleProviderBuffer writes to and ToggleParser reads from. If the file doesn't exist when the first flush fires, the buffer creates it automatically — so you still don't need to create it manually, but it will exist after the first provider poll. ReloadOnChange: true is mandatory in this mode so ToggleParser picks up each flush.

In both modes: if the file exists but is missing a Toggles key for a specific method, that throws ToggleDoesNotExistException — a present-but-incomplete config is treated as a mistake worth surfacing.