|
| 1 | +--- |
| 2 | +title: "Tutorial: Use dynamic configuration using push refresh in a .NET Core app" |
| 3 | +titleSuffix: Azure App Configuration |
| 4 | +description: In this tutorial, you learn how to dynamically update the configuration data for .NET Core apps using push refresh |
| 5 | +services: azure-app-configuration |
| 6 | +documentationcenter: '' |
| 7 | +author: abarora |
| 8 | +manager: zhenlan |
| 9 | +editor: '' |
| 10 | + |
| 11 | +ms.assetid: |
| 12 | +ms.service: azure-app-configuration |
| 13 | +ms.workload: tbd |
| 14 | +ms.devlang: csharp |
| 15 | +ms.topic: tutorial |
| 16 | +ms.date: 07/25/2020 |
| 17 | +ms.author: abarora |
| 18 | + |
| 19 | +#Customer intent: I want to use push refresh to dynamically update my app to use the latest configuration data in App Configuration. |
| 20 | +--- |
| 21 | +# Tutorial: Use dynamic configuration using push refresh in a .NET Core app |
| 22 | + |
| 23 | +The App Configuration .NET Core client library supports updating configuration on demand without causing an application to restart. An application can be configured to detect changes in App Configuration using one or both of the following two approaches. |
| 24 | + |
| 25 | +1. Poll Model: This is the default behavior that uses polling to detect changes in configuration. Once the cached value of a setting expires, the next call to `TryRefreshAsync` or `RefreshAsync` sends a request to the server to check if the configuration has changed, and pulls the updated configuration if needed. |
| 26 | + |
| 27 | +1. Push Model: This uses [App Configuration events](./concept-app-configuration-event.md) to detect changes in configuration. Once App Configuration is set up to send key value change events to Azure Event Grid, the application can use these events to optimize the total number of requests needed to keep the configuration updated. Applications can choose to subscribe to these either directly from Event Grid, or though one of the [supported event handlers](https://docs.microsoft.com/azure/event-grid/event-handlers) such as a webhook, an Azure function or a Service Bus topic. |
| 28 | + |
| 29 | +Applications can choose to subscribe to these events either directly from Event Grid, or through a web hook, or by forwarding events to Azure Service Bus. The Azure Service Bus SDK provides an API to register a message handler that simplifies this process for applications that either do not have an HTTP endpoint or do not wish to poll the event grid for changes continuously. |
| 30 | + |
| 31 | +This tutorial shows how you can implement dynamic configuration updates in your code using push refresh. It builds on the app introduced in the quickstarts. Before you continue, finish [Create a .NET Core app with App Configuration](./quickstart-dotnet-core-app.md) first. |
| 32 | + |
| 33 | +You can use any code editor to do the steps in this tutorial. [Visual Studio Code](https://code.visualstudio.com/) is an excellent option that's available on the Windows, macOS, and Linux platforms. |
| 34 | + |
| 35 | +In this tutorial, you learn how to: |
| 36 | + |
| 37 | +> [!div class="checklist"] |
| 38 | +> * Set up a subscription to send configuration change events from App Configuration to a Service Bus topic |
| 39 | +> * Set up your .NET Core app to update its configuration in response to changes in App Configuration. |
| 40 | +> * Consume the latest configuration in your application. |
| 41 | +
|
| 42 | +## Prerequisites |
| 43 | + |
| 44 | +To do this tutorial, install the [.NET Core SDK](https://dotnet.microsoft.com/download). |
| 45 | + |
| 46 | +[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)] |
| 47 | + |
| 48 | +## Set up Azure Service Bus topic and subscription |
| 49 | + |
| 50 | +This tutorial uses the Service Bus integration for Event Grid to simplify the detection of configuration changes for applications that do not wish to poll App Configuration for changes continuously. The Azure Service Bus SDK provides an API to register a message handler that can be used to update configuration when changes are detected in App Configuration. Follow steps in the [Quickstart: Use the Azure portal to create a Service Bus topic and subscription](https://docs.microsoft.com/azure/service-bus-messaging/service-bus-quickstart-topics-subscriptions-portal) to create a service bus namespace, topic and subscription. |
| 51 | + |
| 52 | +Once the resources are created, add the following environment variables. These will be used to register an event handler for configuration changes in the application code. |
| 53 | + |
| 54 | +| Key | Value | |
| 55 | +|---|---| |
| 56 | +| ServiceBusConnectionString | Connection string for the service bus namespace | |
| 57 | +| ServiceBusTopic | Name of the Service Bus topic | |
| 58 | +| ServiceBusSubscription | Name of the service bus subscription | |
| 59 | + |
| 60 | +## Set up Event subscription |
| 61 | + |
| 62 | +1. Open the App Configuration resource in the Azure portal, then click on `+ Event Subscription` in the `Events` pane. |
| 63 | + |
| 64 | +  |
| 65 | + |
| 66 | +1. Enter a name for the `Event Subscription` and the `System Topic`. |
| 67 | + |
| 68 | +  |
| 69 | + |
| 70 | +1. Select the `Endpoint Type` as `Service Bus Topic`, elect the Service Bus topic, then click on `Confirm Selection`. |
| 71 | + |
| 72 | +  |
| 73 | + |
| 74 | +1. Click on `Create` to create the event subscription. |
| 75 | + |
| 76 | +1. Click on `Event Subscriptions` in the `Events` pane to validated that the subscription was created successfully. |
| 77 | + |
| 78 | +  |
| 79 | + |
| 80 | +> [!NOTE] |
| 81 | +> When subscribing for configuration changes, one or more filters can be used to reduce the number of events sent to your application. These can be configured either as [Event Grid subscription filters](https://docs.microsoft.com/azure/event-grid/event-filtering) or [Service Bus subscription filters](https://docs.microsoft.com/azure/service-bus-messaging/topic-filters). For example, a subscription filter can be used to only subscribe to events for changes in a key that starts with a specific string. |
| 82 | +
|
| 83 | +## Register event handler to reload data from App Configuration |
| 84 | + |
| 85 | +Open *Program.cs* and update the file with the following code. |
| 86 | + |
| 87 | +```csharp |
| 88 | +using Microsoft.Azure.ServiceBus; |
| 89 | +using Microsoft.Extensions.Configuration; |
| 90 | +using Microsoft.Extensions.Configuration.AzureAppConfiguration; |
| 91 | +using System; |
| 92 | +using System.Diagnostics; |
| 93 | +using System.Text; |
| 94 | +using System.Text.Json; |
| 95 | +using System.Threading.Tasks; |
| 96 | + |
| 97 | +namespace TestConsole |
| 98 | +{ |
| 99 | + class Program |
| 100 | + { |
| 101 | + private const string AppConfigurationConnectionStringEnvVarName = "AppConfigurationConnectionString"; // e.g. Endpoint=https://{store_name}.azconfig.io;Id={id};Secret={secret} |
| 102 | + private const string ServiceBusConnectionStringEnvVarName = "ServiceBusConnectionString"; // e.g. Endpoint=sb://{service_bus_name}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key} |
| 103 | + private const string ServiceBusTopicEnvVarName = "ServiceBusTopic"; |
| 104 | + private const string ServiceBusSubscriptionEnvVarName = "ServiceBusSubscription"; |
| 105 | + |
| 106 | + private static IConfigurationRefresher _refresher = null; |
| 107 | + |
| 108 | + static async Task Main(string[] args) |
| 109 | + { |
| 110 | + string appConfigurationConnectionString = Environment.GetEnvironmentVariable(AppConfigurationConnectionStringEnvVarName); |
| 111 | + |
| 112 | + IConfiguration configuration = new ConfigurationBuilder() |
| 113 | + .AddAzureAppConfiguration(options => |
| 114 | + { |
| 115 | + options.Connect(appConfigurationConnectionString); |
| 116 | + options.ConfigureRefresh(refresh => |
| 117 | + refresh |
| 118 | + .Register("TestApp:Settings:Message") |
| 119 | + .SetCacheExpiration(TimeSpan.FromDays(30)) // Important: Reduce poll frequency |
| 120 | + ); |
| 121 | + |
| 122 | + _refresher = options.GetRefresher(); |
| 123 | + }).Build(); |
| 124 | + |
| 125 | + RegisterRefreshEventHandler(); |
| 126 | + var message = configuration["TestApp:Settings:Message"]; |
| 127 | + Console.WriteLine($"Initial value: {configuration["TestApp:Settings:Message"]}"); |
| 128 | + |
| 129 | + while (true) |
| 130 | + { |
| 131 | + await _refresher.TryRefreshAsync(); |
| 132 | + |
| 133 | + if (configuration["TestApp:Settings:Message"] != message) |
| 134 | + { |
| 135 | + Console.WriteLine($"New value: {configuration["TestApp:Settings:Message"]}"); |
| 136 | + message = configuration["TestApp:Settings:Message"]; |
| 137 | + } |
| 138 | + |
| 139 | + await Task.Delay(TimeSpan.FromSeconds(1)); |
| 140 | + } |
| 141 | + } |
| 142 | + |
| 143 | + private static void RegisterRefreshEventHandler() |
| 144 | + { |
| 145 | + string serviceBusConnectionString = Environment.GetEnvironmentVariable(ServiceBusConnectionStringEnvVarName); |
| 146 | + string serviceBusTopic = Environment.GetEnvironmentVariable(ServiceBusTopicEnvVarName); |
| 147 | + string serviceBusSubscription = Environment.GetEnvironmentVariable(ServiceBusSubscriptionEnvVarName); |
| 148 | + SubscriptionClient serviceBusClient = new SubscriptionClient(serviceBusConnectionString, serviceBusTopic, serviceBusSubscription); |
| 149 | + |
| 150 | + serviceBusClient.RegisterMessageHandler( |
| 151 | + handler: (message, cancellationToken) => |
| 152 | + { |
| 153 | + string messageText = Encoding.UTF8.GetString(message.Body); |
| 154 | + JsonElement messageData = JsonDocument.Parse(messageText).RootElement.GetProperty("data"); |
| 155 | + string key = messageData.GetProperty("key").GetString(); |
| 156 | + Console.WriteLine($"Event received for Key = {key}"); |
| 157 | + |
| 158 | + _refresher.SetDirty(); |
| 159 | + return Task.CompletedTask; |
| 160 | + }, |
| 161 | + exceptionReceivedHandler: (exceptionargs) => |
| 162 | + { |
| 163 | + Console.WriteLine($"{exceptionargs.Exception}"); |
| 164 | + return Task.CompletedTask; |
| 165 | + }); |
| 166 | + } |
| 167 | + } |
| 168 | +} |
| 169 | +``` |
| 170 | + |
| 171 | +The [SetDirty](https://docs.microsoft.com/dotnet/api/microsoft.extensions.configuration.azureappconfiguration.iconfigurationrefresher.setdirty) method is used to set the cached value for key-values registered for refresh as dirty. This ensures that the next call to `RefreshAsync` or `TryRefreshAsync` re-validates the cached values with App Configuration and updates them if needed. |
| 172 | + |
| 173 | +A random delay is added before the cached value is marked as dirty to reduce potential throttling in case multiple instances refresh at the same time. The default maximum delay before the cached value is marked as dirty is 30 seconds, but can be overridden by passing an optional `TimeSpan` parameter to the `SetDirty` method. |
| 174 | + |
| 175 | +> [!NOTE] |
| 176 | +> To reduce the number of requests to App Configuration when using push refresh, it is important to call `SetCacheExpiration(TimeSpan cacheExpiration)` with an appropriate value of `cacheExpiration` parameter. This controls the cache expiration time for pull refresh and can be used as a safety net in case there is an issue with the Event subscription or the Service Bus subscription. The recommended value is `TimeSpan.FromDays(30)`. |
| 177 | +
|
| 178 | +## Build and run the app locally |
| 179 | + |
| 180 | +1. Set an environment variable named **AppConfigurationConnectionString**, and set it to the access key to your App Configuration store. If you use the Windows command prompt, run the following command and restart the command prompt to allow the change to take effect: |
| 181 | + |
| 182 | + ```console |
| 183 | + setx AppConfigurationConnectionString "connection-string-of-your-app-configuration-store" |
| 184 | + ``` |
| 185 | + |
| 186 | + If you use Windows PowerShell, run the following command: |
| 187 | + |
| 188 | + ```powershell |
| 189 | + $Env:AppConfigurationConnectionString = "connection-string-of-your-app-configuration-store" |
| 190 | + ``` |
| 191 | + |
| 192 | + If you use macOS or Linux, run the following command: |
| 193 | + |
| 194 | + ```console |
| 195 | + export AppConfigurationConnectionString='connection-string-of-your-app-configuration-store' |
| 196 | + ``` |
| 197 | + |
| 198 | +1. Run the following command to build the console app: |
| 199 | + |
| 200 | + ```console |
| 201 | + dotnet build |
| 202 | + ``` |
| 203 | + |
| 204 | +1. After the build successfully completes, run the following command to run the app locally: |
| 205 | + |
| 206 | + ```console |
| 207 | + dotnet run |
| 208 | + ``` |
| 209 | + |
| 210 | +  |
| 211 | + |
| 212 | +1. Sign in to the [Azure portal](https://portal.azure.com). Select **All resources**, and select the App Configuration store instance that you created in the quickstart. |
| 213 | + |
| 214 | +1. Select **Configuration Explorer**, and update the values of the following keys: |
| 215 | + |
| 216 | + | Key | Value | |
| 217 | + |---|---| |
| 218 | + | TestApp:Settings:Message | Data from Azure App Configuration - Updated | |
| 219 | + |
| 220 | +1. Wait for 30 seconds to allow the event to be processed and configuration to be updated. |
| 221 | + |
| 222 | +  |
| 223 | + |
| 224 | +## Clean up resources |
| 225 | + |
| 226 | +[!INCLUDE [azure-app-configuration-cleanup](../../includes/azure-app-configuration-cleanup.md)] |
| 227 | + |
| 228 | +## Next steps |
| 229 | + |
| 230 | +In this tutorial, you enabled your .NET Core app to dynamically refresh configuration settings from App Configuration. To learn how to use an Azure managed identity to streamline the access to App Configuration, continue to the next tutorial. |
| 231 | + |
| 232 | +> [!div class="nextstepaction"] |
| 233 | +> [Managed identity integration](./howto-integrate-azure-managed-service-identity.md) |
0 commit comments