ASP.NET Core Feature Flags

Feature flags provide a way for ASP.NET Core applications to turn features on or off dynamically. Developers can use feature flags in simple use cases like conditional statements to more advanced scenarios like conditionally adding routes or MVC filters. Feature flags build on top of the .NET Core configuration system. Any .NET Core configuration provider is capable of acting as the back-bone for feature flags.

Here are some of the benefits of using this library:

• A common convention for feature management
• Low barrier-to-entry
  • Built on

    IConfiguration

  • Supports JSON file feature flag setup
• Feature Flag lifetime management
  • Configuration values can change in real-time, feature flags can be consistent across the entire request
• Simple to Complex Scenarios Covered
  • Toggle on/off features through declarative configuration file
  • Dynamically evaluate state of feature based on call to server
• API extensions for ASP.NET Core and MVC framework
  • Routing
  • Filters
  • Action Attributes

API Reference: https://go.microsoft.com/fwlink/?linkid=2091700

Feature Flags

Feature flags are composed of two parts, a name and a list of feature-filters that are used to turn the feature on.

Feature Filters

Feature filters define a scenario for when a feature should be enabled. When a feature is evaluated for whether it is on or off, its list of feature-filters are traversed until one of the filters decides the feature should be enabled. At this point the feature is considered enabled and traversal through the feature filters stops. If no feature filter indicates that the feature should be enabled, then it will be considered disabled.

As an example, a Microsoft Edge browser feature filter could be designed. This feature filter would activate any features it is attached to as long as an HTTP request is coming from Microsoft Edge.

Registration

The .NET Core configuration system is used to determine the state of feature flags. The foundation of this system is

IConfiguration

Feature Flag Declaration

The feature management library supports appsettings.json as a feature flag source since it is a provider for .NET Core's IConfiguration system. Below we have an example of the format used to set up feature flags in a json file.

{
    "Logging": {
        "LogLevel": {
            "Default": "Warning"
        }
    },

// Define feature flags in a json file
"FeatureManagement": {
    "FeatureT": {
        "EnabledFor": [
            {
                "Name": "AlwaysOn"
            }
        ]
    },
    "FeatureU": {
        "EnabledFor": []
    },
    "FeatureV": {
        "EnabledFor": [
            {
                "Name": "TimeWindow",
                "Parameters": {
                    "Start": "Wed, 01 May 2019 13:59:59 GMT",
                    "End": "Mon, 01 July 2019 00:00:00 GMT"
                }
            }
        ]
    }
}
}

The

FeatureManagement

EnabledFor

FeatureT

AlwaysOn

AlwaysOn

FeatureU

EnabledFor

FeatureV

TimeWindow

On/Off Declaration

The following snippet demonstrates an alternative way to define a feature that can be used for on/off features. ``` JavaScript { "Logging": { "LogLevel": { "Default": "Warning" } },

// Define feature flags in config file
"FeatureManagement": {
    "FeatureT": true, // On feature
    "FeatureX": false // Off feature
}

} ```

Referencing

To make it easier to reference these feature flags in code, we recommend to define feature flag variables like below.

// Define feature flags in an enum
public enum MyFeatureFlags
{
    FeatureT,
    FeatureU,
    FeatureV
}

Service Registration

Feature flags rely on .NET Core dependency injection. We can register the feature management services using standard conventions.

using Microsoft.FeatureManagement;
using Microsoft.FeatureManagement.FeatureFilters;

public class Startup
{
  public void ConfigureServices(IServiceCollection services)
  {
      services.AddFeatureManagement()
              .AddFeatureFilter()
              .AddFeatureFilter();
  }
}

This tells the feature manager to use the "FeatureManagement" section from the configuration for feature flag settings. It also registers two built-in feature filters named

PercentageFilter

TimeWindowFilter

Advanced: The feature manager looks for feature definitions in a configuration section named "FeatureManagement". If the "FeatureManagement" section does not exist, it falls back to the root of the provided configuration.

Consumption

The simplest use case for feature flags is to do a conditional check for whether a feature is enabled to take different paths in code. The uses cases grow from there as the feature flag API begins to offer extensions into ASP.NET Core.

Feature Check

The basic form of feature management is checking if a feature is enabled and then performing actions based on the result. This is done through the

IFeatureManager

IsEnabledAsync

…
IFeatureManager featureManager;
…
if (await featureManager.IsEnabledAsync(nameof(MyFeatureFlags.FeatureU)))
{
    // Do something
}

Dependency Injection

When using the feature management library with MVC, the

IFeatureManager

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

public HomeController(IFeatureManager featureManager)
{
    _featureManager = featureManager;
}
}

Controllers and Actions

MVC controller and actions can require that a given feature, or one of any list of features, be enabled in order to execute. This can be done by using a

FeatureGateAttribute

Microsoft.FeatureManagement.Mvc

[FeatureGate(MyFeatureFlags.FeatureX)]
public class HomeController : Controller
{
    …
}

The

HomeController

HomeController

[FeatureGate(MyFeatureFlags.FeatureY)]
public IActionResult Index()
{
    return View();
}

The

Index

Disabled Action Handling

When an MVC controller or action is blocked because none of the features it specifies are enabled, a registered

IDisabledFeaturesHandler

IFeatureManagementBuilder

public interface IDisabledFeaturesHandler
{
    Task HandleDisabledFeature(IEnumerable features, ActionExecutingContext context);
}

View

In MVC views

  
This can only be seen if 'FeatureX' is enabled.

The

HTML+Razor
@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

MVC Filters

MVC action filters can be set up to conditionally execute based on the state of a feature. This is done by registering MVC filters in a feature aware manner. The feature management pipeline supports async MVC Action filters, which implement

IAsyncActionFilter

services.AddMvc(o => 
{
    o.Filters.AddForFeature(nameof(MyFeatureFlags.FeatureV));
});

The code above adds an MVC filter named

SomeMvcFilter

Application building

The feature management library can be used to add application branches and middleware that execute conditionally based on feature state.

app.UseMiddlewareForFeature(nameof(MyFeatureFlags.FeatureU));

With the above call, the application adds a middleware component that only appears in the request pipeline if the feature "FeatureU" is enabled. If the feature is enabled/disabled during runtime, the middleware pipeline can be changed dynamically.

This builds off the more generic capability to branch the entire application based on a feature.

app.UseForFeature(featureName, appBuilder => 
{
    appBuilder.UseMiddleware();
});

Implementing a Feature Filter

Creating a feature filter provides a way to enable features based on criteria that you define. To implement a feature filter, the

IFeatureFilter

IFeatureFilter

EvaluateAsync

EvaluateAsync

EvaluateAsync

true

Feature filters are registered by the

IFeatureManagementBuilder

AddFeatureManagement

Parameterized Feature Filters

Some feature filters require parameters to decide whether a feature should be turned on or not. For example a browser feature filter may turn on a feature for a certain set of browsers. It may be desired that Edge and Chrome browsers enable a feature, while Firefox does not. To do this a feature filter can be designed to expect parameters. These parameters would be specified in the feature configuration, and in code would be accessible via the

FeatureFilterEvaluationContext

IFeatureFilter.EvaluateAsync

public class FeatureFilterEvaluationContext
{
    /// 

    /// The name of the feature being evaluated.
    /// 
    public string FeatureName { get; set; }

/// <summary>
/// The settings provided for the feature filter to use when evaluating whether the feature should be enabled.
/// </summary>
public IConfiguration Parameters { get; set; }
}

FeatureFilterEvaluationContext

Parameters

Parameters

[FilterAlias("Browser")]
public class BrowserFilter : IFeatureFilter
{
    … Removed for example

public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
{
    BrowserFilterSettings settings = context.Parameters.Get<browserfiltersettings>() ?? new BrowserFilterSettings();

    //
    // Here we would use the settings and see if the request was sent from any of BrowserFilterSettings.AllowedBrowsers
}
}

Filter Alias Attribute

When a feature filter is registered to be used for a feature flag, the alias used in configuration is the name of the feature filter type with the filter suffix, if any, removed. For example

MyCriteriaFilter

"MyFeature": {
    "EnabledFor": [
        {
            "Name": "MyCriteria"
        }
    ]
}

This can be overridden through the use of the

FilterAliasAttribute

Missing Feature Filters

If a feature is configured to be enabled for a specific feature filter and that feature filter hasn't been registered, then an exception will be thrown when the feature is evaluated. The exception can be disabled by using the feature management options.

services.Configure(options =>
{
    options.IgnoreMissingFeatureFilters = true;
});

Using HttpContext

Feature filters can evaluate whether a feature should be enabled based off the properties of an HTTP Request. This is performed by inspecting the HTTP Context. A feature filter can get a reference to the HTTP Context by obtaining an

IHttpContextAccessor

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

public BrowserFilter(IHttpContextAccessor httpContextAccessor)
{
    _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
}
}

The

IHttpContextAccessor

IServiceCollection

public void ConfigureServices(IServiceCollection services)
{
    …
    services.TryAddSingleton();
    …
}

Providing a Context For Feature Evaluation

In console applications there is no ambient context such as

HttpContext

IFeatureManager.IsEnabledAsync(string featureName, TContext appContext)

MyAppContext context = new MyAppContext
{
    AccountId = current.Id;
}

if (await featureManager.IsEnabledAsync(feature, context))
{
…
}

Contextual Feature Filters

Contextual feature filters implement the

IContextualFeatureFilter

IFeatureManager.IsEnabledAsync

TContext

IContextualFeatureFilter

IContextualFeatureFilter

public interface IAccountContext
{
    string AccountId { get; set; }
}

[FilterAlias("AccountId")]
class AccountIdFilter : IContextualFeatureFilter
{
    public Task EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountId)
    {
        //
        // Evaluate if the feature should be on with the help of the provided IAccountContext
    }
}

We can see that the

AccountIdFilter

IAccountContext

IAccountContext

Note: Only a single feature filter interface can be implemented by a single type. Trying to add a feature filter that implements more than a single feature filter interface will result in an

ArgumentException

Built-In Feature Filters

There a few feature filters that come with the

Microsoft.FeatureManagement

Each of the built-in feature filters have their own parameters. Here is the list of feature filters along with examples.

Microsoft.Percentage

This filter provides the capability to enable a feature based on a set percentage.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "Name": "Microsoft.Percentage",
            "Parameters": {
                "Value": 50
            }
        }
    ]
}

Microsoft.TimeWindow

This filter provides the capability to enable a feature based on a time window. If only

End

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "Name": "Microsoft.TimeWindow",
            "Parameters": {
                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                "End": "Mon, 01 July 2019 00:00:00 GMT"
            }
        }
    ]
}

Microsoft.Targeting

This filter provides the capability to enable a feature for a target audience. An in-depth explanation of targeting is explained in the targeting section below. The filter parameters include an audience object which describes users, groups, and a default percentage of the user base that should have access to the feature. Each group object that is listed in the target audience must also specify what percentage of the group's members should have access. If a user is specified in the users section directly, or if the user is in the included percentage of any of the group rollouts, or if the user falls into the default rollout percentage then that user will have the feature enabled.

"EnhancedPipeline": {
    "EnabledFor": [
        {
            "Name": "Microsoft.Targeting",
            "Parameters": {
                "Audience": {
                    "Users": [
                        "Jeff",
                        "Alicia"
                    ],
                    "Groups": [
                        {
                            "Name": "Ring0",
                            "RolloutPercentage": 100
                        },
                        {
                            "Name": "Ring1",
                            "RolloutPercentage": 50
                        }
                    ],
                    "DefaultRolloutPercentage": 20
                }
            }
        }
    ]
}

Feature Filter Alias Namespaces

All of the built-in feature filter alias' are in the 'Microsoft' feature filter namespace. This is to prevent conflicts with other feature filters that may share the same simple alias. The segments of a feature filter namespace are split by the '.' character. A feature filter can be referenced by its fully qualified alias such as 'Microsoft.Percentage' or by the last segment which in the case of 'Microsoft.Percentage' is 'Percentage'.

Targeting

Targeting is a feature management strategy that enables developers to progressively roll out new features to their user base. The strategy is built on the concept of targeting a set of users known as the target audience. An audience is made up of specific users, groups, and a designated percentage of the entire user base. The groups that are included in the audience can be broken down further into percentages of their total members.

The following steps demonstrate an example of a progressive rollout for a new 'Beta' feature:

1. Individual users Jeff and Alicia are granted access to the Beta
2. Another user, Mark, asks to opt-in and is included.
3. Twenty percent of a group known as "Ring1" users are included in the Beta.
4. The number of "Ring1" users included in the beta is bumped up to 100 percent.
5. Five percent of the user base is included in the beta.
6. The rollout percentage is bumped up to 100 percent and the feature is completely rolled out.

This strategy for rolling out a feature is built in to the library through the included Microsoft.Targeting feature filter.

Targeting in a Web Application

An example web application that uses the targeting feature filter is available in the FeatureFlagDemo example project.

To begin using the

TargetingFilter

TargetingFilter

ITargetingContextAccessor

The implementation type used for the

ITargetingContextAccessor

TargetingFilter

ITargetingContextAccessor

HttpContextTargetingContextAccessor

services.AddSingleton();

services.AddFeatureManagement();
        .AddFeatureFilter();

ITargetingContextAccessor

To use the

TargetingFilter

ITargetingContextAccessor

An example that extracts targeting context information from the application's HTTP context is included in the FeatureFlagDemo example project. This method relies on the use of

IHttpContextAccessor

Targeting in a Console Application

The targeting filter relies on a targeting context to evaluate whether a feature should be turned on. This targeting context contains information such as what user is currently being evaluated, and what groups the user in. In console applications there is typically no ambient context available to flow this information in to the targeting filter, thus it must be passed directly when

FeatureManager.IsEnabledAsync

ContextualTargetingFilter

TargetingFilter.

services.AddFeatureManagement()
        .AddFeatureFilter();

Since

ContextualTargetingFilter

IContextualTargetingFilter

ITargetingContext

IFeatureManager.IsEnabledAsync

IFeatureManager fm;
…
// userId and groups defined somewhere earlier in application
TargetingContext targetingContext = new TargetingContext
{
   UserId = userId,
   Groups = groups;
}

await fm.IsEnabledAsync(featureName, targetingContext);

The

ContextualTargetingFilter

An example that uses the

ContextualTargetingFilter

Targeting Evaluation Options

Options are available to customize how targeting evaluation is performed across all features. These options can be configured when setting up feature management.

services.Configure(options =>
{
    options.IgnoreCase = true;
});

Caching

Feature state is provided by the IConfiguration system. Any caching and dynamic updating is expected to be handled by configuration providers. The feature manager asks IConfiguration for the latest value of a feature's state whenever a feature is checked to be enabled.

Snapshot

There are scenarios which require the state of a feature to remain consistent during the lifetime of a request. The values returned from the standard

IFeatureManager

IConfiguration

IFeatureManagerSnapshot

IFeatureManagerSnapshot

IFeatureManager

IFeatureManagerSnapshot

IFeatureManager

Custom Feature Providers

Implementing a custom feature provider enable developers to pull feature flags from sources such as a database or a feature management service. The included feature provider that is used by default pulls feature flags from .NET Core's configuration system. This allows for features to be defined in an appsettings.json file or in configuration providers like Azure App Configuration. This behavior can be substituted to provide complete control of where feature definitions are read from.

To customize the loading of feature definitions, one must implement the

IFeatureDefinitionProvider

public interface IFeatureDefinitionProvider
{
    Task GetFeatureDefinitionAsync(string featureName);

IAsyncEnumerable<featuredefinition> GetAllFeatureDefinitionsAsync();
}

To use an implementation of

IFeatureDefinitionProvider

IFeatureDefinitionProvider

InMemoryFeatureDefinitionProvider

services.AddSingleton()
        .AddFeatureManagement()

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.