faysilalshareef/feature-flags

Feature Flags — Microsoft.FeatureManagement

Core Principles

• Decouple deployment from release — ship code behind flags, enable when ready
• Gradual rollout — percentage-based filters expose features to a subset of users first
• Kill switch — disable a misbehaving feature instantly without redeployment
• Short-lived by design — every flag should have a planned removal date
• Configuration-driven — flags live in appsettings.json or Azure App Configuration, not in code

When to Use

• Rolling out a new feature incrementally to production users
• A/B testing or canary releases controlled by targeting filters
• Providing an emergency kill switch for risky functionality
• Trunk-based development where incomplete features merge behind gates
• Time-boxed promotions or seasonal functionality with scheduled windows

When NOT to Use

• Permanent application settings — use IOptions<T> and configuration instead
• Environment-specific behavior (dev vs prod) — use environment configuration
• Authorization and access control — use ASP.NET Core policies and claims
• Simple on/off toggles that never change at runtime — use compile-time constants

Key Patterns

NuGet Packages

<PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.*" />
<!-- For Azure App Configuration integration -->
<PackageReference Include="Microsoft.Azure.AppConfiguration.AspNetCore" Version="8.*" />

Feature Flag Names as Constants

namespace {Company}.{Domain}.Infrastructure.Features;

/// <summary>
/// Centralized feature flag names. Every flag must have a removal target date in the summary.
/// </summary>
public static class FeatureFlags
{
    /// <summary>New dashboard UI. Target removal: 2026-Q2.</summary>
    public const string NewDashboard = "NewDashboard";

    /// <summary>Bulk export capability. Target removal: 2026-Q3.</summary>
    public const string BulkExport = "BulkExport";

    /// <summary>AI-powered recommendations. Target removal: 2026-Q2.</summary>
    public const string AiRecommendations = "AiRecommendations";
}

Registration in Program.cs

// Program.cs
builder.Services.AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>()
    .AddFeatureFilter<TimeWindowFilter>()
    .AddFeatureFilter<TargetingFilter>();

IFeatureManager Injection

namespace {Company}.{Domain}.Application.Orders;

public sealed class PlaceOrderHandler(
    IFeatureManager featureManager,
    IOrderRepository orders,
    IRecommendationEngine recommendations,
    ILogger<PlaceOrderHandler> logger)
{
    public async Task<OrderResult> HandleAsync(PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);
        await orders.AddAsync(order, ct);

        if (await featureManager.IsEnabledAsync(FeatureFlags.AiRecommendations))
        {
            logger.LogInformation("AI recommendations enabled for order {OrderId}", order.Id);
            var suggestions = await recommendations.GetSuggestionsAsync(order, ct);
            order.AttachRecommendations(suggestions);
        }

        return new OrderResult(order.Id);
    }
}

[FeatureGate] Attribute on Controllers

namespace {Company}.{Domain}.Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public sealed class ExportController(IExportService exportService) : ControllerBase
{
    [HttpPost("bulk")]
    [FeatureGate(FeatureFlags.BulkExport)]
    public async Task<IActionResult> BulkExportAsync(
        BulkExportRequest request, CancellationToken ct)
    {
        var result = await exportService.ExportAsync(request, ct);
        return Ok(result);
    }
}

[FeatureGate] Attribute on Minimal API Endpoints

// Program.cs — endpoint groups
var export = app.MapGroup("/api/export")
    .AddEndpointFilter<FeatureGateEndpointFilter>();

export.MapPost("/bulk", async (BulkExportRequest request, IExportService service, CancellationToken ct) =>
{
    var result = await service.ExportAsync(request, ct);
    return Results.Ok(result);
});

appsettings.json Configuration

{
  "FeatureManagement": {
    "NewDashboard": true,
    "BulkExport": false,
    "AiRecommendations": {
      "EnabledFor": [
        {
          "Name": "Percentage",
          "Parameters": {
            "Value": 25
          }
        }
      ]
    }
  }
}

Percentage rollout strategy: 10 -> 25 -> 50 -> 100 -> remove the flag.

Time-Window Filter

{
  "FeatureManagement": {
    "HolidayPromotion": {
      "EnabledFor": [
        {
          "Name": "TimeWindow",
          "Parameters": {
            "Start": "2026-12-20T00:00:00Z",
            "End": "2027-01-02T23:59:59Z"
          }
        }
      ]
    }
  }
}

Targeting Filter (User/Group Rollout)

{
  "FeatureManagement": {
    "NewDashboard": {
      "EnabledFor": [
        {
          "Name": "Targeting",
          "Parameters": {
            "Audience": {
              "Users": ["user-123", "user-456"],
              "Groups": [
                {
                  "Name": "BetaTesters",
                  "RolloutPercentage": 100
                },
                {
                  "Name": "InternalStaff",
                  "RolloutPercentage": 50
                }
              ],
              "DefaultRolloutPercentage": 5
            }
          }
        }
      ]
    }
  }
}

Implement ITargetingContextAccessor

namespace {Company}.{Domain}.Infrastructure.Features;

public sealed class HttpTargetingContextAccessor(
    IHttpContextAccessor httpContextAccessor) : ITargetingContextAccessor
{
    public ValueTask<TargetingContext> GetContextAsync()
    {
        var httpContext = httpContextAccessor.HttpContext
            ?? throw new InvalidOperationException("No active HTTP context.");

        var user = httpContext.User;
        var context = new TargetingContext
        {
            UserId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "anonymous",
            Groups = user.FindAll("group").Select(c => c.Value).ToList()
        };

        return ValueTask.FromResult(context);
    }
}

// Register in Program.cs
builder.Services.AddSingleton<ITargetingContextAccessor, HttpTargetingContextAccessor>();

Custom IFeatureFilter

namespace {Company}.{Domain}.Infrastructure.Features;

[FilterAlias("TenantTier")]
public sealed class TenantTierFilter(
    ITenantContext tenantContext) : IFeatureFilter
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        var allowedTiers = context.Parameters
            .GetSection("AllowedTiers")
            .Get<string[]>() ?? [];

        var currentTier = tenantContext.CurrentTenant.Tier;
        return Task.FromResult(allowedTiers.Contains(currentTier, StringComparer.OrdinalIgnoreCase));
    }
}

// Registration
builder.Services.AddFeatureManagement()
    .AddFeatureFilter<TenantTierFilter>();

{
  "FeatureManagement": {
    "AdvancedAnalytics": {
      "EnabledFor": [
        {
          "Name": "TenantTier",
          "Parameters": {
            "AllowedTiers": ["Premium", "Enterprise"]
          }
        }
      ]
    }
  }
}

Azure App Configuration Integration

// Program.cs
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(builder.Configuration.GetConnectionString("AppConfig"))
        .UseFeatureFlags(flagOptions =>
        {
            flagOptions.CacheExpirationInterval = TimeSpan.FromSeconds(30);
            flagOptions.Label = builder.Environment.EnvironmentName;
        });
});

builder.Services.AddAzureAppConfiguration();

// Middleware — must be early in pipeline
var app = builder.Build();
app.UseAzureAppConfiguration();

Feature Flag Cleanup Strategy

namespace {Company}.{Domain}.Infrastructure.Features;

/// <summary>
/// Run as a startup health check. Logs warnings for flags past their removal target.
/// </summary>
public sealed class FeatureFlagAuditService(
    IFeatureManager featureManager,
    ILogger<FeatureFlagAuditService> logger) : IHostedService
{
    private static readonly Dictionary<string, DateOnly> RemovalTargets = new()
    {
        [FeatureFlags.NewDashboard] = new DateOnly(2026, 6, 30),
        [FeatureFlags.BulkExport] = new DateOnly(2026, 9, 30),
        [FeatureFlags.AiRecommendations] = new DateOnly(2026, 6, 30),
    };

    public Task StartAsync(CancellationToken ct)
    {
        var today = DateOnly.FromDateTime(DateTime.UtcNow);

        foreach (var (flag, target) in RemovalTargets)
        {
            if (today > target)
            {
                logger.LogWarning(
                    "Feature flag '{Flag}' passed its removal target of {Target}. Schedule cleanup",
                    flag, target);
            }
        }

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Decision Guide

| Scenario | Use Feature Flag | Use IOptions Config | Use Environment Variable | |---|---|---|---| | Gradual user rollout | Yes | No | No | | Runtime on/off toggle | Yes | Possible | No | | Per-environment behavior | No | Yes | Yes | | Temporary A/B test | Yes | No | No | | Connection strings / secrets | No | No | Yes (Key Vault) | | Permanent business rule | No | Yes | No | | Emergency kill switch | Yes | No | No | | Seasonal / time-boxed feature | Yes (TimeWindow) | No | No |

Anti-Patterns

| Anti-Pattern | Problem | Correct Approach | |---|---|---| | Permanent feature flags | Flag debt accumulates, dead code paths multiply | Set removal target date; audit with FeatureFlagAuditService | | Flag names as magic strings | Typos cause silent failures | Centralize in a static FeatureFlags class with constants | | Nested flag dependencies | Flag A depends on Flag B creates combinatorial complexity | Keep flags independent; compose at the feature level | | Testing only the enabled path | Disabled path rots silently | Test both enabled and disabled paths in every flag scenario | | Flags in domain logic | Domain layer couples to infrastructure | Evaluate flags in application/API layer, pass result to domain | | No flag cleanup process | Codebase fills with obsolete gates | Track removal dates, run audit on startup, add to sprint hygiene | | Using flags for authorization | Security decisions need proper policy enforcement | Use ASP.NET Core authorization policies and claims | | Evaluating flags in tight loops | Repeated evaluation adds latency | Cache the result for the scope of the request |

Detect Existing Patterns

# Find FeatureManagement usage
grep -r "IFeatureManager\|FeatureGate\|FeatureManagement" --include="*.cs" src/

# Find feature flag configuration
grep -r "FeatureManagement" --include="*.json" src/

# Find custom feature filters
grep -r ": IFeatureFilter" --include="*.cs" src/

# Find Azure App Configuration
grep -r "AddAzureAppConfiguration\|UseFeatureFlags" --include="*.cs" src/

Adding to Existing Project

1. Install the NuGet package -- Microsoft.FeatureManagement.AspNetCore
2. Create a FeatureFlags constants class in Infrastructure/Features
3. Register in Program.cs with AddFeatureManagement() and required filters
4. Add flag definitions to appsettings.json under FeatureManagement
5. For targeting, implement ITargetingContextAccessor to resolve user/group context
6. For Azure, add Microsoft.Azure.AppConfiguration.AspNetCore and configure refresh
7. Set removal targets for every flag and wire up the audit hosted service
8. Test both paths -- verify behavior when flag is enabled and disabled