Quick Start

Integrate FeatureFlags.app into your ASP.NET Core application in minutes.

Requires ASP.NET Core on .NET 10 or later 5 steps

Prerequisites

An ASP.NET Core application on .NET 10 or later.

An API key (create one in the FeatureFlags web UI).

  1. 1

    Install the Client Package

    Add the Acmi.FeatureFlags.Client NuGet package to your project:

    dotnet add package Acmi.FeatureFlags.Client

    Or add it directly to your .csproj file:

    MyApp.csproj
    <PackageReference Include="Acmi.FeatureFlags.Client" Version="x.y.z" />
  2. 2

    Configure the Client

    Add the FeatureFlags configuration to your appsettings.json:

    appsettings.json
    {
      "FeatureFlags": {
        "ApiBaseEndpoint": "https://featureflags.app/api/",
        "ApiKey": "[your-api-key]",
        "CacheExpirationInMinutes": 15
      }
    }

    Configuration Options

    ApiBaseEndpoint
    The base URL of the FeatureFlags.app API. Must end with /api/ (including the trailing slash).
    ApiKey
    Your API key created in the FeatureFlags.app web UI. Store this securely using user secrets or environment variables—never commit it to source control.
    CacheExpirationInMinutes
    How often the client refreshes flag definitions in the background. Default is 15 minutes, and the minimum is 1; a lower value stops the app at startup with an error. Flag changes reach your app within this interval. Use a shorter interval, down to 1, for apps that rely on kill-switch flags. A refresh that finds no changes gets an empty 304 Not Modified response.

    Security Best Practice

    For local development, use dotnet user-secrets to store your API key:

    Terminal
    dotnet user-secrets set "FeatureFlags:ApiKey" "your-api-key-here"

    For production, use environment variables or your cloud provider's secrets management service.

  3. 3

    Register the Services

    In your Program.cs, add the FeatureFlags services using the extension method:

    Program.cs
    using Acmi.FeatureFlags.Client;
    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add FeatureFlags services
    builder.AddFeatureFlags();
    
    // ... rest of your configuration
    
    var app = builder.Build();
    await app.RunAsync();

    That's it! The extension method registers all necessary services including the client, feature definition provider, and Microsoft's feature management services.

  4. 4

    Use Feature Flags

    Once configured, you can use feature flags throughout your application using Microsoft's IFeatureManager.

    In Controllers

    MyController.cs
    public class MyController : Controller
    {
        private readonly IFeatureManager _manager;
    
        public MyController(IFeatureManager featureManager)
        {
            _manager = featureManager;
        }
    
        public async Task<IActionResult> Index()
        {
            if (await _manager.IsEnabledAsync("IndexFeature"))
            {
                // New feature code
            }
            else
            {
                // Legacy code
            }
    
            return View();
        }
    
        [FeatureGate("NewIndexFeature")]
        public async Task<IActionResult> NewIndex()
        {
            return View();
        }
    }

    In Views

    Index.cshtml
    @inject IFeatureManager Manager
    
    <h1>My Page</h1>
    
    @if (await Manager.IsEnabledAsync("NewFeature"))
    {
        <div>
            <p>This is the new feature!</p>
        </div>
    }
    else
    {
        <div>
            <p>This is the legacy feature.</p>
        </div>
    }

    Using the Feature Tag Helper

    Microsoft provides a tag helper for cleaner view syntax:

    Index.cshtml
    @addTagHelper *, Microsoft.FeatureManagement.AspNetCore
    
    <feature name="NewFeature">
        <p>This content shows when NewFeature is enabled.</p>
    </feature>
  5. 5

    Create Feature Flags

    1. Log in to FeatureFlags.app.
    2. Navigate to the Feature Flags page.
    3. Click "Create New" and give your flag a meaningful name (e.g., "NewFeature").
    4. Toggle the enabled state as needed.
    5. Configure optional filters for advanced scenarios (user and group targeting, rollout percentages, time windows).

    Changes reach your application within your refresh interval (CacheExpirationInMinutes, 15 minutes by default). Use a shorter interval for apps that rely on kill-switch flags.

Advanced Features

Rollout Percentage

Gradually roll out features to a percentage of users by setting a targeting filter's rollout percentage. Each user stays in or out of the rollout, so they see the same behavior on every request.

User Targeting

Enable features for specific users or groups, and exclude others. Users are matched on User.Identity.Name, and groups come from the user's role claims by default.

Time Windows

Schedule features to enable or disable at specific times, including recurrence.

Custom Filters

Implement your own more complex filters using JSON.

Additional Resources