Quick Start

Integrate FeatureFlags.app into your ASP.NET Core application in minutes. Requires ASP.NET Core on .NET 10 or later.

Prerequisites

An ASP.NET Core application on .NET 10 or later.
An API key (create one in the FeatureFlags web UI).

Step 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:

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

Step 2: Configure the Client

Add the FeatureFlags configuration to your 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. Flag changes reach your app within this interval. Use a shorter interval for apps that rely on kill-switch flags.

Security Best Practice

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

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

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

Step 3: Register the Services

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

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.

Step 4: Use Feature Flags

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

In Controllers

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

@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:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

<feature name="NewFeature">
    <p>This content shows when NewFeature is enabled.</p>
</feature>

Step 5: Create Feature Flags

Log in to FeatureFlags.app.
Navigate to the Feature Flags page.
Click "Create New" and give your flag a meaningful name (e.g., "NewFeature").
Toggle the enabled state as needed.
Configure optional filters for advanced scenarios (rollout percentage, user targeting, 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 using a percentage filter that will assign users consistently.

User Targeting

Enable features for specific users - use User.Identity.Name for matching users.