Merge pull request #266641 from zhiyuanliang-ms/zhiyuanliang/add-background-service-example

ttorble · web-flow · commit 0cacd08d0b17 · 2024-04-02T09:51:02.000+01:00
Azure App Configuration - Add feature flag example for .NET background service
diff --git a/articles/azure-app-configuration/TOC.yml b/articles/azure-app-configuration/TOC.yml
@@ -35,6 +35,8 @@
           href: quickstart-feature-flag-aspnet-core.md
         - name: .NET/.NET Framework
           href: quickstart-feature-flag-dotnet.md
+        - name: .NET Background Service
+          href: quickstart-feature-flag-dotnet-background-service.md
         - name: Java Spring
           href: quickstart-feature-flag-spring-boot.md
         - name: Azure Functions
diff --git a/articles/azure-app-configuration/enable-dynamic-configuration-dotnet-background-service.md b/articles/azure-app-configuration/enable-dynamic-configuration-dotnet-background-service.md
@@ -43,15 +43,15 @@ You use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to create a
 
 1. Create a new folder for your project.
 
-2. In the new folder, run the following command to create a new .NET background service project:
+1. In the new folder, run the following command to create a new .NET background service project:
 
     ```dotnetcli
     dotnet new worker
     ```
 
 ## Reload data from App Configuration
 
-1. Add references to the `Microsoft.Extensions.Configuration.AzureAppConfiguration` NuGet package by running the following commands:
+1. Add references to the `Microsoft.Extensions.Configuration.AzureAppConfiguration` NuGet package by running the following command:
 
     ```dotnetcli
     dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
@@ -175,7 +175,7 @@ You use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to create a
 
     ---
 
-1. Run the following command to build the console app.
+1. Run the following command to build the app.
 
     ```dotnetcli
     dotnet build
@@ -197,7 +197,7 @@ You use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to create a
     |----------------------------|-----------------------------------------------|
     | *TestApp:Settings:Message* | *Data from Azure App Configuration - Updated* |
 
-1. Wait for about 30 seconds. You should see the console outputs changed.
+1. Wait a few moments for the refresh interval time window to pass. You will see the console outputs changed.
 
     ![Screenshot of the refreshed background service.](./media/dotnet-background-service-refresh.png)
 
diff --git a/articles/azure-app-configuration/enable-dynamic-configuration-dotnet-core-push-refresh.md b/articles/azure-app-configuration/enable-dynamic-configuration-dotnet-core-push-refresh.md
@@ -233,7 +233,7 @@ The `ProcessPushNotification` method takes in a `PushNotification` object contai
     |---|---|
     | TestApp:Settings:Message | Data from Azure App Configuration - Updated |
 
-1. Wait for 30 seconds to allow the event to be processed and configuration to be updated.
+1. Wait for a few moments to allow the event to be processed. You will see the updated configuration.
 
     ![Push refresh run after updated](./media/dotnet-core-app-pushrefresh-final.png)
 
diff --git a/articles/azure-app-configuration/media/dotnet-background-service-refresh.png b/articles/azure-app-configuration/media/dotnet-background-service-refresh.png
diff --git a/articles/azure-app-configuration/media/dotnet-background-service-run.png b/articles/azure-app-configuration/media/dotnet-background-service-run.png
diff --git a/articles/azure-app-configuration/media/quickstarts/dotnet-background-service-feature-flag-disabled.png b/articles/azure-app-configuration/media/quickstarts/dotnet-background-service-feature-flag-disabled.png
diff --git a/articles/azure-app-configuration/media/quickstarts/dotnet-background-service-feature-flag.png b/articles/azure-app-configuration/media/quickstarts/dotnet-background-service-feature-flag.png
diff --git a/articles/azure-app-configuration/quickstart-dotnet-core-app.md b/articles/azure-app-configuration/quickstart-dotnet-core-app.md
@@ -35,7 +35,7 @@ You can use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to crea
 
 1. Create a new folder for your project.
 
-2. In the new folder, run the following command to create a new .NET console app project:
+1. In the new folder, run the following command to create a new .NET console app project:
 
     ```dotnetcli
     dotnet new console
@@ -49,20 +49,20 @@ You can use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to crea
     dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
     ```
 
-2. Run the following command to restore packages for your project:
+1. Run the following command to restore packages for your project:
 
     ```dotnetcli
     dotnet restore
     ```
 
-3. Open *Program.cs*, and add a reference to the .NET App Configuration provider.
+1. Open *Program.cs*, and add the following statements:
 
     ```csharp
     using Microsoft.Extensions.Configuration;
     using Microsoft.Extensions.Configuration.AzureAppConfiguration;
     ```
 
-4. Use App Configuration by calling the `AddAzureAppConfiguration` method in the `Program.cs` file.
+1. Use App Configuration by calling the `AddAzureAppConfiguration` method in the `Program.cs` file.
 
     ```csharp
     var builder = new ConfigurationBuilder();
diff --git a/articles/azure-app-configuration/quickstart-feature-flag-aspnet-core.md b/articles/azure-app-configuration/quickstart-feature-flag-aspnet-core.md
@@ -20,6 +20,7 @@ The feature management support extends the dynamic configuration feature in App
 ## Prerequisites
 
 Follow the documents to create an ASP.NET Core app with dynamic configuration.
+
 - [Quickstart: Create an ASP.NET Core app with App Configuration](./quickstart-aspnet-core-app.md)
 - [Tutorial: Use dynamic configuration in an ASP.NET Core app](./enable-dynamic-configuration-aspnet-core.md)
 
@@ -57,7 +58,7 @@ Add a feature flag called *Beta* to the App Configuration store and leave **Labe
     ```
 
     > [!TIP]
-    > When no parameter is passed to the `UseFeatureFlags` method, it loads *all* feature flags with *no label* in your App Configuration store. The default refresh expiration of feature flags is 30 seconds. You can customize this behavior via the `FeatureFlagOptions` parameter. For example, the following code snippet loads only feature flags that start with *TestApp:* in their *key name* and have the label *dev*. The code also changes the refresh expiration time to 5 minutes. Note that this refresh expiration time is separate from that for regular key-values.
+    > When no parameter is passed to the `UseFeatureFlags` method, it loads *all* feature flags with *no label* in your App Configuration store. The default refresh interval of feature flags is 30 seconds. You can customize this behavior via the `FeatureFlagOptions` parameter. For example, the following code snippet loads only feature flags that start with *TestApp:* in their *key name* and have the label *dev*. The code also changes the refresh interval time to 5 minutes. Note that this refresh interval time is separate from that for regular key-values.
     >
     > ```csharp
     > options.UseFeatureFlags(featureFlagOptions =>
@@ -165,7 +166,7 @@ Add a feature flag called *Beta* to the App Configuration store and leave **Labe
 
 1. Select **Feature manager** and locate the **Beta** feature flag. Enable the flag by selecting the checkbox under **Enabled**.
 
-1. Refresh the browser a few times. When the cache expires after 30 seconds, the page shows with updated content.
+1. Refresh the browser a few times. When the refresh interval time window passes, the page will show with updated content.
 
     ![Feature flag after enabled](./media/quickstarts/aspnet-core-feature-flag-local-after.png)
 
diff --git a/articles/azure-app-configuration/quickstart-feature-flag-azure-functions-csharp.md b/articles/azure-app-configuration/quickstart-feature-flag-azure-functions-csharp.md
@@ -68,7 +68,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
    - [Microsoft.FeatureManagement](https://www.nuget.org/packages/Microsoft.FeatureManagement/) version 2.2.0 or later
    - [Microsoft.Azure.Functions.Extensions](https://www.nuget.org/packages/Microsoft.Azure.Functions.Extensions/) version 1.1.0 or later 
 
-2. Add a new file, *Startup.cs*, with the following code. It defines a class named `Startup` that implements the `FunctionsStartup` abstract class. An assembly attribute is used to specify the type name used during Azure Functions startup.
+1. Add a new file, *Startup.cs*, with the following code. It defines a class named `Startup` that implements the `FunctionsStartup` abstract class. An assembly attribute is used to specify the type name used during Azure Functions startup.
 
     ```csharp
     using System;
@@ -94,7 +94,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
     ```
 
 
-3. Update the `ConfigureAppConfiguration` method, and add Azure App Configuration provider as an extra configuration source by calling `AddAzureAppConfiguration()`. 
+1. Update the `ConfigureAppConfiguration` method, and add Azure App Configuration provider as an extra configuration source by calling `AddAzureAppConfiguration()`. 
 
     The `UseFeatureFlags()` method tells the provider to load feature flags. All feature flags have a default cache expiration of 30 seconds before rechecking for changes. The expiration interval can be updated by setting the `FeatureFlagsOptions.CacheExpirationInterval` property passed to the `UseFeatureFlags` method. 
 
@@ -113,7 +113,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
     > [!TIP]
     > If you don't want any configuration other than feature flags to be loaded to your application, you can call `Select("_")` to only load a nonexisting dummy key `"_"`. By default, all configuration key-values in your App Configuration store will be loaded if no `Select` method is called.
 
-4. Update the `Configure` method to make Azure App Configuration services and feature manager available through dependency injection.
+1. Update the `Configure` method to make Azure App Configuration services and feature manager available through dependency injection.
 
     ```csharp
     public override void Configure(IFunctionsHostBuilder builder)
@@ -123,7 +123,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
     }
     ```
 
-5. Open *Function1.cs*, and add the following namespaces.
+1. Open *Function1.cs*, and add the following namespaces.
 
     ```csharp
     using System.Linq;
@@ -144,7 +144,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
     }
     ```
 
-6. Update the `Run` method to change the value of the displayed message depending on the state of the feature flag.
+1. Update the `Run` method to change the value of the displayed message depending on the state of the feature flag.
 
    The `TryRefreshAsync` method is called at the beginning of the Functions call to refresh feature flags. It will be a no-op if the cache expiration time window isn't reached. Remove the `await` operator if you prefer the feature flags to be refreshed without blocking the current Functions call. In that case, later Functions calls will get updated value.
 
@@ -200,7 +200,7 @@ This project will use [dependency injection in .NET Azure Functions](../azure-fu
 
 1. Select **Feature manager**, and change the state of the **Beta** key to **On**.
 
-1. Refresh the browser a few times. When the cached feature flag expires after 30 seconds, the page should have changed to indicate the feature flag `Beta` is turned on, as shown in the image below.
+1. Refresh the browser a few times. When the refresh interval time window passes, the page will change to indicate the feature flag `Beta` is turned on, as shown in the image below.
  
     ![Quickstart Function feature flag enabled](./media/quickstarts/functions-launch-ff-enabled.png)
 
diff --git a/articles/azure-app-configuration/quickstart-feature-flag-dotnet-background-service.md b/articles/azure-app-configuration/quickstart-feature-flag-dotnet-background-service.md
@@ -0,0 +1,187 @@
+---
+title: Quickstart for adding feature flags to .NET background service
+titleSuffix: Azure App Configuration
+description: A quickstart for adding feature flags to .NET background services and managing them in Azure App Configuration
+services: azure-app-configuration
+author: zhiyuanliang
+ms.service: azure-app-configuration
+ms.devlang: csharp
+ms.custom: devx-track-csharp, mode-other, devx-track-dotnet
+ms.topic: quickstart
+ms.tgt_pltfrm: .NET
+ms.date: 2/19/2024
+ms.author: zhiyuanliang
+#Customer intent: As a .NET background service developer, I want to use feature flags to control feature availability quickly and confidently.
+---
+# Quickstart: Add feature flags to a .NET background service
+
+In this quickstart, you incorporate the feature management capability from Azure App Configuration into a .NET background service. You use App Configuration to centrally store and manage your feature flags.
+
+## Prerequisites
+
+Feature management support extends the dynamic configuration feature in App Configuration. The example in this quickstart builds on the .NET background service app introduced in the dynamic configuration tutorial. Before you continue, finish the following tutorial to create a .NET background service app with dynamic configuration first.
+
+- [Tutorial: Use dynamic configuration in a .NET background service](./enable-dynamic-configuration-dotnet-background-service.md)
+
+## Add a feature flag
+
+Add a feature flag called *Beta* to the App Configuration store and leave **Label** and **Description** with their default values. For more information about how to add feature flags to a store using the Azure portal or the CLI, go to [Create a feature flag](./manage-feature-flags.md).
+
+> [!div class="mx-imgBorder"]
+> ![Screenshot showing fields to enable a feature flag named Beta.](media/add-beta-feature-flag.png)
+
+## Use the feature flag
+
+1. Add references to the `Microsoft.FeatureManagement` NuGet package by running the following command:
+
+    ```dotnetcli
+    dotnet add package Microsoft.FeatureManagement
+    ```
+
+1. Run the following command to restore packages for your project:
+
+    ```dotnetcli
+    dotnet restore
+    ```
+
+1. Open *Program.cs* and add the following statement:
+
+    ```csharp
+    using Microsoft.FeatureManagement;
+    ```
+
+1. Add a call to the `UseFeatureFlags` method inside the `AddAzureAppConfiguration` call and register feature management services.
+
+    ```csharp
+    // Existing code in Program.cs
+    // ... ...
+
+    builder.Configuration.AddAzureAppConfiguration(options =>
+    {
+        options.Connect(Environment.GetEnvironmentVariable("ConnectionString"));
+
+        // Use feature flags
+        options.UseFeatureFlags();
+
+        // Register the refresher so that the Worker service can consume it through dependency injection
+        builder.Services.AddSingleton(options.GetRefresher());
+    });
+
+    // Register feature management services
+    builder.Services.AddFeatureManagement();
+
+    // The rest of existing code in Program.cs
+    // ... ...
+    ```
+
+    > [!TIP]
+    > When no parameter is passed to the `UseFeatureFlags` method, it loads *all* feature flags with *no label* in your App Configuration store. The default refresh interval of feature flags is 30 seconds. You can customize this behavior via the `FeatureFlagOptions` parameter. For example, the following code snippet loads only feature flags that start with *TestApp:* in their *key name* and have the label *dev*. The code also changes the refresh interval time to 5 minutes. Note that this refresh interval time is separate from that for regular key-values.
+    >
+    > ```csharp
+    > options.UseFeatureFlags(featureFlagOptions =>
+    > {
+    >     featureFlagOptions.Select("TestApp:*", "dev");
+    >     featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
+    > });
+    > ```
+
+1. Open *Worker.cs* and add the following statement:
+
+    ```csharp
+    using Microsoft.FeatureManagement;
+    ```
+
+1. Update the constructor of the `Worker` service to obtain instances of `IConfigurationRefresher` and `IFeatureManager` through dependency injection.
+
+    ```csharp
+    public class Worker : BackgroundService
+    {
+        private readonly ILogger<Worker> _logger;
+        private readonly IConfigurationRefresher _refresher;
+        private readonly IFeatureManager _featureManager;
+
+        public Worker(ILogger<Worker> logger, IConfigurationRefresher refresher, IFeatureManager featureManager)
+        {
+            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+            _refresher = refresher ?? throw new ArgumentNullException(nameof(refresher));
+            _featureManager = featureManager ?? throw new ArgumentNullException(nameof(featureManager));
+        }
+
+        // ... ...
+    }
+    ```
+
+1. Update the `ExecuteAsync` method to log a message depending on the state of the feature flag. 
+
+    The `TryRefreshAsync` method is called at the beginning of every iteration of the task execution to refresh the feature flag. It will be a no-op if the refresh interval time window isn't reached. The `await` operator is not used so that the feature flags are refreshed without blocking the current iteration of the task execution. In that case, later iterations of the task execution will get updated value.
+
+    ```csharp
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            // Intentionally not await TryRefreshAsync to avoid blocking the execution.
+            _refresher.TryRefreshAsync(stoppingToken);
+
+            if (_logger.IsEnabled(LogLevel.Information))
+            {
+                if (await _featureManager.IsEnabledAsync("Beta"))
+                {
+                    _logger.LogInformation("[{time}]: Worker is running with Beta feature.", DateTimeOffset.Now);
+                }
+                else
+                {
+                    _logger.LogInformation("[{time}]: Worker is running.", DateTimeOffset.Now);
+                }
+            }
+            
+            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
+        }
+    }
+    ```
+
+## Build and run the app locally
+
+1. Run the following command to build the app:
+
+    ```dotnetcli
+    dotnet build
+    ```
+
+1. After the build successfully completes, run the following command to run the app locally:
+
+
+    ```dotnetcli
+    dotnet run
+    ```
+
+1. You should see the following outputs in the console.
+
+    ![Screenshot of the console with background service running with feature flag disabled.](./media/quickstarts/dotnet-background-service-feature-flag-disabled.png)
+
+1. Sign in to the [Azure portal](https://portal.azure.com). Select **All resources**, and select the App Configuration store that you created previously. 
+
+1. Select **Feature manager** and locate the **Beta** feature flag. Enable the flag by selecting the checkbox under **Enabled**.
+
+1. Wait a few moments for the refresh interval time window to pass. You will see the updated log message.
+
+    ![Screenshot of the console with background service running with feature flag enabled.](./media/quickstarts/dotnet-background-service-feature-flag.png)
+
+## Clean up resources
+
+[!INCLUDE [azure-app-configuration-cleanup](../../includes/azure-app-configuration-cleanup.md)]
+
+## Next steps
+
+To enable feature management capability for other types of apps, continue to the following tutorials.
+
+> [!div class="nextstepaction"]
+> [Use feature flags in .NET console apps](./quickstart-feature-flag-dotnet.md)
+
+> [!div class="nextstepaction"]
+> [Use feature flags in ASP.NET Core apps](./quickstart-feature-flag-aspnet-core.md)
+
+To learn more about managing feature flags in Azure App Configuration, continue to the following tutorial.
+
+> [!div class="nextstepaction"]
+> [Manage feature flags in Azure App Configuration](./manage-feature-flags.md)
diff --git a/articles/azure-app-configuration/quickstart-feature-flag-dotnet.md b/articles/azure-app-configuration/quickstart-feature-flag-dotnet.md
@@ -15,7 +15,7 @@ ms.author: zhiyuanliang
 ---
 # Quickstart: Add feature flags to a .NET/.NET Framework console app
 
-In this quickstart, you incorporate Azure App Configuration into a .NET console app to create an end-to-end implementation of feature management. You can use the App Configuration service to centrally store all your feature flags and control their states. 
+In this quickstart, you incorporate Azure App Configuration into a .NET console app to create an end-to-end implementation of feature management. You can use App Configuration to centrally store all your feature flags and control their states. 
 
 The .NET Feature Management libraries extend the framework with feature flag support. These libraries are built on top of the .NET configuration system. They integrate with App Configuration through its .NET configuration provider.
 
diff --git a/articles/azure-app-configuration/quickstart-feature-flag-spring-boot.md b/articles/azure-app-configuration/quickstart-feature-flag-spring-boot.md
@@ -13,7 +13,7 @@ ms.custom: devx-track-java, mode-other
 
 # Quickstart: Add feature flags to a Spring Boot app
 
-In this quickstart, you incorporate Azure App Configuration into a Spring Boot web app to create an end-to-end implementation of feature management. You can use the App Configuration service to centrally store all your feature flags and control their states.
+In this quickstart, you incorporate Azure App Configuration into a Spring Boot web app to create an end-to-end implementation of feature management. You can use App Configuration to centrally store all your feature flags and control their states.
 
 The Spring Boot Feature Management libraries extend the framework with comprehensive feature flag support. These libraries do **not** have a dependency on any Azure libraries. They seamlessly integrate with App Configuration through its Spring Boot configuration provider.
 
