|
1 | 1 | --- |
2 | | -title: Use feature filters to enable conditional feature flags |
| 2 | +title: Enable conditional features with a custom filter in an ASP.NET Core application |
3 | 3 | titleSuffix: Azure App Configuration |
4 | | -description: Learn how to use feature filters in Azure App Configuration to enable conditional feature flags for your app. |
| 4 | +description: Learn how to implement a custom feature filter to enable conditional feature flags for your ASP.NET Core application. |
5 | 5 | ms.service: azure-app-configuration |
6 | 6 | ms.devlang: csharp |
7 | 7 | ms.custom: devx-track-csharp |
8 | 8 | author: zhiyuanliang |
9 | 9 | ms.author: zhiyuanliang |
10 | 10 | ms.topic: how-to |
11 | | -ms.date: 02/28/2024 |
12 | | -#Customerintent: As a developer, I want to create a feature filter to activate a feature flag depending on a specific scenario. |
| 11 | +ms.date: 03/28/2024 |
13 | 12 | --- |
14 | 13 |
|
15 | | -# Use feature filters to enable conditional feature flags |
| 14 | +# Tutorial: Enable conditional features with a custom filter in an ASP.NET Core application |
16 | 15 |
|
17 | | -Feature flags allow you to activate or deactivate functionality in your application. A simple feature flag is either on or off. The application always behaves the same way. For example, you could roll out a new feature behind a feature flag. When the feature flag is enabled, all users see the new feature. Disabling the feature flag hides the new feature. |
| 16 | +Feature flags can use feature filters to enable features conditionally. To learn more about feature filters, see [Tutorial: Enable conditional features with feature filters](./howto-feature-filters.md). |
18 | 17 |
|
19 | | -In contrast, a _conditional feature flag_ allows the feature flag to be enabled or disabled dynamically. The application may behave differently, depending on the feature flag criteria. Suppose you want to show your new feature to a small subset of users at first. A conditional feature flag allows you to enable the feature flag for some users while disabling it for others. _Feature filters_ determine the state of the feature flag each time it's evaluated. |
| 18 | +The example used in this tutorial is based on the ASP.NET Core application introduced in the feature management [quickstart](./quickstart-feature-flag-aspnet-core.md). Before proceeding further, complete the quickstart to create an ASP.NET Core application with a *Beta* feature flag. Once completed, you must [add a custom feature filter](./howto-feature-filters.md) to the *Beta* feature flag in your App Configuration store. |
20 | 19 |
|
21 | | -The `Microsoft.FeatureManagement` library includes the following built-in feature filters accessible from the Azure App Configuration portal. |
22 | | - |
23 | | -- **Time window filter** enables the feature flag during a specified window of time. |
24 | | -- **Targeting filter** enables the feature flag for specified users and groups. |
25 | | - |
26 | | -You can also create your own feature filter that implements the `Microsoft.FeatureManagement.IFeatureFilter` interface. For more information, see [Implementing a Feature Filter](https://github.com/microsoft/FeatureManagement-Dotnet#implementing-a-feature-filter). |
| 20 | +In this tutorial, you'll learn how to implement a custom feature filter and use the feature filter to enable features conditionally. |
27 | 21 |
|
28 | 22 | ## Prerequisites |
29 | 23 |
|
30 | | -- Follow the instructions in [Quickstart: Add feature flags to an ASP.NET Core app](./quickstart-feature-flag-aspnet-core.md) to create a web app with a feature flag. |
31 | | -- Install the [`Microsoft.FeatureManagement.AspNetCore`](https://www.nuget.org/packages/Microsoft.FeatureManagement.AspNetCore/) package of version **3.0.0** or later. |
32 | | - |
33 | | -## Register a feature filter |
34 | | - |
35 | | -If you have a [custom feature filter](https://github.com/microsoft/FeatureManagement-Dotnet#implementing-a-feature-filter), you can register it by calling the `AddFeatureFilter` method. |
| 24 | +- Create an [ASP.NET Core app with a feature flag](./quickstart-feature-flag-aspnet-core.md). |
| 25 | +- [Add a custom feature filter to the feature flag](./howto-feature-filters.md) |
36 | 26 |
|
37 | | -```csharp |
38 | | -services.AddFeatureManagement() |
39 | | - .AddFeatureFilter<MyCriteriaFilter>(); |
40 | | -``` |
| 27 | +## Implement a custom feature filter |
41 | 28 |
|
42 | | -Starting with version *3.0.0* of `Microsoft.FeatureManagement`, the following [built-in filters](https://github.com/microsoft/FeatureManagement-Dotnet#built-in-feature-filters) are registered automatically as part of the `AddFeatureManagement` call, so you don't need to register them. |
| 29 | +You've added a custom feature filter named **Random** with a **Percentage** parameter for your *Beta* feature flag in the prerequisites. Next, you'll implement the feature filter to enable the *Beta* feature flag based on the chance defined by the **Percentage** parameter. |
43 | 30 |
|
44 | | -- `TimeWindowFilter` |
45 | | -- `ContextualTargetingFilter` |
46 | | -- `PercentageFilter` |
| 31 | +1. Add a `RandomFilter.cs` file with the following code. |
47 | 32 |
|
48 | | -> [!TIP] |
49 | | -> For more information on using `TargetingFilter`, see [Enable staged rollout of features for targeted audiences](./howto-targetingfilter-aspnet-core.md). |
| 33 | + ```csharp |
| 34 | + using Microsoft.FeatureManagement; |
50 | 35 |
|
51 | | -## Add a feature filter to a feature flag |
| 36 | + namespace TestAppConfig |
| 37 | + { |
| 38 | + [FilterAlias("Random")] |
| 39 | + public class RandomFilter : IFeatureFilter |
| 40 | + { |
| 41 | + private readonly Random _random; |
52 | 42 |
|
53 | | -In this section, you will learn how to add a feature filter to the **Beta** feature flag you created in the [Quickstart](./quickstart-feature-flag-aspnet-core.md). The following steps use the built-in `TimeWindowFilter` as an example. |
| 43 | + public RandomFilter() |
| 44 | + { |
| 45 | + _random = new Random(); |
| 46 | + } |
54 | 47 |
|
55 | | -1. In the Azure portal, go to your configuration store and select **Feature manager**. |
| 48 | + public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context) |
| 49 | + { |
| 50 | + int percentage = context.Parameters.GetSection("Percentage").Get<int>(); |
56 | 51 |
|
57 | | - :::image type="content" source="./media/feature-filters/edit-beta-feature-flag.png" alt-text="Screenshot of the Azure portal, selecting the Edit option for the **Beta** feature flag, under Feature manager."::: |
| 52 | + int randomNumber = _random.Next(100); |
58 | 53 |
|
59 | | -1. On the line with the **Beta** feature flag you created in the quickstart, select the context menu and then **Edit**. |
| 54 | + return Task.FromResult(randomNumber <= percentage); |
| 55 | + } |
| 56 | + } |
| 57 | + } |
| 58 | + ``` |
60 | 59 |
|
61 | | -1. In the **Edit feature flag** pane that opens, check the **Enable feature flag** checkbox if it isn't already enabled. Then check the **Use feature filter** checkbox and select **Create**. |
| 60 | + You added a `RandomFilter` class that implements the `IFeatureFilter` interface from the `Microsoft.FeatureManagement` library. The `IFeatureFilter` interface has a single method named `EvaluateAsync`, which is called whenever a feature flag is evaluated. In `EvaluateAsync`, a feature filter enables a feature flag by returning `true`. |
62 | 61 |
|
63 | | - :::image type="content" source="./media/feature-filters/edit-a-feature-flag.png" alt-text="Screenshot of the Azure portal, filling out the form 'Edit feature flag'."::: |
| 62 | + You decorated a `FilterAliasAttribute` to the `RandomFilter` to give your filter an alias **Random**, which matches the filter name you set in the *Beta* feature flag in Azure App Configuration. |
64 | 63 |
|
65 | | -1. The pane **Create a new filter** opens. Under **Filter type**, select **Time window filter**. |
| 64 | +1. Open the *Program.cs* file and register the `RandomFilter` by calling the `AddFeatureFilter` method. |
66 | 65 |
|
67 | | - :::image type="content" source="./media/feature-filters/add-time-window-filter.png" alt-text="Screenshot of the Azure portal, creating a new time window filter."::: |
| 66 | + ```csharp |
| 67 | + // The rest of existing code in Program.cs |
| 68 | + // ... ... |
68 | 69 |
|
69 | | -1. Set the **Start date** to **Custom** and select a time a few minutes ahead of your current time. Set the **Expiry date** to **Never** |
| 70 | + // Add feature management to the container of services. |
| 71 | + builder.Services.AddFeatureManagement() |
| 72 | + .AddFeatureFilter<RandomFilter>(); |
70 | 73 |
|
71 | | -1. Select **Add** to save the new feature filter and return to the **Edit feature flag** screen. |
| 74 | + // The rest of existing code in Program.cs |
| 75 | + // ... ... |
| 76 | + ``` |
72 | 77 |
|
73 | | -1. The feature filter you created is now listed in the feature flag details. Select **Apply** to save the new feature flag settings. |
| 78 | +## Feature filter in action |
74 | 79 |
|
75 | | - :::image type="content" source="./media/feature-filters/feature-flag-edit-apply-filter.png" alt-text="Screenshot of the Azure portal, applying new time window filter."::: |
| 80 | +Relaunch the application and refresh the browser a few times. Without manually toggling the feature flag, you will see that the **Beta** menu sometimes appears and sometimes doesn't. |
76 | 81 |
|
77 | | -1. On the **Feature manager** page, the feature flag now has a **Feature filter(s)** value of **1**. |
| 82 | +> [!div class="mx-imgBorder"] |
| 83 | +>  |
78 | 84 |
|
79 | | - :::image type="content" source="./media/feature-filters/updated-feature-flag.png" alt-text="Screenshot of the Azure portal, displaying updated feature flag."::: |
| 85 | +> [!div class="mx-imgBorder"] |
| 86 | +>  |
80 | 87 |
|
81 | | -## Feature filters in action |
82 | | - |
83 | | -Relaunch the application you created in the [Quickstart](./quickstart-feature-flag-aspnet-core.md). If your current time is earlier than the start time set for the time window filter, the **Beta** menu item will not appear on the toolbar. This is because the **Beta** feature flag is disabled by the time window filter. |
| 88 | +## Next steps |
84 | 89 |
|
85 | | -Once the start time has passed, refresh your browser a few times. You will notice that the **Beta** menu item will now appear. This is because the **Beta** feature flag is now enabled by the time window filter. |
| 90 | +To learn more about the built-in feature filters, continue to the following tutorials. |
86 | 91 |
|
87 | | -## Next steps |
| 92 | +> [!div class="nextstepaction"] |
| 93 | +> [Enable features on a schedule](./howto-timewindow-filter.md) |
88 | 94 |
|
89 | 95 | > [!div class="nextstepaction"] |
90 | | -> [Enable staged rollout of features for targeted audiences](./howto-targetingfilter-aspnet-core.md) |
| 96 | +> [Roll out features to targeted audience](./howto-targetingfilter.md) |
0 commit comments