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

09/1/2020
8 minutes to read

ASP.NET Core has a pluggable configuration system that can read configuration data from a variety of sources. It can handle changes dynamically 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. The configuration settings get updated with the configuration store each time as long as the web app receives requests.

App Configuration automatically caches each setting to avoid too many calls to the configuration store. The refresh operation waits until the cached value of a setting expires to update that setting, even when its value changes in the configuration store. The default cache expiration time is 30 seconds. You can override this expiration time, if necessary.

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:

Set up your application to update its configuration in response to changes in an App Configuration store.
Inject the latest configuration in your application's controllers.

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.

Add a sentinel key

A sentinel key is a special key used to signal when configuration has changed. Your app monitors the sentinel key for changes. When a change is detected, you refresh all configuration values. This approach reduces the overall number of requests made by your app to App Configuration, compared to monitoring all keys for changes.

In the Azure portal, select Configuration Explorer > Create > Key-value.
For Key, enter TestApp:Settings:Sentinel. For Value, enter 1. Leave Label and Content type blank.
Select Apply.

Note

If you aren't using a sentinel key, you need to manually register every key you want to watch.

Reload data from App Configuration

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

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
            webBuilder.ConfigureAppConfiguration((hostingContext, config) =>
            {
                var settings = config.Build();
                config.AddAzureAppConfiguration(options =>
                {
                    options.Connect(settings["ConnectionStrings:AppConfig"])
                           .ConfigureRefresh(refresh =>
                                {
                                    refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)
                                           .SetCacheExpiration(new TimeSpan(0, 5, 0));
                                });
                });
            })
        .UseStartup<Startup>());

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
            webBuilder.ConfigureAppConfiguration((hostingContext, config) =>
            {
                var settings = config.Build();
                config.AddAzureAppConfiguration(options =>
                {
                    options.Connect(settings["ConnectionStrings:AppConfig"])
                           .ConfigureRefresh(refresh =>
                                {
                                    refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)
                                           .SetCacheExpiration(new TimeSpan(0, 5, 0));
                                });
                });
            })
        .UseStartup<Startup>());

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:Sentinel", refreshAll: true)
                                       .SetCacheExpiration(new TimeSpan(0, 5, 0));
                            });
            });
        })
        .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. The refreshAll parameter to the Register method indicates that all configuration values should be refreshed if the sentinel key changes.

Also, the SetCacheExpiration method overrides the default cache expiration time of 30 seconds, specifying a time of 5 minutes instead. This reduces the number of requests made to App Configuration.

Note

For testing purposes, you may want to lower the cache expiration time.

To actually trigger a refresh operation, you'll need to configure a refresh middleware for the application to refresh the configuration data when any change occurs. You'll see how to do this in a later step.

Add a Settings.cs file in the Controllers directory that defines and implements a new Settings class. Replace the namespace with the name of your project.

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; }
    }
}

Open Startup.cs, and use IServiceCollection.Configure<T> in the ConfigureServices method to bind configuration data to the Settings class.

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
    services.AddControllersWithViews();
    services.AddAzureAppConfiguration();
}

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
    services.AddControllersWithViews();
    services.AddAzureAppConfiguration();
}

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddAzureAppConfiguration();
}

Tip

To learn more about the options pattern when reading configuration values, see Options Patterns in ASP.NET Core.

Update the Configure method, adding the UseAzureAppConfiguration 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, IWebHostEnvironment env)
{
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
            app.UseHsts();
        }

        // Add the following line:
        app.UseAzureAppConfiguration();

        app.UseHttpsRedirection();

        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
                name: "default",
                pattern: "{controller=Home}/{action=Index}/{id?}");
        });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
            app.UseHsts();
        }

        // Add the following line:
        app.UseAzureAppConfiguration();

        app.UseHttpsRedirection();

        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
                name: "default",
                pattern: "{controller=Home}/{action=Index}/{id?}");
        });
}

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

    services.Configure<CookiePolicyOptions>(options =>
    {
        options.CheckConsentNeeded = context => true;
        options.MinimumSameSitePolicy = SameSiteMode.None;
    });

    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 setting has expired. If it's expired, it's refreshed.

Note

To ensure the configuration is refreshed, add the middleware as early as appropriate to your request pipeline so it will not be short-circuited by another middleware in your application.

Use the latest configuration data

Open HomeController.cs in the Controllers directory, and add a reference to the Microsoft.Extensions.Options package.
```
using Microsoft.Extensions.Options;
```
Update the HomeController class to receive Settings through dependency injection, and make use of its values.

    public class HomeController : Controller
    {
        private readonly Settings _settings;
        private readonly ILogger<HomeController> _logger;

        public HomeController(ILogger<HomeController> logger, IOptionsSnapshot<Settings> settings)
        {
            _logger = logger;
            _settings = settings.Value;
        }

        public IActionResult Index()
        {
            ViewData["BackgroundColor"] = _settings.BackgroundColor;
            ViewData["FontSize"] = _settings.FontSize;
            ViewData["FontColor"] = _settings.FontColor;
            ViewData["Message"] = _settings.Message;

            return View();
        }

        // ...
    }

    public class HomeController : Controller
    {
        private readonly Settings _settings;
        private readonly ILogger<HomeController> _logger;

        public HomeController(ILogger<HomeController> logger, IOptionsSnapshot<Settings> settings)
        {
            _logger = logger;
            _settings = settings.Value;
        }

        public IActionResult Index()
        {
            ViewData["BackgroundColor"] = _settings.BackgroundColor;
            ViewData["FontSize"] = _settings.FontSize;
            ViewData["FontColor"] = _settings.FontColor;
            ViewData["Message"] = _settings.Message;

            return View();
        }

        // ...
    }

    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();
        }
    }

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"]px;
    }
</style>
<head>
    <title>Index View</title>
</head>
<body>
    <h1>@ViewData["Message"]</h1>
</body>
</html>

Build and run the app locally

To build the app by using the .NET Core CLI, run the following command in the command shell:
```
    dotnet build
```
After the build successfully completes, run the following command to run the web app locally:
```
    dotnet run
```
Open a browser window, and go to the URL shown in the dotnet run output.
Sign in to the Azure portal. Select All resources, and select the App Configuration store instance that you created in the quickstart.

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!
TestApp:Settings:Sentinel	2

Refresh the browser page to see the new configuration settings. You may need to refresh more than once for the changes to be reflected, or change your automatic refresh rate to less than 5 minutes.

Clean up resources

If you do not want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

Important

Deleting a resource group is irreversible. The resource group and all the resources in it are permanently deleted. Make sure that you don't accidentally delete the wrong resource group or resources. If you created the resources for this article inside a resource group that contains other resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

Sign in to the Azure portal, and select Resource groups.
In the Filter by name box, enter the name of your resource group.
In the result list, select the resource group name to see an overview.
Select Delete resource group.
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.

Managed identity integration

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

Prerequisites

Add a sentinel key

Reload data from App Configuration

Use the latest configuration data

Build and run the app locally

Clean up resources

Next steps

Is this page helpful?

Feedback

Is this page helpful?