|
| 1 | +--- |
| 2 | +title: "Tutorial: Use dynamic configuration in an Aspire solution" |
| 3 | +titleSuffix: Azure App Configuration |
| 4 | +description: In this tutorial, you learn how to dynamically update the configuration data for Aspire solutions. |
| 5 | +services: azure-app-configuration |
| 6 | +author: zhiyuanliang-ms |
| 7 | +ms.service: azure-app-configuration |
| 8 | +ms.devlang: csharp |
| 9 | +ms.custom: devx-track-csharp, mode-other |
| 10 | +ms.topic: quickstart |
| 11 | +ms.date: 12/4/2025 |
| 12 | +zone_pivot_groups: appconfig-aspire |
| 13 | +ms.author: zhiyuanliang |
| 14 | +#Customer intent: As an Aspire developer, I want to learn the centralized configuration cloud-native solution for Aspire. |
| 15 | +--- |
| 16 | + |
| 17 | +# Tutorial: Use dynamic configuration in an Aspire solution |
| 18 | + |
| 19 | +This tutorial shows how you can enable dynamic configuration updates in an Aspire solution. It builds on the web app introduced in the quickstart. Your app will leverage the App Configuration provider library for its built-in configuration caching and refreshing capabilities. Before you continue, finish [Create an Aspire solution with Azure App Configuration](./quickstart-aspire.md) first. |
| 20 | + |
| 21 | +In this tutorial, you learn how to: |
| 22 | + |
| 23 | +> [!div class="checklist"] |
| 24 | +> * Set up your app to update its configuration in response to changes in an App Configuration store. |
| 25 | +> * Inject the latest configuration into your app. |
| 26 | +
|
| 27 | +## Prerequisites |
| 28 | + |
| 29 | +Finish the quickstart: [Create an Aspire solution with Azure App Configuration](./quickstart-aspire.md). |
| 30 | + |
| 31 | +## Reload data from App Configuration |
| 32 | + |
| 33 | +1. Navigate into the `Web` project's directory (created in the [Prerequisites](./enable-dynamic-configuration-aspire.md#prerequisites) steps). Run the following command to add the [`Microsoft.Azure.AppConfiguration.AspNetCore`](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore) Nuget package. |
| 34 | + |
| 35 | + ```dotnetcli |
| 36 | + dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore |
| 37 | + ``` |
| 38 | +
|
| 39 | +1. Open *AppHost.cs*, and update the `AddAzureAppConfiguration` method you added during the quickstart. |
| 40 | +
|
| 41 | + ```csharp |
| 42 | + builder.AddAzureAppConfiguration( |
| 43 | + "appconfiguration", |
| 44 | + configureOptions: options => |
| 45 | + { |
| 46 | + // Load all keys that start with `TestApp:` and have no label. |
| 47 | + options.Select("TestApp:*", LabelFilter.Null); |
| 48 | + // Reload configuration if any selected key-values have changed. |
| 49 | + options.ConfigureRefresh(refreshOptions => |
| 50 | + refreshOptions.RegisterAll()); |
| 51 | + }); |
| 52 | + ``` |
| 53 | +
|
| 54 | + The `Select` method is used to load all key-values whose key name starts with *TestApp:* and that have *no label*. You can call the `Select` method more than once to load configurations with different prefixes or labels. If you share one App Configuration store with multiple apps, this approach helps load configuration only relevant to your current app instead of loading everything from your store. |
| 55 | + |
| 56 | + Inside the `ConfigureRefresh` method, you call the `RegisterAll` method to instruct the App Configuration provider to reload the entire configuration whenever it detects a change in any of the selected key-values (those starting with *TestApp:* and having no label). For more information about monitoring configuration changes, see [Best practices for configuration refresh](./howto-best-practices.md#configuration-refresh). |
| 57 | +
|
| 58 | +1. Add Azure App Configuration middleware to the service collection of your app. |
| 59 | +
|
| 60 | + Update *Program.cs* with the following code. |
| 61 | +
|
| 62 | + ```csharp |
| 63 | + // Existing code in Program.cs |
| 64 | + // ... ... |
| 65 | +
|
| 66 | + // Add Azure App Configuration middleware to the container of services. |
| 67 | + builder.Services.AddAzureAppConfiguration(); |
| 68 | +
|
| 69 | + var app = builder.Build(); |
| 70 | +
|
| 71 | + // The rest of existing code in program.cs |
| 72 | + // ... ... |
| 73 | + ``` |
| 74 | +
|
| 75 | +1. Call the `UseAzureAppConfiguration` method. It enables your app to use the App Configuration middleware to update the configuration for you automatically. |
| 76 | +
|
| 77 | + Update *Program.cs* with the following code. |
| 78 | +
|
| 79 | + ```csharp |
| 80 | + // Existing code in Program.cs |
| 81 | + // ... ... |
| 82 | +
|
| 83 | + var app = builder.Build(); |
| 84 | +
|
| 85 | + if (!app.Environment.IsDevelopment()) |
| 86 | + { |
| 87 | + app.UseExceptionHandler("/Error"); |
| 88 | + app.UseHsts(); |
| 89 | + } |
| 90 | +
|
| 91 | + // Use Azure App Configuration middleware for dynamic configuration refresh. |
| 92 | + app.UseAzureAppConfiguration(); |
| 93 | +
|
| 94 | + // The rest of existing code in program.cs |
| 95 | + // ... ... |
| 96 | + ``` |
| 97 | +
|
| 98 | +## Request-driven configuration refresh |
| 99 | +
|
| 100 | +The configuration refresh is triggered by the incoming requests to your web app. No refresh will occur if your app is idle. When your app is active, the App Configuration middleware monitors any keys you registered for refreshing in the `ConfigureRefresh` call. The middleware is triggered upon every incoming request to your app. However, the middleware will only send requests to check the value in App Configuration when the refresh interval you set has passed. |
| 101 | +
|
| 102 | +- If a request to App Configuration for change detection fails, your app will continue to use the cached configuration. New attempts to check for changes will be made periodically while there are new incoming requests to your app. |
| 103 | +- The configuration refresh happens asynchronously to the processing of your app's incoming requests. It will not block or slow down the incoming request that triggered the refresh. The request that triggered the refresh may not get the updated configuration values, but later requests will get new configuration values. |
| 104 | +- To ensure the middleware is triggered, call the `app.UseAzureAppConfiguration()` method as early as appropriate in your request pipeline so another middleware won't skip it in your app. |
| 105 | +
|
| 106 | +:::zone target="docs" pivot="azure" |
| 107 | +
|
| 108 | +## Run the app locally |
| 109 | +
|
| 110 | +1. Run the `AppHost` project. Go to the Aspire dashboard and open the web app. |
| 111 | +
|
| 112 | + :::image type="content" source="media/aspire/original-message.png" alt-text="Screenshot of a web app with the original message from Azure App Configuration." lightbox="media/aspire/original-message.png"::: |
| 113 | +
|
| 114 | +1. In the Azure portal, navigate to the **Configuration explorer** of your App Configuration store, and update the value of the following key. |
| 115 | +
|
| 116 | + | Key | Value | |
| 117 | + |----------------------------|-------------------------------------------------| |
| 118 | + | *TestApp:Settings:Message* | *Hello from Azure App Configuration - Updated!* | |
| 119 | +
|
| 120 | +1. Refresh the browser a few times. When the refresh interval elapses after 30 seconds, the page shows with updated content. |
| 121 | +
|
| 122 | + :::image type="content" source="media/aspire/refreshed-message.png" alt-text="Screenshot of a web app with the updated message from Azure App Configuration." lightbox="media/aspire/refreshed-message.png"::: |
| 123 | +
|
| 124 | +1. Go to the Aspire dashboard and open the structured logs. You see that the `webfrontend` resource has a log with message "Configuration reloaded.". |
| 125 | +
|
| 126 | + :::image type="content" source="media/aspire/dashboard-logs.png" alt-text="Screenshot of the Aspire dashboard showing structured logs." lightbox="media/aspire/dashboard-logs.png"::: |
| 127 | +
|
| 128 | +:::zone-end |
| 129 | +
|
| 130 | +:::zone target="docs" pivot="emulator" |
| 131 | +
|
| 132 | +## Run the app locally |
| 133 | +
|
| 134 | +1. Run the `AppHost` project. Go to the Aspire dashboard and open the web app. |
| 135 | +
|
| 136 | + :::image type="content" source="media/aspire/original-message.png" alt-text="Screenshot of a web app with the original message from Azure App Configuration." lightbox="media/aspire/original-message.png"::: |
| 137 | +
|
| 138 | +1. Go to the emulator UI, edit the value of the following key. |
| 139 | +
|
| 140 | + | Key | Value | |
| 141 | + |----------------------------|-------------------------------------------------| |
| 142 | + | *TestApp:Settings:Message* | *Hello from Azure App Configuration - Updated!* | |
| 143 | +
|
| 144 | +1. Refresh the browser a few times. When the refresh interval elapses after 30 seconds, the page shows with updated content. |
| 145 | +
|
| 146 | + :::image type="content" source="media/aspire/refreshed-message.png" alt-text="Screenshot of a web app with the updated message from Azure App Configuration." lightbox="media/aspire/refreshed-message.png"::: |
| 147 | +
|
| 148 | +1. Go to the Aspire dashboard and open the structured logs. You see that the `webfrontend` resource has a log with message "Configuration reloaded.". |
| 149 | +
|
| 150 | + :::image type="content" source="media/aspire/dashboard-logs.png" alt-text="Screenshot of the Aspire dashboard showing structured logs." lightbox="media/aspire/dashboard-logs.png"::: |
| 151 | +
|
| 152 | +:::zone-end |
| 153 | +
|
| 154 | +## Next steps |
| 155 | +
|
| 156 | +In this tutorial, you enabled your Aspire app to dynamically refresh configuration settings from App Configuration. To learn how to enable dynamic configuration in an ASP.NET Web Application, continue to the next tutorial: |
| 157 | +
|
| 158 | +> [!div class="nextstepaction"] |
| 159 | +> [Enable dynamic configuration in ASP.NET Web Applications](./enable-dynamic-configuration-aspnet-netfx.md) |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments