Tutorial: Use dynamic configuration in an Aspire solution

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 first.

In this tutorial, you learn how to:

Prerequisites

Finish the quickstart: Create an Aspire solution with Azure App Configuration.

Reload data from App Configuration

1. Navigate into the Web project's directory (created in the Prerequisites steps). Run the following command to add the Microsoft.Azure.AppConfiguration.AspNetCore Nuget package.

   dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
   

2. Open AppHost.cs, and update the AddAzureAppConfiguration method you added during the quickstart.

   builder.AddAzureAppConfiguration(
       "appconfiguration",
       configureOptions: options =>
       {
           // Load all keys that start with `TestApp:` and have no label.
           options.Select("TestApp:*", LabelFilter.Null);
           // Reload configuration if any selected key-values have changed.
           options.ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
       });
   

   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.

   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.

3. Add Azure App Configuration middleware to the service collection of your app.

   Update Program.cs with the following code.

   // Existing code in Program.cs
   // ... ...
   
   // Add Azure App Configuration middleware to the container of services.
   builder.Services.AddAzureAppConfiguration();
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

4. Call the UseAzureAppConfiguration method. It enables your app to use the App Configuration middleware to update the configuration for you automatically.

   Update Program.cs with the following code.

   // Existing code in Program.cs
   // ... ...
   
   var app = builder.Build();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }
   
   // Use Azure App Configuration middleware for dynamic configuration refresh.
   app.UseAzureAppConfiguration();
   
   // The rest of existing code in program.cs
   // ... ...
   

Request-driven configuration refresh

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.

• 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.
• 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.
• 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.

Next steps

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: