Merge pull request #290444 from rossgrambo/rossgrambo/variant-feature-flags-doc-rewrite

Adds variant feature flags docs

Author: v-dirichards

articles/azure-app-configuration/TOC.yml

@@ -158,6 +158,12 @@
         href: howto-targetingfilter.md
       - name: ASP.NET Core
         href: howto-targetingfilter-aspnet-core.md
+    - name: Use variant feature flags
+      items:
+      - name: Overview
+        href: use-variant-feature-flags.md
+      - name: ASP.NET Core
+        href: use-variant-feature-flags-aspnet-core.md
   - name: Enable Azure monitoring
     items:
     - name: Monitor App Configuration

articles/azure-app-configuration/index.yml

@@ -162,6 +162,8 @@ landingContent:
           url: howto-timewindow-filter.md
         - text: Roll out features to targeted audience
           url: howto-targetingfilter.md
+        - text: Use variant feature flags
+          url: use-variant-feature-flags.md
       - linkListType: reference
         links:
         - text: .NET feature management

articles/azure-app-configuration/manage-feature-flags.md

@@ -15,7 +15,7 @@ ms.custom: "devx-track-csharp, mvc"
 
 # Quickstart: Manage feature flags in Azure App Configuration
 
-Azure App Configuration includes feature flags, which you can use to enable or disable a functionality, and variant feature flags (preview), which allow multiple variations of a feature flag.
+Azure App Configuration includes feature flags, which you can use to enable or disable a functionality, and variant feature flags, which allow multiple variations of a feature flag.
 
 The Feature manager in the Azure portal provides a UI for creating and managing the feature flags and the variant feature flags that you use in your applications.
 
@@ -59,9 +59,9 @@ az appconfig feature set --name <name> --feature Beta
 
 ---
 
-## Create a variant feature flag (preview)
+## Create a variant feature flag
 
-Add a new variant feature flag (preview) by opening your Azure App Configuration store in the Azure portal and from the **Operations** menu, select **Feature manager** > **Create**. Then select **Variant feature flag (Preview)**.
+Add a new variant feature flag by opening your Azure App Configuration store in the Azure portal and from the **Operations** menu, select **Feature manager** > **Create**. Then select **Variant feature flag**.
 
 :::image type="content" source="media\manage-feature-flags\variant-feature-flags-menu.png" alt-text="Screenshot of the Azure platform. Create a variant feature flag.":::
 

articles/azure-app-configuration/media/use-variant-feature-flags-aspnet-core/click-to-confirm.png

@@ -0,0 +1,276 @@
+---
+title: 'Tutorial: Use variant feature flags from Azure App Configuration in an ASP.NET application'
+titleSuffix: Azure App configuration
+description: In this tutorial, you learn how to use variant feature flags in an ASP.NET application
+#customerintent: As a user of Azure App Configuration, I want to learn how I can use variants and variant feature flags in my ASP.NET application.
+author: rossgrambo
+ms.author: rossgrambo
+ms.service: azure-app-configuration
+ms.devlang: csharp
+ms.topic: tutorial
+ms.date: 10/18/2024
+---
+
+# Tutorial: Use variant feature flags from Azure App Configuration in an ASP.NET application
+
+In this tutorial, you use a variant feature flag to manage experiences for different user segments in an example application, *Quote of the Day*. You utilize the variant feature flag created in [Use variant feature flags](./use-variant-feature-flags.md). Before proceeding, ensure you create the variant feature flag named *Greeting* in your App Configuration store.
+
+## Prerequisites
+
+* Ensure the [.NET CLI](/dotnet/core/tools) is installed on your machine.
+* Follow the [Use variant feature flags](./use-variant-feature-flags.md) tutorial and create the variant feature flag named *Greeting*.
+
+## Create an ASP.NET Core web app
+
+1. Run the following code in a command prompt. This command creates a new Razor Pages application in ASP.NET Core, using Individual account auth, and places it in an output folder named *QuoteOfTheDay*.
+
+    ```dotnetcli
+    dotnet new razor --auth Individual -o QuoteOfTheDay
+    ```
+
+1. Create a [user secret](/aspnet/core/security/app-secrets) for the application by navigating into the *QuoteOfTheDay* folder and run the following command. This secret holds the endpoint for your App Configuration.
+
+    ```dotnetcli
+    dotnet user-secrets set Endpoints:AppConfiguration "<App Configuration Endpoint>"
+    ```
+
+1. Add the latest versions of the required packages.
+
+    ```dotnetcli
+    dotnet add package Azure.Identity
+    dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
+    dotnet add package Microsoft.FeatureManagement.AspNetCore
+    ```
+
+## Connect to App Configuration for feature management
+
+1. In *Program.cs*, add the following using statements.
+
+    ```csharp
+    using Azure.Identity;
+    using Microsoft.Extensions.Configuration.AzureAppConfiguration;
+    using Microsoft.FeatureManagement;
+    ```
+
+1. In *Program.cs*, under the line `var builder = WebApplication.CreateBuilder(args);`, add the App Configuration provider, which pulls down the configuration from Azure App Configuration when the application starts. By default, the `UseFeatureFlags` method pulls down all feature flags with no label.
+
+    You use the `DefaultAzureCredential` to authenticate to your App Configuration store. Follow the [instructions](./concept-enable-rbac.md#authentication-with-token-credentials) to assign your credential the **App Configuration Data Reader** role. Be sure to allow sufficient time for the permission to propagate before running your application.
+
+    ```csharp
+    builder.Configuration
+        .AddAzureAppConfiguration(options =>
+        {
+            string endpoint = builder.Configuration.Get("Endpoints:AppConfiguration");
+            options.Connect(new Uri(endpoint), new DefaultAzureCredential());
+
+            options.UseFeatureFlags();
+        });
+    ```
+
+1. Add Azure App Configuration and feature management services and enable targeting for feature management.
+
+    ```csharp
+    // Add Azure App Configuration and feature management services to the container.
+    builder.Services.AddAzureAppConfiguration()
+        .AddFeatureManagement()
+        .WithTargeting();
+    ```
+
+1. Under the line `var app = builder.Build();`, add Azure App Configuration middleware for dynamic configuration refresh.
+
+    ```csharp
+    // Use Azure App Configuration middleware for dynamic configuration refresh.
+    app.UseAzureAppConfiguration();
+    ```
+
+## Use the variant feature flag
+
+1. Open *QuoteOfTheDay* > *Pages* > *Index.cshtml.cs* and replace the content with the following code.
+
+    ```csharp
+    using Microsoft.AspNetCore.Mvc;
+    using Microsoft.AspNetCore.Mvc.RazorPages;
+    using Microsoft.FeatureManagement;
+    
+    namespace QuoteOfTheDay.Pages;
+    
+    public class Quote
+    {
+        public string Message { get; set; }
+    
+        public string Author { get; set; }
+    }
+    
+    public class IndexModel(IVariantFeatureManagerSnapshot featureManager) : PageModel
+    {
+        private readonly IVariantFeatureManagerSnapshot _featureManager = featureManager;
+    
+        private Quote[] _quotes = [
+            new Quote()
+            {
+                Message = "You cannot change what you are, only what you do.",
+                Author = "Philip Pullman"
+            }];
+    
+        public Quote? Quote { get; set; }
+    
+        public string GreetingMessage { get; set; }
+    
+        public async void OnGet()
+        {
+            Quote = _quotes[new Random().Next(_quotes.Length)];
+    
+            Variant variant = await _featureManager.GetVariantAsync("Greeting", HttpContext.RequestAborted);
+
+            if (variant != null)
+            {
+                GreetingMessage = variant.Configuration?.Get<string>() ?? "";
+            }
+            else
+            {
+                _logger.LogWarning("No variant given. Either the feature flag named 'Greeting' is not defined or the variants are not defined properly.");
+            }
+        }
+    }
+    ```
+
+    You call `GetVariantAsync` to retrieve the variant of the *Greeting* feature flag for the current user and assign its value to the `GreetingMessage` property of the page model.
+
+1. In *QuoteOfTheDay* > *Pages* > *Shared* > *_Layout.cshtml*, under where `QuoteOfTheDay.styles.css` is added, add the following reference to the font-awesome CSS library.
+
+    ```css
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/all.min.css">
+    ```
+
+1. Open *index.cshtml* and replace its content with the following code.
+
+    ```cshtml
+    @page
+    @model IndexModel
+    @{
+        ViewData["Title"] = "Home page";
+        ViewData["Username"] = User.Identity?.Name ?? string.Empty;
+    }
+    
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            background-color: #f4f4f4;
+            color: #333;
+        }
+    
+        .quote-container {
+            background-color: #fff;
+            margin: 2em auto;
+            padding: 2em;
+            border-radius: 8px;
+            max-width: 750px;
+            box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.2);
+            display: flex;
+            justify-content: space-between;
+            align-items: start;
+            position: relative;
+        }
+    
+        .vote-container {
+            position: absolute;
+            top: 10px;
+            right: 10px;
+            display: flex;
+            gap: 0em;
+        }
+    
+        .vote-container .btn {
+            background-color: #ffffff; /* White background */
+            border-color: #ffffff; /* Light blue border */
+            color: #333
+        }
+    
+        .vote-container .btn:focus {
+            outline: none;
+            box-shadow: none;
+        }
+    
+        .vote-container .btn:hover {
+            background-color: #F0F0F0; /* Light gray background */
+        }
+    
+        .greeting-content {
+            font-family: 'Georgia', serif; /* More artistic font */
+        }
+    
+        .quote-content p.quote {
+            font-size: 2em; /* Bigger font size */
+            font-family: 'Georgia', serif; /* More artistic font */
+            font-style: italic; /* Italic font */
+            color: #4EC2F7; /* Medium-light blue color */
+        }
+    </style>
+    
+    <div class="quote-container">
+        <div class="quote-content">
+            <h3 class="greeting-content">@(Model.GreetingMessage)</h3>
+            <br />
+            <p class="quote">“@(Model.Quote?.Message ?? "< Quote not found >")”</p>
+            <p>- <b>@(Model.Quote?.Author ?? "Unknown")</b></p>
+        </div>
+    
+        <div class="vote-container">
+            <button class="btn btn-primary" onclick="heartClicked(this)">
+                <i class="far fa-heart"></i> <!-- Heart icon -->
+            </button>
+        </div>
+    </div>
+    
+    <script>
+        function heartClicked(button) {
+            var icon = button.querySelector('i');
+            icon.classList.toggle('far');
+            icon.classList.toggle('fas');
+        }
+    </script>
+    ```
+
+    This code displays the UI of the *Quote of the Day* application and shows the `GreetingMessage` from the page model. The JavaScript handler `heartClicked` is triggered when the heart button is clicked.
+
+### Build and run the app
+
+1. Build and run the application.
+
+    ```dotnetcli
+    dotnet build
+    dotnet run
+    ```
+1. Once the application is loaded, select **Register** at the top right to register a new user.
+
+    :::image type="content" source="media/use-variant-feature-flags-aspnet-core/register.png" alt-text="Screenshot of the Quote of the day app, showing Register.":::
+
+1. Register a new user named *[email protected]*.
+
+1. Select the link **Click here to validate email** after entering user information.
+
+    :::image type="content" source="media/use-variant-feature-flags-aspnet-core/click-to-confirm.png" alt-text="Screenshot of the Quote of the day app, showing click to confirm.":::
+
+1. Repeat the same steps to register a second user named *[email protected]*.
+
+    > [!NOTE]
+    > It's important for the purpose of this tutorial to use these names exactly. As long as the feature has been configured as expected, the two users should see different variants.
+
+1. Select **Login** at the top right to sign in as [email protected].
+
+    :::image type="content" source="media/use-variant-feature-flags-aspnet-core/login.png" alt-text="Screenshot of the Quote of the day app, showing **Login**.":::
+
+1. Once logged in, you see a long greeting message for **[email protected]**
+
+    :::image type="content" source="media/use-variant-feature-flags-aspnet-core/long-variant.png" alt-text="Screenshot of the Quote of the day app, showing a long message for the user.":::
+
+1. Click *Logout* and login as **[email protected]**, you see the simple greeting message.
+
+    :::image type="content" source="media/use-variant-feature-flags-aspnet-core/simple-variant.png" alt-text="Screenshot of the Quote of the day app, showing a simple message for the user.":::
+
+## Next steps
+
+For the full feature rundown of the .NET feature management library, refer to the following document.
+
+> [!div class="nextstepaction"]
+> [.NET Feature Management](./feature-management-dotnet-reference.md)

articles/azure-app-configuration/media/use-variant-feature-flags-aspnet-core/login.png

@@ -0,0 +1,76 @@
+---
+title: 'Use variant feature flags'
+titleSuffix: Azure App configuration
+description: In this tutorial, you learn how to set up and use variant feature flags in an App Configuration
+#customerintent: As a user of Azure App Configuration, I want to learn how I can use variants and variant feature flags in my application.
+author: rossgrambo
+ms.author: rossgrambo
+ms.service: azure-app-configuration
+ms.devlang: csharp
+ms.topic: tutorial
+ms.date: 10/18/2024
+---
+
+# Use variant feature flags
+
+Variant feature flags enable your application to support multiple variants of a feature. The variants of your feature can be assigned to specific users, groups, or percentile buckets. These flags can be useful for feature rollouts, configuration rollouts, and feature experimentation (also known as A/B testing).
+
+## What is a variant feature flag?
+
+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 variants with configurations. A variant is defined with a *Name* and an optional *Configuration Value*. The name is an identifier to tell variants apart. The configuration value can range from simple JSON primitives to complex JSON objects. You can use variants to differentiate functionalities or user experiences and optionally configure these functionalities or user experiences with variant configuration values. Additionally, a variant feature flag includes allocation rules, which define the target audience for each variant.
+
+### Variants
+
+The following example shows two variants using JSON objects for the configuration value.
+
+| Variant Name | Variant Configuration Value |
+|---|---|
+| Minimal | { "maxitems": 10, "showAds": false } |
+| Standard | { "maxitems": 30, "showAds": true } |
+
+### Allocation
+
+Allocation controls which segment of users get each variant. The following example allocates 10% of users to get the *Minimal* variant and 90% to get the *Standard* variant.
+
+| Variant | Allocation | Remarks |
+|---|---|---|
+| Minimal | 10% | Assign the variant to users in the 0th to 10th percentile. |
+| Standard | 90% | Assign the variant to users in the 10th to 100th percentile. |
+
+### Overrides
+
+You can assign variants to specific groups or users irrespective of the percentage allocation. The following example assigns users in the *Beta Tester* group the *Minimal* variant.
+
+| Group Name | Variant |
+|---|---|
+| Beta Tester | Minimal |
+
+### Default variants and kill switch
+
+Variant feature flags have two variant defaults, **DefaultWhenEnabled** and **DefaultWhenDisabled**. 
+- The **DefaultWhenEnabled** variant takes effect if the flag is enabled but the allocation doesn't assign all percentiles. Any user placed in an unassigned percentile receives the **DefaultWhenEnabled** variant.
+- The **DefaultWhenDisabled** variant takes effect if the flag is disabled, done by setting the **Enabled** field to false, also known as using the "kill switch". 
+
+The **kill switch** is used to stop users from allocating. Used when one or more of the variants have a problem- whether it's a bug, regression, or bad performance. To use the kill switch, set the **Enabled** field of the variant flag to false. All users now are given the **DefaultWhenDisabled** variant, regardless of which percentiles or overridden users/groups they were a part of.
+
+## Build an app with a variant feature flag
+
+In this tutorial, you create a web app named _Quote of the Day_. When the app is loaded, it displays a quote. Users can interact with the heart button to like it. To improve user engagement, you want to explore whether a personalized greeting message increases the number of users who like the quote. Users who receive the _None_ variant see no greeting. Users who receive the _Simple_ variant get a simple greeting message. Users who receive the _Long_ variant get a slightly longer greeting.
+
+## Prerequisites
+
+* An Azure subscription. If you don’t have one, [create one for free](https://azure.microsoft.com/free/).
+* An [App Configuration store](./quickstart-azure-app-configuration-create.md).
+
+## Create a variant feature flag
+
+1. Create a variant feature flag called *Greeting* with no label in your App Configuration store. It includes three variants: *None*, *Simple*, and *Long*, each corresponding to different greeting messages. Refer to the following table for their configuration values and allocation settings. For more information on how to add a variant feature flag, see [Create a variant feature flag](./manage-feature-flags.md#create-a-variant-feature-flag).
+
+    | Variant Name | Variant Configuration Value | Allocation| 
+    |---|---|---|
+    | None *(Default)* | null | 50% |
+    | Simple | "Hello!" | 25% |
+    | Long | "I hope this makes your day!" | 25% | 
+
+2. Continue to the following instructions to use the variant feature flag in your application for the language or platform you're using.
+    * [ASP.NET Core](./use-variant-feature-flags-aspnet-core.md)