Merge pull request #267642 from zhiyuanliang-ms/zhiyuanliang/update-targeting-usage

Azure App Configuration - Update TargetingFilter tutorial

Author: ttorble

articles/azure-app-configuration/howto-targetingfilter-aspnet-core.md

@@ -4,40 +4,143 @@ titleSuffix: Azure App Configuration
 description: Learn how to enable staged rollout of features for targeted audiences.
 ms.service: azure-app-configuration
 ms.devlang: csharp
-author: maud-lv
-ms.author: malev
-ms.topic: conceptual
-ms.date: 02/16/2024
+author: zhiyuanliang
+ms.author: zhiyuanliang
+ms.topic: how-to
+ms.date: 03/05/2024
 ---
 
 # Enable staged rollout of features for targeted audiences
 
-Feature flags allow you to dynamically activate or deactivate functionality in your application. Feature filters determine the state of a feature flag each time it's evaluated. The `Microsoft.FeatureManagement` library includes `TargetingFilter`, which enables a feature flag for a specified list of users and groups, or for a specified percentage of users. `TargetingFilter` is "sticky." This means that once an individual user receives a feature, they'll continue to see that feature on all future requests. You can use `TargetingFilter` to enable a feature for a specific account during a demo, to progressively roll out new features to users in different groups or "rings," and much more.
+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 users can be actual user accounts, but they can also be machines, devices, or any uniquely identifiable entities to which you want to roll out a feature.
+
+- The groups are up to your application to define. For example, when targeting user accounts, you can use Microsoft Entra groups or groups denoting user locations. When targeting machines, you can group them based on rollout stages. Groups can be any common attributes based on which you want to categorize your audience.
 
 In this article, you learn how to roll out a new feature in an ASP.NET Core web application to specified users and groups, using `TargetingFilter` with Azure App Configuration.
 
 ## Prerequisites
 
 - Finish the [Quickstart: Add feature flags to an ASP.NET Core app](./quickstart-feature-flag-aspnet-core.md).
-- Update the `Microsoft.FeatureManagement.AspNetCore` package to version **2.6.0** or later.
+- Update the [`Microsoft.FeatureManagement.AspNetCore`](https://www.nuget.org/packages/Microsoft.FeatureManagement.AspNetCore/) package to version **3.0.0** or later.
 
-## Create a web application with feature flags and authentication
+## Create a web application with authentication and feature flags
 
-To roll out features based on users and groups, you need a web application that allows users to sign in.
+In this section, you will create a web application that allows users to sign in and use the **Beta** feature flag you created before. Most of the steps are very similar to what you have done in [Quickstart](./quickstart-feature-flag-aspnet-core.md).
 
 1. Create a web application that authenticates against a local database using the following command.
 
    ```dotnetcli
    dotnet new mvc --auth Individual -o TestFeatureFlags
    ```
 
-1. Build and run. Then select the **Register** link in the upper right corner to create a new user account. Use an email address of `[email protected]`. On the **Register Confirmation** screen, select **Click here to confirm your account**.
+1. Add references to the following NuGet packages.
+
+    ```dotnetcli
+    dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
+    dotnet add package Microsoft.FeatureManagement.AspNetCore
+    ```
+
+1. Store the connection string for your App Configuration store.
+
+    ```dotnetcli
+    dotnet user-secrets init
+    dotnet user-secrets set ConnectionStrings:AppConfig "<your_connection_string>"
+    ```
+
+1. Update *Program.cs* with the following code.
+
+    ``` C#
+    // Existing code in Program.cs
+    // ... ...
+
+    var builder = WebApplication.CreateBuilder(args);
+
+    // Retrieve the connection string
+    string connectionString = builder.Configuration.GetConnectionString("AppConfig");
+
+    // Load configuration from Azure App Configuration
+    builder.Configuration.AddAzureAppConfiguration(options =>
+    {
+        options.Connect(connectionString);
+        options.UseFeatureFlags();
+    });
+
+    // Add Azure App Configuration middleware to the container of services
+    builder.Services.AddAzureAppConfiguration();
+
+    // Add feature management to the container of services
+    builder.Services.AddFeatureManagement();
+
+    // The rest of existing code in Program.cs
+    // ... ...
+    ```
+
+    ``` C#
+    // Existing code in Program.cs
+    // ... ...
+    
+    var app = builder.Build();
+
+    // Use Azure App Configuration middleware for dynamic configuration refresh
+    app.UseAzureAppConfiguration();
+
+    // The rest of existing code in Program.cs
+    // ... ...
+    ```
+
+1. Add *Beta.cshtml* under the *Views\Home* directory and update it with the following markup.
+
+    ``` cshtml
+    @{
+        ViewData["Title"] = "Beta Page";
+    }
 
-1. Follow the instructions in the [Quickstart](./quickstart-feature-flag-aspnet-core.md) to add a feature flag to your new web application.
+    <h1>This is the beta website.</h1>
+    ```
+
+1. Open *HomeController.cs* under the *Controllers* directory and update it with the following code.
+
+    ``` C#
+    public IActionResult Beta()
+    {
+        return View();
+    }
+    ```
+
+1. Open *_ViewImports.cshtml*, and register the feature manager Tag Helper using an `@addTagHelper` directive:
+
+    ``` cshtml
+    @addTagHelper *, Microsoft.FeatureManagement.AspNetCore
+    ```
+
+1. Open *_Layout.cshtml* in the Views\Shared directory. Insert a new `<feature>` tag in between the *Home* and *Privacy* navbar items.
+
+    ``` html
+    <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
+        <ul class="navbar-nav flex-grow-1">
+            <li class="nav-item">
+                <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Index">Home</a>
+            </li>
+            <feature name="Beta">
+                <li class="nav-item">
+                    <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Beta">Beta</a>
+                </li>
+            </feature>
+            <li class="nav-item">
+                <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
+            </li>
+        </ul>
+        <partial name="_LoginPartial" />
+    </div>
+    ```
+
+1. Build and run. Then select the **Register** link in the upper right corner to create a new user account. Use an email address of `[email protected]`. On the **Register Confirmation** screen, select **Click here to confirm your account**.
 
 1. Toggle the feature flag in App Configuration. Validate that this action controls the visibility of the **Beta** item on the navigation bar.
 
-## Update the web application code to use TargetingFilter
+## Update the web application code to use `TargetingFilter`
 
 At this point, you can use the feature flag to enable or disable the `Beta` feature for all users. To enable the feature flag for some users while disabling it for others, update your code to use `TargetingFilter`. In this example, you use the signed-in user's email address as the user ID, and the domain name portion of the email address as the group. You add the user and group to the `TargetingContext`. The `TargetingFilter` uses this context to determine the state of the feature flag for each request.
 
@@ -47,7 +150,7 @@ At this point, you can use the feature flag to enable or disable the `Beta` feat
    dotnet add package Microsoft.FeatureManagement.AspNetCore
    ```
 
-1. Add a *TestTargetingContextAccessor.cs* file.
+1. Add *ExampleTargetingContextAccessor.cs* file.
 
     ```csharp
     using Microsoft.AspNetCore.Http;
@@ -58,12 +161,12 @@ At this point, you can use the feature flag to enable or disable the `Beta` feat
 
     namespace TestFeatureFlags
     {
-        public class TestTargetingContextAccessor : ITargetingContextAccessor
+        public class ExampleTargetingContextAccessor : ITargetingContextAccessor
         {
-            private const string TargetingContextLookup = "TestTargetingContextAccessor.TargetingContext";
+            private const string TargetingContextLookup = "ExampleTargetingContextAccessor.TargetingContext";
             private readonly IHttpContextAccessor _httpContextAccessor;
 
-            public TestTargetingContextAccessor(IHttpContextAccessor httpContextAccessor)
+            public ExampleTargetingContextAccessor(IHttpContextAccessor httpContextAccessor)
             {
                 _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
             }
@@ -92,48 +195,23 @@ At this point, you can use the feature flag to enable or disable the `Beta` feat
     }
     ```
 
-1. In *Startup.cs*, add a reference to the *Microsoft.FeatureManagement.FeatureFilters* namespace.
+1. Open `Program.cs` and add the `ExampleTargetingContextAccessor` created in the earlier step and `TargetingFilter` to the service collection by calling the `WithTargeting` method after the existing line of `AddFeatureManagement`. The `TargetingFilter` will use the `ExampleTargetingContextAccessor` to determine the targeting context every time that the feature flag is evaluated.
 
     ```csharp
-    using Microsoft.FeatureManagement.FeatureFilters;
-    ```
+    // Existing code in Program.cs
+    // ... ...
 
-1. Update the *ConfigureServices* method to register `TargetingFilter`, following the call to `AddFeatureManagement()`.
+    // Add feature management to the container of services
+    builder.Services.AddFeatureManagement()
+                    .WithTargeting<ExampleTargetingContextAccessor>();
 
-    ```csharp
-    services.AddFeatureManagement()
-            .AddFeatureFilter<TargetingFilter>();
+    // The rest of existing code in Program.cs
+    // ... ...
     ```
 
     > [!NOTE]
     > For Blazor applications, see [instructions](./faq.yml#how-to-enable-feature-management-in-blazor-applications-or-as-scoped-services-in--net-applications) for enabling feature management as scoped services.
 
-1. Update the *ConfigureServices* method to add the `TestTargetingContextAccessor` created in the earlier step to the service collection. The *TargetingFilter* uses it to determine the targeting context every time that the feature flag is evaluated.
-
-    ```csharp
-      services.AddSingleton<ITargetingContextAccessor, TestTargetingContextAccessor>();
-    ```
-
-    The entire *ConfigureServices* method looks like this.
-
-    ```csharp
-    public void ConfigureServices(IServiceCollection services)
-    {
-        services.AddDbContext<ApplicationDbContext>(options =>
-            options.UseSqlite(
-                Configuration.GetConnectionString("DefaultConnection")));
-        services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
-                .AddEntityFrameworkStores<ApplicationDbContext>();
-        services.AddControllersWithViews();
-        services.AddRazorPages();
-
-        // Add feature management, targeting filter, and ITargetingContextAccessor to service collection
-        services.AddFeatureManagement()
-                .AddFeatureFilter<TargetingFilter>();
-        services.AddSingleton<ITargetingContextAccessor, TestTargetingContextAccessor>();
-    }
-    ```
-
 ## Update the feature flag to use TargetingFilter
 
 1. In the Azure portal, go to your App Configuration store and select **Feature manager**.