4.0.0-preview

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 4.0.0-preview
• Microsoft.FeatureManagement.AspNetCore 4.0.0-preview
• Microsoft.FeatureManagement.Telemetry.ApplicationInsights 4.0.0-preview

Variants

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.

Telemetry

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.

Additional Changes

IVariantFeatureManager

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.

Cancellation Tokens

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 field

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.

Breaking Changes

There are no breaking changes in this release.

3.1.1

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 3.1.1
• Microsoft.FeatureManagement.AspNetCore 3.1.1

Bug fix

• Fixed a bug where feature manager will fail to add cache entry if the shared memory cache sets SizeLimit. (#325)

3.1.0

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 3.1.0
• Microsoft.FeatureManagement.AspNetCore 3.1.0

Enhancements

• FeatureManager and ConfigurationFeatureDefinitionProvider are now public.

  • Enables usage of external dependency injection containers.
  • Allows usage of FeatureManager without 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)

The FeatureManager and ConfigurationFeatureDefinitionProvider classes are the core services of the feature management system. In the past, both of them were internal and could only be registered via the AddFeatureManagement() method, which relies on Microsoft.Extensions.DependencyInjection. This limitation prevented third-party DI container systems from registering these classes, making them incompatible with the entire feature management system. After exposing FeatureManager and ConfigurationFeatureDefinitionProvider to public, all Feature Management services have been made accessible to other DI containers. (Related issues: #126 #258)

Additionally, the recommended way for accessing HttpContext in Blazor is through a scoped context provider service. The singleton HttpContextAccessor pattern, while working well in regular ASP.NET Core web app, becomes unreliable in Blazor components. As a result, to use Targeting in Blazor, the targeting filter and targeting context accessor should be registered as scoped. (Related issue: #15 #258)

We have introduced an alternative way AddScopedFeatureManagement() to register the feature management system, where the feature manager and all feature filters will be registered as scoped. It ensures that the integration aligns with Blazor's best practices for handling HttpContext and enhances the overall ease of use.

Bug Fixes

• 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

3.0.0

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 3.0.0
• Microsoft.FeatureManagement.AspNetCore 3.0.0

Breaking Changes

• Dropped netcoreapp3.1 and net5.0 target frameworks since both have reached the end of their life cycle. #267
• All feature flags must be defined in a FeatureManagement section within configuration. Previously flags were discovered at the top level of configuration if the FeatureManagement section was not defined, but this functionality has been removed. #261

Enhancements

• Built-in filters are registered by default. #287
  This includes:
  • TimeWindowFilter
  • ContextualTargetingFilter
  • PercentageFilter
• TargetingContextAccessor can be added via the .WithTargeting extension method. This will automatically add the built-in TargetingFilter. #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 TargetingFilter and ContextualTargetingFilter that 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 to IFeatureManager.IsEnabled. See 'contextual/non-contextual filter selection process' below for a more detailed explanation. #262
• Added netstandard 2.1 as a target framework in the Microsoft.FeatureManagement package. #267
• Added net7.0 as a target framework in the Microsoft.FeatureManagement.AspNetCore package. #267

Bug Fixes

• 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)

Migration

Adding built-in filters

It is no longer necessary to register the following filters manually:

• TimeWindowFilter
• ContextualTargetingFilter
• PercentageFilter

The following code:

services.AddFeatureManagement()
    .AddFeatureFilter<TimeWindowFilter>();

should be simplified to:

services.AddFeatureManagement();

Adding Targeting Filter

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>();

Additional

Contextual/non-contextual filter selection process

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.

2.6.1

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 2.6.1
• Microsoft.FeatureManagement.AspNetCore 2.6.1

Bug fix

• Adds edge case for EvaluateAsync call that doesn't use context from FeatureManager

2.6.0

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.

2.6.0-preview2

Enhancement - Parameter Caching

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

2.6.0-preview

Feature - RequirementType

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 #221.

"FeatureW": {
    "RequirementType": "All",
    "EnabledFor": []
}

For more details read here

Targeting Exclusion

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 #218.

"Exclusion": {
    "Users": [
        "Mark"
    ],
    "Groups": [
        "Admins"
    ]
}

For more details read here

3.0.0-preview

DEPRECATED

This release was deprecated. The dynamic feature functionality will be re-introduced in a later version with some design changes.

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 3.0.0-preview
• Microsoft.FeatureManagement.AspNetCore 3.0.0-preview

Preview Release

A new set of APIs has been added to support dynamic features. The dynamic feature experience can be considered to be in preview.

Features

Dynamic Features

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.

Cancellation token support

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.

New Configuration Schema

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.

Breaking Changes

• IFeatureFilter.EvaluateAsync now accepts a cancellation token.
  • IFeatureFilter.EvaluateAsync(FeatureFilterEvaluationContext) -> IFeatureFilter.EvaluateAsync(FeatureFilterEvaluationContext, CancellationToken)
  • All built-in feature filters EvaluateAsync method now require a cancellation token.
  • An equivalent change applies to IContextualFeatureFilter.
• ITargetingContextAccessor.GetContextAsync now accepts a cancellation token.
  • ITargetingContextAccessor.GetContextAsync() -> ITargetingContextAccessor.GetContextAsync(CancellationToken).
• All async IFeatureManager methods now accept a cancellation token.
• IFeatureManager.GetFeatureNamesAsync has been renamed to IFeatureManager.GetFeatureFlagNamesAsync.
• IFeatureDefinitionProvider has been renamed to IFeatureFlagDefinitionProvider.
  • All methods now accept cancellation token.
• ISessionManager now accepts cancellation token.
• FeatureDefinition renamed to FeatureFlagDefinition.
• IFeatureManagementBuilder now declares AddFeatureVariantAssigner.
• FeatureFilterEvaluationContext.FeatureName renamed to FeatureFilterEvaluationContext.FeatureFlagName

2.5.1

Microsoft.FeatureManagement Updates

The packages associated with this release are

• Microsoft.FeatureManagement 2.5.1
• Microsoft.FeatureManagement.AspNetCore 2.5.1

Bug fix

• Updated summary on FeatureGateAttribute to mention that it is usable on Razor pages. (#170)