Source code | Package (NuGet) | Samples | Product documentation
A variant feature flag is an enhanced feature flag that supports multiple states or variations. While it can still be toggled on or off, it also allows for different configurations, ranging from simple primitives to complex JSON objects. Variant feature flags are particularly useful for feature rollouts, configuration rollouts, and feature experimentation (also known as A/B testing).
The new IVariantFeatureManager has been introduced as the successor to the existing IFeatureManager. It retains all the functionalities of IFeatureManager while adding new GetVariantAsync methods and supporting CancellationToken for all methods.
IVariantFeatureManager featureManager;
...
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.HelpText, CancellationToken.None);
model.Text = variant.Configuration.Value;Note: If reading variant flags from App Configuration, version 8.0.0 or above for the Microsoft.Extensions.Configuration.AzureAppConfiguration or Microsoft.Azure.AppConfiguration.AspNetCore package is required.
For more details on Variants, see here.
Variant feature flags can be used in conjunction with dependency injection to surface different implementations of a service for different users. This is accomplished by using the Variant Service Provider.
For more details on Variant Service Provider, see here
Telemetry provides observability into flag evaluations, offering insights into which users received specific flag results. This enables more powerful metric analysis, such as experimentation.
For more details on Telemetry, see here.
Added support for variant feature flags defined using Microsoft Feature Management schema. Variants and telemetry can be declared using Microsoft Feature Flag schema v2. Here is a Sample.
The performance of the feature flag state evaluation has been improved by up to 20%, with a memory reduction of up to 30% for .NET 8 applications compared to the version 3.5.0 release.
- Added support for injecting additional telemetry fields on feature evaluation events if telemetry is enabled.
DefaultWhenEnabledreflects what the DefaultWhenEnabled variant on the flag is.VariantAssignmentPercentageshows what percentage of users will be allocated the given Variant for the given Reason.
- The feature flag telemetry pipeline is now integrated with .NET
Acitivityinstrumentation. Feature manager now has anAcitvitySourcecalled "Microsoft.FeatureManagement". If telemetry is enabled for a feature flag, whenever the feature flag is evaluated, feature manager will start anActivityand add anActivityEventwith tags containing feature evaluation information. #455
-
If you were using earlier preview versions of this package and configuration files to define variant feature flags, they are no longer supported in the .NET Feature Management schema. Instead, please use the Microsoft Feature Management schema to define variant feature flags. #421.
-
AddTelemetryPublisherAPI andITelemetryPublisherinterface were removed. The feature flag telemetry pipeline is now integrated with .NETAcitivityinstrumentation. #455
- No changes in this release.
- All public classes no longer use init-only setters, ensuring compatibility with application using C# 7 or earlier. #450
- Fixed a bug that caused the time window filter to be unusable if
AddFeatureFilter<TimeWindowFilter>was called.`. #447
- Added a
Recurrenceoption to theTimeWindowfilter to support recurring time window. This enables scenarios where a feature flag is activated based on a recurrence pattern, such as every day after 5 PM or every Friday. See more details here. (#266) - A
LoggerFactoryis no longer required when constructing built-in filters. (#386)
- Fixed a possible null-reference exception when enumerating
GetFeatureNamesAsync. (#438)
- Added support for variant feature flags defined using Microsoft Feature Management schema. Variants and telemetry can be declared using Microsoft Feature Flag schema v2. The Microsoft Feature Management schema is designed to be language agnostic, which enables you to apply a consistent feature management configuration across Microsoft feature management libraries of different programming languages.
- Added support for variant feature flag-based service provider in dependency injection. It allows different service implementations to be injected automatically for different targeted audiences based on their variant assignment. (#39). See more details here.
- Added a
TargetingContextproperty to theEvaluationEvent. This allows feature evaluation events to accurately represent what the targeting context was at the time of feature evaluation. (#409)
- Added support for feature flags defined using Microsoft Feature Management schema
Variants are a tool that can be used to surface different variations of a feature to different segments of an audience. Previously, this library only worked with flags. The flags were limited to boolean values, as they are either enabled or disabled. Variants have dynamic values. They can be string, int, a complex object, or a reference to a ConfigurationSection.
//
// Modify view based off multiple possible variants
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.BackgroundUrl);
model.BackgroundUrl = variant.Configuration.Value;
return View(model);Variants are defined within a Feature, under a new section named "Variants". Variants are assigned by allocation, defined in a new section named "Allocation".
"BackgroundUrl": {
"Variants": [
{
"Name": "GetStarted",
"ConfigurationValue": "https://learn.microsoft.com/en-us/media/illustrations/biztalk-get-started-get-started.svg"
},
{
"Name": "InstallConfigure",
"ConfigurationValue": "https://learn.microsoft.com/en-us/media/illustrations/biztalk-host-integration-install-configure.svg"
}
],
"Allocation": {
// Defines Users, Groups, or Percentiles for variant assignment
}
// Filters and other Feature fields
}For more details on Variants, see here.
The feature management library now offers the ability to emit events containing information about a feature evaluation. This can be used to ensure a flag is running as expected, or to see which users were given which features and why they were given the feature. To enable this functionality, two things need to be done:
The flag needs to explicitly enable telemetry in its definition.
"MyFlag": {
"Telemetry": {
"Enabled": true
}
}And a telemetry publisher needs to be registered. Custom publishers can be defined, but for Application Insights one is already available in the Microsoft.FeatureManagement.Telemetry.ApplicationInsights package. Publishers can be added with a single line.
builder.services
.AddFeatureManagement()
.AddTelemetryPublisher<ApplicationInsightsTelemetryPublisher>();An example is available to demonstrate how to use the new Telemetry in an ASP.NET application. See the example in the examples folder.
For more details on Telemetry, see here.
IVariantFeatureManager has been added as the successor of the existing IFeatureManager. It continues to offer the functions of IFeatureManager, but offers the new GetVariantAsync methods as well.
IVariantFeatureManager incorporates cancellation tokens into the methods of IFeatureManager. For existing apps to take advantage of cancellation tokens, use the IVariantFeatureManager interface instead and adjust calls to IsEnabledAsync or GetFeatureNamesAsync to include a CancellationToken.
Status is a new optional field on a Feature that controls how a flag's enabled state is evaluated. Flags can set this field to Disabled. This will cause the flag to always act disabled, while the rest of the defined schema remains intact. See here.
There are no breaking changes in this release.
- Fixed a bug where feature manager will fail to add cache entry if the shared memory cache sets
SizeLimit. (#325)
-
FeatureManagerandConfigurationFeatureDefinitionProviderare now public. (#126)- Enables usage of external dependency injection containers.
- Allows usage of
FeatureManagerwithout requiring dependency injection.
-
Added support for server-side Blazor apps, where the following API can be used in place of the existing
AddFeatureManagement()API. The new API registers the feature manager and feature filters as scoped services, while the existing API registers them as singletons. (#258)public static IFeatureManagementBuilder AddScopedFeatureManagement(this IServiceCollection services)
- Fixed a bug introduced in the previous release where feature flags cannot be loaded from a custom section of configuration. (#308)
- Fixed a bug introduced in the previous release where evaluation of a feature flag that references a contextual feature filter may throw an exception if there is no appropriate context provided during evaluation. (#313)
- Dropped netcoreapp3.1 and net5.0 target frameworks since both have reached the end of their life cycle. microsoft/FeatureManagement-Dotnet#267
- All feature flags must be defined in a
FeatureManagementsection within configuration. Previously flags were discovered at the top level of configuration if theFeatureManagementsection was not defined, but this functionality has been removed. microsoft/FeatureManagement-Dotnet#261
- Built-in filters are registered by default. microsoft/FeatureManagement-Dotnet#287
This includes:
TimeWindowFilterContextualTargetingFilterPercentageFilter
TargetingContextAccessorcan be added via the.WithTargetingextension method. This will automatically add the built-inTargetingFilter. microsoft/FeatureManagement-Dotnet#287- Contextual and non-contextual filters are now able to share the same name/alias. An example of two such filters are the built-in
TargetingFilterandContextualTargetingFilterthat both use the alias"Targeting". Given a scenario that a contextual and non-contextual filter are registered in the application, the filter that is used when evaluating a flag is dependent up on whether a context was passed in toIFeatureManager.IsEnabled. See 'contextual/non-contextual filter selection process' below for a more detailed explanation. microsoft/FeatureManagement-Dotnet#262 - Added netstandard 2.1 as a target framework in the Microsoft.FeatureManagement package. microsoft/FeatureManagement-Dotnet#267
- Added net7.0 as a target framework in the Microsoft.FeatureManagement.AspNetCore package. microsoft/FeatureManagement-Dotnet#267
- Prevents the usage of colon in Feature names.
- Adjusts log level for noisy warning when feature definitions are not found.
- Fixed an edge case in targeting if a user is allocated to exactly the 100th percentile (~1 in 2 billion chance)
It is no longer necessary to register the following filters manually:
TimeWindowFilterContextualTargetingFilterPercentageFilter
The following code:
services.AddFeatureManagement()
.AddFeatureFilter<TimeWindowFilter>();
should be simplified to:
services.AddFeatureManagement();
Since the TargetingFilter (the non-contextual version) requires an implementation of ITargetingContextAccessor to function, it is not added by default. However, a discovery/helper method was added to streamline it's addition.
The following code:
services.AddSingleton<ITargetingContextAccessor, MyTargetingContextAccessor>();
services.AddFeatureManagement()
.AddFeatureFilter<TargetingFilter>();
should be simplified to:
services.AddFeatureManagement()
.WithTargeting<MyTargetingContextAccessor>();
The following passage describes the process of selecting a filter when a contextual and non-contextual filter of the same name are registered in an application.
Let's say you have a non-contextual filter called FilterA and two contextual filters FilterB and FilterC which accept TypeB and TypeC contexts respectively. All of three filters share the same alias "SharedFilterName". you also have a feature flag "MyFeature" which uses the feature filter "SharedFilterName" in its configuration.
If all of three filters are registered:
- When you call IsEnabledAsync("MyFeature"), the FilterA will be used to evaluate the feature flag.
- When you call IsEnabledAsync("MyFeature", context), if context's type is TypeB, FilterB will be used and if context's type is TypeC, FilterC will be used.
- When you call IsEnabledAsync("MyFeature", context), if context's type is TypeF, FilterA will be used.
- Fixed an edge case for EvaluateAsync call that doesn't use context from FeatureManager. (#244)
Promotes the changes in 2.6.0-preview and 2.6.0-preview2 to stable. These changes include parameter caching, requirement type, and targeting exclusion.
Applications using built-in ConfigurationFeatureDefinitionProvider will now benefit from caching of feature filter parameters. This will improve performance of the application by reducing the number of times a filter's parameters are cast in short time frames, yielding observed performance increase of up to 100x. This change will not affect custom filters by default. For custom filters, the class must implement the IFilterParametersBinder interface. Below is an example.
class MyFilter : IFeatureFilter, IFilterParametersBinder
{
public object BindParameters(IConfiguration filterParameters)
{
return filterParameters.Get<FilterSettings>();
}
public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context, CancellationToken cancellationToken)
{
FilterSettings settings = (FilterSettings)context.Settings;
...
}
}For more details read here
Features can now declare a RequirementType. The default RequirementType is Any, which means if any of it's filters evaluate to true, then the feature will be enabled. Declaring a RequirementType of All means that every filter must evaluate to true in order for the feature to be enabled. Added in microsoft/FeatureManagement-Dotnet#221.
"FeatureW": {
"RequirementType": "All",
"EnabledFor": []
}For more details read here
Targeting filters define an Audience. Now, Audiences can be fine tuned to exclude certain users and groups. By adding an Exclusion to an Audience, targeting filters will evaluate to false for users that are either directly defined, or a part of a group that is defined within the Exclusion. This takes priority over any other section of the Audience. Added in microsoft/FeatureManagement-Dotnet#218.
"Exclusion": {
"Users": [
"Mark"
],
"Groups": [
"Admins"
]
}For more details read here
This release was deprecated. The dynamic feature functionality will be re-introduced in a later version with some design changes.
Dynamic features are a tool that can be used to surface different variants of a feature to different segments of an audience. Previously, this library only worked with feature flags. Feature flags are limited to boolean values, as they are either enabled or disabled. Dynamic features have dynamic values. They can be string, int, a complex object, or any other type.
//
// Modify view based off multiple possible variants
model.BackgroundUrl = dynamicFeatureManager.GetVariantAsync<string>("HomeBackground", cancellationToken);
return View(model);For more details read here.
Version 2 of Microsoft.FeatureManagement has an asynchronous pipeline, but cancellation token support was not added. Adding support for this in v2 would have required changing interfaces, thus a breaking change. V3 introduces this breaking change, and now proper cancellation is supported through the pipeline.
The original schema of the "FeatureManagement" configuration section treated all sub objects as feature flags. Now there are dynamic features alongside feature flags. Additionally, there are other switches that are expected to be added in the future to customize global feature management state. To make room for this the schema has been updated.
{
"FeatureManagement": {
"FeatureFlags": {
},
"DynamicFeatures": {
}
}
}For more details read here.
IFeatureFilter.EvaluateAsyncnow accepts a cancellation token.IFeatureFilter.EvaluateAsync(FeatureFilterEvaluationContext)->IFeatureFilter.EvaluateAsync(FeatureFilterEvaluationContext, CancellationToken)- All built-in feature filters
EvaluateAsyncmethod now require a cancellation token. - An equivalent change applies to
IContextualFeatureFilter.
ITargetingContextAccessor.GetContextAsyncnow accepts a cancellation token.ITargetingContextAccessor.GetContextAsync()->ITargetingContextAccessor.GetContextAsync(CancellationToken).
- All async
IFeatureManagermethods now accept a cancellation token. IFeatureManager.GetFeatureNamesAsynchas been renamed toIFeatureManager.GetFeatureFlagNamesAsync.IFeatureDefinitionProviderhas been renamed toIFeatureFlagDefinitionProvider.- All methods now accept cancellation token.
ISessionManagernow accepts cancellation token.FeatureDefinitionrenamed toFeatureFlagDefinition.IFeatureManagementBuildernow declaresAddFeatureVariantAssigner.FeatureFilterEvaluationContext.FeatureNamerenamed toFeatureFilterEvaluationContext.FeatureFlagName
- Updated summary on
FeatureGateAttributeto mention that it is usable on Razor pages. #170
- Updated
FeatureGateAttributeto support Razor pages. This attribute can be placed on Razor page handlers to control access to the page based on whether a feature flag is on or off. #166
- Fixed an issue in
PercentageFilterwhere a feature may occasionally be considered as on even when the filter is set to 0 percent. #156
- Added option to throw when attempting to evaluate a missing feature. #140
IFeatureManagementSnapshotis now thread-safe. #141
FilterAliasAttributenow uses the proper parameter name in anArgumentNullExceptionifaliasis null.
The net5.0 framework has been added to the list of target frameworks. This change resolves dependency issues for ASP.NET Core 5.0 applications.
- The license URL for these packages has been fixed.
No changes have been made in this version. This is the first stable release with the targeting feature filter (introduced in 2.1.0-preview) and custom feature providers (introduced in 2.2.0-preview).
Support for custom feature providers has been added. #79
Implementing a custom feature provider enables developers to to read feature flags from sources such as a database or a feature management service. For more information on the concept of custom feature providers and how to use this new feature take a look at the project's readme.
The netcoreapp3.1 framework has been added to the list of target frameworks. This change resolves dependency issues for ASP.NET Core 3.1 applications. #77
Support for rolling out features to a target audience has been added through built in feature filters. #56
Targeting enables developers to progressively roll out features to a target audience that can be increased gradually. For more information on the concept of targeting and how to use this new feature take a look at the project's readme.
The IFeatureManager interface now exposes a way to enumerate all feature names that are registered in the system. This enables work flows where the states of all known features need to be evaluated.
IFeatureManager fm;
await foreach (string featureName in fm.GetFeatureNamesAsync())
{
await IsEnabledAsync(featureName);
}
Important: Using the await foreach syntax requires using version 8.0 or above of C#.
When the feature manager tries to evaluate the state of a feature that depends on a missing feature filter it will now throw a FeatureManagementException with the error MissingFeatureFilter.
The new fail-fast behavior can be disabled via feature management options if the old behavior to ignore missing feature filters is desired.
services.Configure<FeatureManagementOptions>(options =>
{
options.IgnoreMissingFeatureFilters = true;
});
- FeatureManager now throws a
FeatureManagementExceptionwith errorAmbiguousFeatureFilter, instead ofInvalidOperationException, if a feature makes an ambiguous reference to two or more feature filters. Task<bool> ISessionManager.TryGetAsync(string featureName, out bool enabled)has been changed toTask<bool?> ISessionManager.GetAsync(string featureName)to enable async implementations.
Support for async feature filters has been added. This results in the entire feature management pipeline being asynchronous. Async feature filters pave the way to performing async workloads in feature filters if desired.
Before
IFeatureManager fm;
if (fm.IsEnabled("MyFeature"))
{
}
After
IFeatureManager fm;
if (await fm.IsEnabledAsync("MyFeature"))
{
}
The original design for the feature management library relied on applications to have an ambient context. An application's ambient context could be used in feature filters to obtain information such as user identity and other information relevant when toggling features. This led to a disconnect in console applications which do not have an ambient context in most cases. Now application's without an ambient context can float a context into the feature management system by using the new IFeatureManager.IsEnabledAsync<TContext>(string feature, TContext context) method. The context parameter is able to be consumed by feature filters that implement IContextualFeatureFilter.
Consumption
The ability to pass a context when evaluating a feature has been added to IFeatureManager.
IFeatureManager fm = services.GetRequiredService<IFeatureManager>();
await fm.IsEnabledAsync("featureName", new MyApplicationContext
{
UserId = "someUser"
});
Contextual Feature Filters
Contextual feature filters are feature filters that can utilize a context provided by the application when evaluating whether a feature is on or off. Contextual feature filters are a generic type. Their generic type parameter describes the interface that the passed in context must implement for the filter to be able to evaluate it.
As an example, IContextualFeatureFilter<IAccountContext> requires a context that implements IAccountContext to be passed in. If a feature is checked for enabled and a context is provided that does not implement IAccountContext then the previously mentioned filter would not run.
IFeatureFilterMetadata
With the introduction of IContextualFeatureFilter there are now two types of feature filters including IFeatureFilter. The two types of feature filters both inherit IFeatureFilterMetadata. IFeatureFilterMetadata is a marker interface and does not actually provide any feature filtering capabilities. It is used as the new parameter type for IFeatureManagementBuilder.AddFeatureFilter.
Performance Improvement
A cache for feature settings has been added which respects the reload token of the .NET Core configuration system. If a configuration provider is used that does not properly trigger the reload token of the .NET Core configuration system, FeatureManager will not be able to pickup changes.
IFeatureManager.IsEnabledis now asynchronousIsEnabledwas renamed toIsEnabledAsync.IFeatureManagerSnapshot.IsEnabledis also affected.
IFeatureFilter.Evaluateis now asynchronousEvaluatewas renamed toEvaluateAsync.
Mvc.Filters.FilterCollection.AddForFeaturenow only acceptsIAsyncActionFilterrather than any type of filter.AddRouteForFeaturehas been removed.ISessionManageris now an async interface.
- Renamed 'Microsoft.FeatureManagment.FeatureAttribute' to 'Microsoft.FeatureManagment.Mvc.FeatureGateAttribute'.
- Enhanced FeatureGateAttribute to allow specifying whether 'any' or 'all' features need to be enabled.
- Enhanced feature tag helper to allow for multiple features, any/all requirement, and negated logic.
- Added
IFeatureManagementBuilder.AddSessionManagerto enhance discoverability for providing a custom feature session manager.- Previous approach was
IServiceCollection.AddSingleton<ISessionManager>(MySessionManager)
- Previous approach was