EnumCraft.FeatureFlags 1.0.1

EnumCraft.FeatureFlags

Strongly-typed, provider-based feature flags built on EnumCraft.Core.

Overview

EnumCraft.FeatureFlags provides a clean, extensible feature flag abstraction for .NET applications. Define your own strongly-typed flag catalog, plug in a data provider, and get type-safe flag resolution with per-tenant override support.

This package is part of the EnumCraft ecosystem:

Installation

dotnet add package EnumCraft.FeatureFlags
dotnet add package EnumCraft.FeatureFlags.Json

Requirements

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

Quick Start

1. Define your flag type

Each application defines its own concrete flag type. Each type has its own isolated provider, snapshot, and catalog.

using EnumCraft.FeatureFlags;

public sealed class AppFeatureFlag : FeatureFlag<AppFeatureFlag>
{
  public static readonly AppFeatureFlag DarkMode = new( Guid.Parse("6255cf3c-2a18-4082-87f0-764bf76cc0f9"),
                                                        "Dark Mode",
                                                        nameof(DarkMode),
                                                        isActiveDefault: false );
  
  public static readonly AppFeatureFlag NewDashboard = new( Guid.Parse("c473d35a-c391-444b-86a7-4aac8319db4e"),
                                                            "New Dashboard",
                                                            nameof(NewDashboard),
                                                            isActiveDefault: false );
  
  public static readonly AppFeatureFlag BetaReporting = new( Guid.Parse("c74e06d8-1b6d-4614-8218-facb10da1ca6"),
                                                             "Beta Reporting",
                                                             nameof(BetaReporting),
                                                             isActiveDefault: false );
  
  public static readonly AppFeatureFlag MaintenanceMode = new( Guid.Parse("aeba8047-b728-4e5b-8d66-f74f44a4bc76"),
                                                               "Maintenance Mode",
                                                               nameof(MaintenanceMode),
                                                               isActiveDefault: false );

  private AppFeatureFlag(Guid id, string description, string code, bool isActiveDefault = false)
    : base(id, description, code, isActiveDefault) { }
}

2. Configure at startup

Use Configure() to fail fast if the provider cannot initialize, or TryConfigure() for a safe wrapper that returns false with an error message instead of throwing an exception.

using EnumCraft.FeatureFlags.Json;

var options = new JsonFeatureFlagProviderOptions { DirectoryPath = AppDomain.CurrentDomain.BaseDirectory,
                                                   FileName      = "AppFeatureFlag.json" };

// Fail-fast — throws exception if provider fails to initialize
AppFeatureFlag.Configure(new JsonFeatureFlagProvider(options));

// — or — safe wrapper
if(!AppFeatureFlag.TryConfigure(new JsonFeatureFlagProvider(options), out var error))
{
  Console.WriteLine($"Failed to configure flags: {error}");
  return;
}

Configure() may only be called once per flag type. Calling it a second time throws InvalidOperationException. Use TryConfigure() if you need to handle the already-configured case gracefully without an exception. Runtime provider swapping via Reconfigure() is not supported in v1.0.0 - a restart is required to change providers.

3. Use anywhere

// Global resolution
if(AppFeatureFlag.DarkMode.IsActive)
{
  // enabled globally
}

// Per-tenant resolution (string tenant ID)
if(AppFeatureFlag.DarkMode["tenant-123"])
{
  // enabled for this tenant
}

// Per-tenant resolution (int tenant ID)
if(AppFeatureFlag.DarkMode[1001])
{
  // enabled for this tenant
}

// Full resolution chain (for diagnostics)
var resolution = AppFeatureFlag.DarkMode.Resolve(tenantId);
foreach(var r in resolution)
{
  Console.WriteLine($"[{r.Priority}] {r.Source} → {r.Value}");
}

Resolution Order

For any flag lookup, the resolution priority is:

1. Tenant override — per-tenant value from provider data, if present
2. Global override — global value from provider data, if present
3. Constructor default — isActiveDefault parameter value

FeatureFlagResolution

Resolve() returns IReadOnlyList<FeatureFlagResolution> - one entry per resolution source that participated. Each entry exposes the following.

FeatureFlagValueSource

Optional Logging

Set a logger on the flag type for diagnostic output. Falls back to NullLogger if not set.

using Microsoft.Extensions.Logging;

var logger = loggerFactory.CreateLogger<AppFeatureFlag>();
AppFeatureFlag.SetLogger(logger);

Implementing a Custom Provider

Implement IFeatureFlagProvider to load flag data from any source:

public class MyCustomProvider : IFeatureFlagProvider
{
  public event EventHandler? Changed;

  public bool Initialize(out string? error)
  {
    // load your data
    error = null;
    return true;
  }

  public FeatureFlagData GetSnapshot()
  {
    // return current data
    return new FeatureFlagData();
  }

  public void Dispose() { }
}

IFeatureFlagProvider extends IDisposable - providers own their lifecycle and must clean up any watchers, timers, or connections in Dispose().

Framework Support

Related Packages

• EnumCraft.Core — Type-safe enumerations and flags
• EnumCraft.Json — JSON serialization extensions for TypedEnum and TypedFlag
• EnumCraft.FeatureFlags.Json — JSON file provider for feature flags

License

MIT — see LICENSE for details.

Author

Randel Bjorkquist — GitHub | NuGet