klod68/feature-flag-management

---

name: feature-flag-management description: "Use when implementing feature flags for trunk-based development with incomplete features behind toggles, progressive rollouts (canary, percentage, time-window), per-tenant feature sets, optional AI or premium features, or kill switches that disable production features without redeployment. Covers Microsoft.FeatureManagement, IFeatureManager, built-in and custom feature filters, endpoint and middleware gating, feature flag constants, and flag lifecycle management from creation through removal. Domain: Release Management, Configuration, Progressive Delivery. Level: Intermediate. Tags: feature-flags, feature-management, feature-toggles, progressive-delivery, canary."

Feature Flag Management

Problem

Without feature flags:

• Incomplete features block the entire release — long-lived feature branches accumulate merge conflicts
• Rollback requires a full redeployment instead of a configuration change
• A/B testing and canary releases require separate infrastructure
• Optional features (AI, premium) can't be toggled without code changes
• "Feature toggles" are hand-rolled with ad-hoc if checks and boolean config values

Solution: Microsoft.FeatureManagement

Use the Microsoft.FeatureManagement library for structured feature flag evaluation with built-in filters, DI integration, and ASP.NET middleware support.

Implementation

Tier 1: Simple Boolean Flags

Configuration

// appsettings.json
{
  "FeatureManagement": {
    "AiChatbot": true,
    "NewCheckoutFlow": false,
    "BetaDashboard": true
  }
}

Registration

builder.Services.AddFeatureManagement();

Usage in Code

public class OrderService
{
    private readonly IFeatureManager _featureManager;

    public async Task<OrderResult> PlaceOrderAsync(Order order, CancellationToken ct)
    {
        if (await _featureManager.IsEnabledAsync("NewCheckoutFlow"))
        {
            return await ProcessWithNewFlowAsync(order, ct);
        }

        return await ProcessWithLegacyFlowAsync(order, ct);
    }
}

Usage in Razor / Blazor

<feature name="BetaDashboard">
    <div class="beta-dashboard">
        <!-- Only rendered when flag is enabled -->
    </div>
</feature>

Tier 2: Feature Filters (Conditional Activation)

Percentage Rollout

{
  "FeatureManagement": {
    "NewCheckoutFlow": {
      "EnabledFor": [
        {
          "Name": "Percentage",
          "Parameters": { "Value": 25 }
        }
      ]
    }
  }
}

Time Window

{
  "FeatureManagement": {
    "HolidayBanner": {
      "EnabledFor": [
        {
          "Name": "TimeWindow",
          "Parameters": {
            "Start": "2026-12-20T00:00:00Z",
            "End": "2026-12-31T23:59:59Z"
          }
        }
      ]
    }
  }
}

Targeting (Specific Users/Groups)

builder.Services.AddFeatureManagement()
    .WithTargeting();

// Register targeting context accessor
builder.Services.AddSingleton<ITargetingContextAccessor, HttpContextTargetingContextAccessor>();

{
  "FeatureManagement": {
    "BetaDashboard": {
      "EnabledFor": [
        {
          "Name": "Targeting",
          "Parameters": {
            "Audience": {
              "Users": ["[email protected]", "[email protected]"],
              "Groups": [
                { "Name": "BetaTesters", "RolloutPercentage": 100 },
                { "Name": "InternalUsers", "RolloutPercentage": 50 }
              ],
              "DefaultRolloutPercentage": 0
            }
          }
        }
      ]
    }
  }
}

Tier 3: Custom Feature Filter

[FilterAlias("TenantFilter")]
public class TenantFeatureFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public TenantFeatureFilter(IHttpContextAccessor httpContextAccessor)
        => _httpContextAccessor = httpContextAccessor;

    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        var settings = context.Parameters.Get<TenantFilterSettings>();
        var tenantId = _httpContextAccessor.HttpContext?.User
            .FindFirst("tenant_id")?.Value;

        return Task.FromResult(
            settings?.AllowedTenants?.Contains(tenantId ?? "") == true);
    }
}

public class TenantFilterSettings
{
    public string[] AllowedTenants { get; set; } = [];
}

Feature Flag Constants

/// <summary>
/// Centralized feature flag names — prevents typos and enables Find All References.
/// </summary>
public static class FeatureFlags
{
    public const string AiChatbot = "AiChatbot";
    public const string NewCheckoutFlow = "NewCheckoutFlow";
    public const string BetaDashboard = "BetaDashboard";
    public const string HolidayBanner = "HolidayBanner";
}

Endpoint / Controller Gating

// Minimal API
app.MapGet("/beta/dashboard", DashboardHandler.Get)
    .WithMetadata(new FeatureGateAttribute(FeatureFlags.BetaDashboard));

// MVC Controller
[FeatureGate(FeatureFlags.BetaDashboard)]
public class BetaDashboardController : Controller { }

Middleware Gating

app.UseForFeature(FeatureFlags.AiChatbot, appBuilder =>
{
    appBuilder.UseMiddleware<AiChatbotMiddleware>();
});

Feature Flag Lifecycle

| Phase | Action | |-------|--------| | Create | Add flag to config (disabled), add FeatureFlags constant | | Develop | Code behind IsEnabledAsync check, merge to main | | Test | Enable in staging, verify behavior | | Rollout | Enable with percentage filter (10% → 50% → 100%) | | Stabilize | Monitor metrics, confirm no regressions | | Remove | Remove flag check from code, remove config entry, clean up constant |

When to Use

• Trunk-based development: merge incomplete features behind flags instead of long-lived branches.
• Progressive delivery: canary releases, percentage rollouts, A/B testing.
• Optional features: AI integrations, premium features, experimental UI.
• Kill switches: instantly disable a feature in production without redeployment.
• Per-tenant features: SaaS applications with different feature sets per customer.

When NOT to Use

• Permanent business logic branching — use strategy pattern or configuration, not feature flags.
• Security controls — authorization policies, not feature flags, control access to sensitive operations.
• Simple configuration values — a feature flag is binary (on/off); use IOptions<T> for parameterized config.

Gotchas

1. Flag rot: Old flags accumulate. Track every flag with a cleanup date. After 100% rollout and stabilization, remove the flag from code AND config.
2. Testing both paths: Every flag creates a testing matrix. Ensure both enabled and disabled paths are tested. Use IFeatureManager mocking in unit tests.
3. Stale evaluation: IFeatureManager evaluates against the current configuration. If config is cached, flag changes take effect after cache refresh. Use IConfiguration.GetReloadToken() for dynamic reload.
4. Missing fallback: If IsEnabledAsync is called with an undefined flag name, it returns false by default. This is safe but can hide typos — use FeatureFlags constants.
5. Flag dependencies: If flag B depends on flag A being enabled, document the dependency. Consider combining into a single flag or using a composite filter.

Related Skills

• Embedded Resource Configuration (configuration source for flag values)
• Three-Tier Configuration Precedence (config source for flag values)
• Semantic Versioning with Changelog (document flag additions/removals in changelog)