Feature flags in appsettings.json are a perfectly reasonable place to start. You add a flag, check it with IFeatureManager, and get on with building software. Nice and simple.
Then someone asks you to turn a feature off in production. Suddenly, changing one little Boolean means editing a configuration file, running a deployment pipeline, and waiting for everything to finish. And naturally, this happens at 4:55 on a Friday.
Maybe it's time to move those flags somewhere a little more convenient. The good news? If you're already using Microsoft's Microsoft.FeatureManagement library, you don't need to rewrite all the code that checks your flags.
What changes (and what doesn't)
When moving flags out of appsettings.json, the goal is to change the source of your feature definitions, not how your application uses them. These familiar bits can stay:
IFeatureManagerIFeatureManagerSnapshot[FeatureGate]- The
<feature>tag helper - Microsoft's built-in feature filters
What changes is where the definitions come from. You'll add a client package, register a different provider, and configure its connection. Let's walk through it.
Step 1: Take inventory
Before moving anything, take a look at your FeatureManagement section.
Make a list of:
- Every feature flag and its name.
- Whether it's enabled or disabled.
- Any filters attached to it.
- Any custom filters your application implements.
Pay particular attention to targeting rules, percentage rollouts, and time windows. You'll want to recreate those accurately. Custom filters can come along too, provided your application still implements the corresponding filter classes.
Step 2: Create your flags in the new location
Create the appropriate environments first — development, staging, production, or whatever your setup requires. Then recreate your flags with the same names and filters. Keep those names identical to what your code expects. A typo here is a fun way to spend an afternoon wondering why a feature is disabled. You can also import flags from the feature_management section of your existing appsettings.json, rather than recreating everything manually.
Important: Do this before deploying the application changes. You don't want to switch providers before the flags exist in their new home.
Step 3: Create an API key
Your application needs a way to retrieve its flag definitions. Create an API key for each environment. Each key reads the flags belonging to that environment, keeping development flags out of production. Don't put API keys in source control. For local development, use user secrets:
dotnet user-secrets set "FeatureFlags:ApiKey" "your-api-key-here"
For production, use environment variables or your hosting platform's secrets management.
Step 4: Swap the registration
Install the client package:
dotnet add package Acmi.FeatureFlags.Client
Then replace your existing registration:
// Before
builder.Services.AddFeatureManagement();
// After
using Acmi.FeatureFlags.Client;
builder.AddFeatureFlags();
Notice the difference? You're replacing AddFeatureManagement() with AddFeatureFlags(). Don't call both. AddFeatureFlags() already registers Microsoft's feature management services. Calling both registrations causes the application to fail at startup with a FeatureManagementException. Add the connection settings to appsettings.json:
{
"FeatureFlags": {
"ApiBaseEndpoint": "https://featureflags.app/api/",
"ApiKey": "[from secrets]"
}
}
And that's pretty much the code change.
One important gotcha: Once the new provider is registered, the old local FeatureManagement section is no longer used. Any flag that exists only in appsettings.json will evaluate as off. Check your flags using the dashboard's Evaluate page before deploying. Once everything is verified, remove the old section.
Step 5: Understand the failure modes
Before declaring victory, understand what happens when the flag service isn't available.
The client:
- Fetches definitions when your application starts.
- Refreshes them every 15 minutes by default.
- Keeps the last successfully fetched definitions if a later refresh fails.
- Retries failed refreshes in the background.
If the service is unavailable when the application first starts, there's no previous copy to fall back on. Flags evaluate as off until the first successful fetch. If you're using flags as kill switches, consider reducing the refresh interval with CacheExpirationInMinutes.
No system is magic. Know what happens when the network gets grumpy.
What if you want to move back?
Good news: you're not locked in.
You can export an environment's flags as standard Microsoft.FeatureManagement JSON and put them back into appsettings.json.
Then switch the registration back:
builder.Services.AddFeatureManagement().WithTargeting();
The .WithTargeting() call is important if you're using percentage rollouts, since those export as Microsoft's Targeting filter. Custom filters are exported as-is, so your application still needs their implementations. Your feature-checking code doesn't need to know anything changed.
The takeaway
Moving feature flags out of appsettings.json isn't about changing how you write application code. It's about changing how you manage releases. You can keep using Microsoft's familiar feature management APIs while gaining a more convenient way to manage flags across environments.
And if you'd rather not build and maintain your own flag dashboard, FeatureFlags.app provides one that works with Microsoft.FeatureManagement — without requiring Azure App Configuration.
The best migration is the one where nobody notices anything changed. Except the Friday-afternoon you.
Top comments (0)