Tutorial: Use dynamic configuration in an ASP.NET Core app

• 02/24/2019
• 6 minutes to read
• • 
  • 
  • 
  • 
  • 
  • +3

ASP.NET Core has a pluggable configuration system that can read configuration data from a variety of sources. It can handle changes on the fly without causing an application to restart. ASP.NET Core supports the binding of configuration settings to strongly typed .NET classes. It injects them into your code by using the various IOptions<T> patterns. One of these patterns, specifically IOptionsSnapshot<T>, automatically reloads the application's configuration when the underlying data changes. You can inject IOptionsSnapshot<T> into controllers in your application to access the most recent configuration stored in Azure App Configuration.

You also can set up the App Configuration ASP.NET Core client library to refresh a set of configuration settings dynamically using a middleware. As long as the web app continues to receive requests, the configuration settings continue to get updated with the configuration store.

In order to keep the settings updated and avoid too many calls to the configuration store, a cache is used for each setting. Until the cached value of a setting has expired, the refresh operation does not update the value, even when the value has changed in the configuration store. The default expiration time for each request is 30 seconds, but it can be overridden if required.

This tutorial shows how you can implement dynamic configuration updates in your code. It builds on the web app introduced in the quickstarts. Before you continue, finish Create an ASP.NET Core app with App Configuration first.

You can use any code editor to do the steps in this tutorial. Visual Studio Code is an excellent option that's available on the Windows, macOS, and Linux platforms.

In this tutorial, you learn how to:

Prerequisites

To do this tutorial, install the .NET Core SDK.

If you don't have an Azure subscription, create a free account before you begin.

Before you continue, finish Create an ASP.NET Core app with App Configuration first.

Reload data from App Configuration

1. Add a reference to the Microsoft.Azure.AppConfiguration.AspNetCore NuGet package by running the following command:

       dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore --version 2.0.0-preview-010060003-1250
   

2. Open Program.cs, and update the CreateWebHostBuilder method to add the config.AddAzureAppConfiguration() method.

   public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
       WebHost.CreateDefaultBuilder(args)
           .ConfigureAppConfiguration((hostingContext, config) =>
           {
               var settings = config.Build();
   
               config.AddAzureAppConfiguration(options =>
               {
                   options.Connect(settings["ConnectionStrings:AppConfig"])
                          .ConfigureRefresh(refresh =>
                          {
                              refresh.Register("TestApp:Settings:BackgroundColor")
                                     .Register("TestApp:Settings:FontColor")
                                     .Register("TestApp:Settings:Message");
                          });
               });
           })
           .UseStartup<Startup>();
   

   The ConfigureRefresh method is used to specify the settings used to update the configuration data with the App Configuration store when a refresh operation is triggered. In order to actually trigger a refresh operation, a refresh middleware needs to be configured for the application to refresh the configuration data when any change occurs.

3. Add a Settings.cs file that defines and implements a new Settings class.

   namespace TestAppConfig
   {
       public class Settings
       {
           public string BackgroundColor { get; set; }
           public long FontSize { get; set; }
           public string FontColor { get; set; }
           public string Message { get; set; }
       }
   }
   

4. Open Startup.cs, and update the ConfigureServices method to bind configuration data to the Settings class.

   public void ConfigureServices(IServiceCollection services)
   {
       services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
   
       services.Configure<CookiePolicyOptions>(options =>
       {
           options.CheckConsentNeeded = context => true;
           options.MinimumSameSitePolicy = SameSiteMode.None;
       });
   
       services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
   }
   

5. Update the Configure method to add a middleware to allow the configuration settings registered for refresh to be updated while the ASP.NET Core web app continues to receive requests.

   public void Configure(IApplicationBuilder app, IHostingEnvironment env)
   {
       app.UseAzureAppConfiguration();
       app.UseMvc();
   }
   

   The middleware uses the refresh configuration specified in the AddAzureAppConfiguration method in Program.cs to trigger a refresh for each request received by the ASP.NET Core web app. For each request, a refresh operation is triggered and the client library checks if the cached value for the registered configuration settings have expired. For the cached values that have expired, the values for the settings are updated with the App Configuration store, and the remaining values remain unchanged.

   Note

   The default cache expiration time for a configuration setting is 30 seconds, but can be overridden by calling the SetCacheExpiration method on the options initializer passed as an argument to the ConfigureRefresh method.

Use the latest configuration data

1. Open HomeController.cs in the Controllers directory, and add a reference to the Microsoft.Extensions.Options package.

   using Microsoft.Extensions.Options;
   

2. Update the HomeController class to receive Settings through dependency injection, and make use of its values.

   public class HomeController : Controller
   {
       private readonly Settings _settings;
       public HomeController(IOptionsSnapshot<Settings> settings)
       {
           _settings = settings.Value;
       }
   
       public IActionResult Index()
       {
           ViewData["BackgroundColor"] = _settings.BackgroundColor;
           ViewData["FontSize"] = _settings.FontSize;
           ViewData["FontColor"] = _settings.FontColor;
           ViewData["Message"] = _settings.Message;
   
           return View();
       }
   }
   

3. Open Index.cshtml in the Views > Home directory, and replace its content with the following script:

   <!DOCTYPE html>
   <html lang="en">
   <style>
       body {
           background-color: @ViewData["BackgroundColor"]
       }
       h1 {
           color: @ViewData["FontColor"];
           font-size: @ViewData["FontSize"];
       }
   </style>
   <head>
       <title>Index View</title>
   </head>
   <body>
       <h1>@ViewData["Message"]</h1>
   </body>
   </html>
   

Build and run the app locally

1. To build the app by using the .NET Core CLI, run the following command in the command shell:

    dotnet build
   

2. After the build successfully completes, run the following command to run the web app locally:

    dotnet run
   

3. Open a browser window, and go to http://localhost:5000, which is the default URL for the web app hosted locally.

   

4. Sign in to the Azure portal. Select All resources, and select the App Configuration store instance that you created in the quickstart.

5. Select Configuration Explorer, and update the values of the following keys:

   Key	Value
   TestApp:Settings:BackgroundColor	green
   TestApp:Settings:FontColor	lightGray
   TestApp:Settings:Message	Data from Azure App Configuration - now with live updates!

6. Refresh the browser page to see the new configuration settings. More than one refresh of the browser page may be required for the changes to be reflected.

   

   Note

   Since the configuration settings are cached with a default expiration time of 30 seconds, any changes made to the settings in the App Configuration store would only be reflected in the web app when the cache has expired.

Clean up resources

If you plan to continue to the next tutorial, keep the resources you created in this quickstart for that you can reuse them.

If you're finished with the quickstart sample application, delete the Azure resources you created in this quickstart to avoid charges.

1. Sign in to the Azure portal, and select Resource groups.
2. In the Filter by name box, enter the name of your resource group.
3. In the result list, select the resource group, and either right-click the row or use the ellipsis (...) button to open the context menu.
4. Select Delete resource group.
5. You're asked to confirm the deletion of the resource group. Enter the name of your resource group to confirm, and select Delete.

After a few moments, the resource group and all its resources are deleted.

Next steps

In this tutorial, you enabled your ASP.NET Core web 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.