EnumCraft.FeatureFlags.Json 0.2.1-preview

EnumCraft.FeatureFlags.Json

JSON file provider for EnumCraft.FeatureFlags.

Overview

EnumCraft.FeatureFlags.Json is the JSON file-based data provider for the EnumCraft feature flag system. It loads feature flag configuration from a JSON file, supports per-tenant overrides, and automatically reloads when the file changes — using a FileSystemWatcher with a polling fallback for reliability.

This package is part of the EnumCraft ecosystem:

Status

⚠️ This package is currently in preview. API surface is not yet stable and may change before v1.0.0.

Installation

dotnet add package EnumCraft.FeatureFlags.Json

Requirements

• .NET Standard 2.0+ or .NET 8.0+
• EnumCraft.FeatureFlags
• EnumCraft.Core

Quick Start

using EnumCraft.FeatureFlags.Json;

var options = new JsonFeatureFlagProviderOptions
{
  DirectoryPath = AppDomain.CurrentDomain.BaseDirectory,
  FileName      = "AppFeatureFlag.json"   // name it to match your derived type
};

var provider = new JsonFeatureFlagProvider(options);

if(!AppFeatureFlag.TryConfigure(provider, out var error))
{
  Console.WriteLine($"Failed to configure flags: {error}");
  return;
}

Configuration Options

FullPath is computed automatically from DirectoryPath + FileName.

JSON File Format

Name your JSON file to match your derived flag type (e.g., AppFeatureFlag.json).

{
  "global": {
    "DarkMode":        true,
    "NewDashboard":    true,
    "BetaReporting":   false,
    "MaintenanceMode": false
  },
  "tenants": {
    "1001": {
      "DarkMode":     false,
      "NewDashboard": false
    },
    "1002": {
      "BetaReporting": true
    }
  }
}

Resolution Order

1. Tenant override — per-tenant value, if present
2. Global override — global value from JSON, if present
3. Default — constructor-defined fallback (isActiveDefault)

Auto-Reload Behavior

When EnableAutoReload is true (the default):

• A FileSystemWatcher monitors the JSON file for changes
• A polling timer runs as a fallback safety net
• On successful reload, the Changed event is raised
• On failed reload (malformed JSON, IO error), the previous snapshot is retained — no partial reads
• The watcher is automatically recreated if it encounters a buffer overflow error

Disposal

JsonFeatureFlagProvider implements IDisposable. At application shutdown, dispose the provider to stop the watcher and polling timer cleanly:

provider.Dispose();

License

MIT — see LICENSE for details.

Author

Randel Bjorkquist