reorganize aspnet targeting example

Author: zhiyuanliang-ms

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

@@ -12,21 +12,21 @@ ms.date: 03/26/2024
 
 # Tutorial: Roll out features to targeted audiences in an ASP.NET Core app
 
-In this tutorial, you'll use the targeting filter to roll out a feature to targeted audience for your ASP.NET Core app. For more information about the targeting filter, please read this [article](./howto-targetingfilter.md).
+In this tutorial, you'll use the targeting filter to roll out a feature to targeted audience for your ASP.NET Core app. For more information about the targeting filter, see [Roll out features to targeted audiences](./howto-targetingfilter.md).
 
 ## Prerequisites
 
-- Finish the [Quickstart: Add feature flags to an ASP.NET Core app](./quickstart-feature-flag-aspnet-core.md).
-- Update the [`Microsoft.FeatureManagement.AspNetCore`](https://www.nuget.org/packages/Microsoft.FeatureManagement.AspNetCore/) package to version **3.0.0** or later.
+- [A feature flag with targeting filter](./howto-targetingfilter.md)
+- [.NET SDK 6.0 or later](https://dotnet.microsoft.com/download)
 
-## Create a web application with authentication and feature flags
+## Create a web application with a feature flag
 
 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
+   dotnet new webapp --auth Individual -o TestFeatureFlags
    ```
 
 1. Add references to the following NuGet packages.
@@ -43,7 +43,9 @@ In this section, you will create a web application that allows users to sign in
     dotnet user-secrets set ConnectionStrings:AppConfig "<your_connection_string>"
     ```
 
-1. Update the *Program.cs* file with the following code.
+1. Add Azure App Configuration and feature management to your app.
+
+    Update the *Program.cs* file with the following code. 
 
     ``` C#
     // Existing code in Program.cs
@@ -52,9 +54,9 @@ In this section, you will create a web application that allows users to sign in
     var builder = WebApplication.CreateBuilder(args);
 
     // Retrieve the App Config connection string
-    string AppConfigConnectionString = builder.Configuration.GetConnectionString("AppConfig");
+    string AppConfigConnectionString = builder.Configuration.GetConnectionString("AppConfig") ?? throw new InvalidOperationException("Connection string 'AppConfig' not found."); ;
 
-    // Load configuration from Azure App Configuration
+    // Load feature flag configuration from Azure App Configuration
     builder.Configuration.AddAzureAppConfiguration(options =>
     {
         options.Connect(AppConfigConnectionString);
@@ -71,6 +73,10 @@ In this section, you will create a web application that allows users to sign in
     // ... ...
     ```
 
+1. Call the `UseAzureAppConfiguration` method. It enables your app to use the App Configuration middleware to update the feature flag configuration for you automatically.
+
+    Update Program.cs withe the following code.
+
     ``` C#
     // Existing code in Program.cs
     // ... ...
@@ -84,68 +90,54 @@ In this section, you will create a web application that allows users to sign in
     // ... ...
     ```
 
-1. Add a *Beta.cshtml* file under the *Views\Home* directory and update it with the following markup.
+1. Add a new empty Razor page named **Beta** under the Pages directory. It includes two files *Beta.cshtml* and *Beta.cshtml.cs*.
 
     ``` cshtml
+    @page
+    @model TestFeatureFlags.Pages.BetaModel
     @{
         ViewData["Title"] = "Beta Page";
     }
 
     <h1>This is the beta website.</h1>
     ```
 
-1. Open the *HomeController.cs* file under the *Controllers* directory and update it with the following code.
+1. Open *Beta.cshtml.cs*, and add `FeatureGate` attribute to the `BetaModel` class.
 
     ``` C#
-    public IActionResult Beta()
+    using Microsoft.AspNetCore.Mvc.RazorPages;
+    using Microsoft.FeatureManagement.Mvc;
+
+    namespace TestFeatureFlags.Pages
     {
-        return View();
+        [FeatureGate("Beta")]
+        public class BetaModel : PageModel
+        {
+            public void OnGet()
+            {
+            }
+        }
     }
     ```
 
-1. Open the *_ViewImports.cshtml* file, and register the feature manager Tag Helper using an `@addTagHelper` directive:
+1. Open *Pages/_ViewImports.cshtml*, and register the feature manager Tag Helper using an `@addTagHelper` directive.
 
     ``` cshtml
     @addTagHelper *, Microsoft.FeatureManagement.AspNetCore
     ```
 
-1. Open the *_Layout.cshtml* file 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. Open *_Layout.cshtml* in the *Pages/Shared* directory. Insert a new `<feature>` tag in between the *Home* and *Privacy* navbar items, as shown in the highlighted lines below.
 
-1. Toggle the feature flag in App Configuration. Validate that this action controls the visibility of the **Beta** item on the navigation bar.
+    :::code language="html" source="../../includes/azure-app-configuration-navbar.md" range="15-38" highlight="13-17":::
 
-## Update the web application code to use `TargetingFilter`
+## Enable targeting for the web application
 
-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.
+The targeting filter evaluates a user's feature state based on the user's targeting context, which comprises the user ID and the groups the user belongs to. In this example, you use the signed-in user's email address as the user ID and the domain name of the email address as the group.
 
-1. Add an *ExampleTargetingContextAccessor.cs* file with the following code.
+1. Add an *ExampleTargetingContextAccessor.cs* file with the following code. You implement the `ITargetingContextAccessor` interface to provide the targeting context for the signed-in user of the current request.
 
     ```csharp
-    using Microsoft.AspNetCore.Http;
     using Microsoft.FeatureManagement.FeatureFilters;
-    using System;
-    using System.Collections.Generic;
-    using System.Threading.Tasks;
 
     namespace TestFeatureFlags
     {
@@ -183,7 +175,7 @@ At this point, you can use the feature flag to enable or disable the `Beta` feat
     }
     ```
 
-1. Open the *Program.cs* file 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.
+1. Open the *Program.cs* file and enable the targeting filter by calling the `WithTargeting` method. You pass in the type `ExampleTargetingContextAccessor` that the targeting filter will use to get the targeting context during feature flag evaluation. Add `HttpContextAccessor` to the service collection to allow `ExampleTargetingContextAccessor` to access the signed-in user information from the `HttpContext`.
 
     ```csharp
     // Existing code in Program.cs
@@ -203,20 +195,34 @@ At this point, you can use the feature flag to enable or disable the `Beta` feat
     > [!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. Follow the instructions in [Roll out features to targeted audiences](./howto-targetingfilter.md) to add a targeting filter with a set of targeting rules for the *Beta* feature flag.
-
 ## Targeting filter in action
 
-To see the effects of added targeting filter to the feature flag, build and run the application again. Initially, the **Beta** item doesn't appear on the toolbar, because the _Default percentage_ option is set to 0.
+1. Build and run the web app. Initially, the **Beta** item doesn't appear on the toolbar, because the _Default percentage_ option is set to 0.
 
-Now sign in as `[email protected]`, using the password you set when registering. The **Beta** item now appears on the toolbar, because `[email protected]` is specified as a targeted user.
+> [!div class="mx-imgBorder"]
+> ![User not logged in and Beta item not displayed](./media/feature-filters/beta-not-targeted-by-default.png)
 
-Now sign in as `[email protected]`, using the password you set when registering. The **Beta** item doesn't appear on the toolbar, because `[email protected]` is specified as an excluded user.
+1. Select the **Register** link in the upper right corner to create a new user account. Use an email address of `[email protected]`.
+
+> [!div class="mx-imgBorder"]
+> ![Register a new account](./media/feature-filters/register-a-new-account.png)
+
+On the **Register Confirmation** screen, select **Click here to confirm your account**.
+
+> [!div class="mx-imgBorder"]
+> ![Register confirmation](./media/feature-filters/register-confirmation.png)
 
-The following video shows this behavior in action.
+1. Now sign in as `[email protected]`, using the password you set when registering. 
 
 > [!div class="mx-imgBorder"]
-> ![TargetingFilter in action](./media/feature-flags-targetingfilter.gif)
+> ![Login an account](./media/feature-filters/login-an-account.png)
+
+The **Beta** item now appears on the toolbar, because `[email protected]` is specified as a targeted user.
+
+> [!div class="mx-imgBorder"]
+> ![User logged in and Beta item displayed](./media/feature-filters/beta-targeted-by-user.png)
+
+Now sign in as `[email protected]`, using the password you set when registering. The **Beta** item doesn't appear on the toolbar, because `[email protected]` is specified as an excluded user.
 
 You can create more users with `@contoso.com` and `@contoso-xyz.com` email addresses to see the behavior of the group settings.
 

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

@@ -22,7 +22,7 @@ Targeting is a feature management strategy that enables developers to progressiv
 
 In this article, you will learn how to add and configure a targeting filter for your feature flags.
 
-## Add a targeting filter to a feature flag
+## Add a targeting filter
 
 1. Create a feature flag named *Beta* in your App Configuration store and open to edit it. For more information about how to add and edit a feature flag, see [Manage feature flags](./manage-feature-flags.md).
 

articles/azure-app-configuration/media/feature-filters/beta-not-targeted-by-default.png

@@ -130,15 +130,15 @@ Add a feature flag called *Beta* to the App Configuration store and leave **Labe
     }   
     ```
 
-1. Open *Pages/_ViewImports.cshtml*, and register the feature manager Tag Helper using an `@addTagHelper` directive:
+1. Open *Pages/_ViewImports.cshtml*, and register the feature manager Tag Helper using an `@addTagHelper` directive.
 
     ```cshtml
     @addTagHelper *, Microsoft.FeatureManagement.AspNetCore
     ```
 
     The preceding code allows the `<feature>` Tag Helper to be used in the project's *.cshtml* files.
 
-1. Open *_Layout.cshtml* in the *Pages*\\*Shared* directory. Insert a new `<feature>` tag in between the *Home* and *Privacy* navbar items, as shown in the highlighted lines below.
+1. Open *_Layout.cshtml* in the *Pages/Shared* directory. Insert a new `<feature>` tag in between the *Home* and *Privacy* navbar items, as shown in the highlighted lines below.
 
     :::code language="html" source="../../includes/azure-app-configuration-navbar.md" range="15-38" highlight="13-17":::
 

articles/azure-app-configuration/media/feature-filters/beta-targeted-by-user.png

@@ -30,8 +30,6 @@ In this tutorial, you will learn how to:
 
 - The [Add feature flags to an ASP.NET Core app Quickstart](./quickstart-feature-flag-aspnet-core.md) shows a simple example of how to use feature flags in an ASP.NET Core application. This tutorial shows additional setup options and capabilities of the Feature Management libraries. You can use the sample app created in the quickstart to try out the sample code shown in this tutorial. 
 
-- Install the [`Microsoft.FeatureManagement.AspNetCore`](https://www.nuget.org/packages/Microsoft.FeatureManagement.AspNetCore/) package of version **3.0.0** or later.
-
 ## Set up feature management
 
 To access the .NET feature manager, your app must have references to the `Microsoft.Azure.AppConfiguration.AspNetCore` and `Microsoft.FeatureManagement.AspNetCore` NuGet packages.
@@ -55,22 +53,7 @@ using Microsoft.FeatureManagement;
 builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));
 ```
 
-You can use [feature filters](./howto-feature-filters.md#tutorial-enable-conditional-features-with-feature-filters) for your feature flags. 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.
-
-- `TimeWindowFilter`
-- `ContextualTargetingFilter`
-- `PercentageFilter`
-
-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). To use custom filters, you must include the [Microsoft.FeatureManagement.FeatureFilters](/dotnet/api/microsoft.featuremanagement.featurefilters) namespace and add a call to [AddFeatureFilter](/dotnet/api/microsoft.featuremanagement.ifeaturemanagementbuilder.addfeaturefilter) specifying the type name of the filter you want to use as the generic type of the method.
-
-The following example shows how to use a custom feature filter called `BrowserFilter`. You can find more details in this [tutorial](./howto-feature-filters-aspnet-core.md).
-
-```csharp
-using Microsoft.FeatureManagement;
-
-builder.Services.AddFeatureManagement()
-    .AddFeatureFilter<BrowserFilter>();
-```
+You can use feature filters to enable conditional feature flags. To use either built-in feature filters or create your own, see [Enable conditional features with feature filters](./howto-feature-filters.md).
 
 Rather than hard coding your feature flags into your application, we recommend that you keep feature flags outside the application and manage them separately. Doing so allows you to modify flag states at any time and have those changes take effect in the application right away. The Azure App Configuration service provides a dedicated portal UI for managing all of your feature flags. The Azure App Configuration service also delivers the feature flags to your application directly through its .NET client libraries.