Order of Precedence when Configuring ASP.NET Core
In this post, Premier Developer Consultant Randy Patterson introduces the new configuration API for ASP.NET Core and its order of precedence.
In previous version of ASP.NET, configuration was primarily handled by the ConfigurationManager class. This class typically obtained the user configurable settings from the AppSettings section located in the XML file web.config. While these limited configuration options have worked well in the past, it poses some challenges in cloud and container environments.
The New Configuration API
With the introduction of ASP.NET Core, a new Configuration API was introduced that pulls key-value pairs from many different sources into a single Configuration collection. This allows you to access your configuration keys using a single collection regardless of where the information was sourced from.
ASP.NET Core includes several providers for loading configuration from a variety of sources including:
- JSON Files
- XML Files
- INI Files
- Command-line arguments
- Environment variables
- In-memory .NET objects
- Secret Manager storage
- Encrypted in Azure Key Vault
Additionally, you can use 3rd party providers or write your own if these configuration sources do not fit your needs.
The ASP.NET Core configuration API provides you with many choices for sourcing your configuration values used by your Web application. Additionally, you get the benefit of dynamic configuration options like Command Line Arguments and Environment Variables that work well cross-platform and when deployed to cloud or container environments. For Example, Kubernetes will often update the containers’ configuration by setting environments variables allowing the container to update its configuration as the cluster environment changes.
Order of Precedence
When ASP.NET Core starts, it loads your configuration providers in the order they are configured. Furthermore, if a configuration source is loaded and the key already exists from a previous file, it overwrites the previous value.
The last key loaded wins.
Starting with ASP.Net Core version 2.0, the configuration providers setup is hidden in Program.cs behind the method call CreateDefaultBuilder()
public static IWebHost BuildWebHost (string[] args) => WebHost.CreateDefaultBuilder(args).UseStartup<Startup>().Build();
Looking at the WebHost.cs file on Github (Open Source is great!) we can see that the order the providers are configured is as follows.
- appsettings.json file
- appsettings.{env.EnvironmentName}.json file
- The local User Secrets File #Only in local development environment
- Environment Variables
- Command Line Arguments
As you can see in the list above, Command Line Arguments are loaded last and, therefore, will always replace keys from previous providers. Lets take a look at details for each of the configuration sources.
1. appsettings.json File
The default location for your configuration settings and as the name suggests, it’s formatted as JSON. This file is loaded first and usually contains the default keys and values
Example appssettings.json
{
“ConnectionString” : “default connection string”
}
2. appsettings.{env.EnvironmentName}.json File
This file is used to override the keys in appsettings.json with deployment environment specific settings. For Example a file named appsettings.production.json would contain values specific to production.
3. User Secrets File
The User Secrets file is a JSON file stored on the local developer’s laptop. This file is unencrypted and stored outside of the solution directory and, therefore, is not checked into source control. The user secrets file is used for local development overrides like connecting to a local database server. These configuration values are only relevant to the local developer. For additional information on User Secrets File see the documentation here.
4. Environment Variables
Environment variables are a cross-platform way of storing configuration values and are available on Windows, Linux and Mac. While running on Windows you probably will not use environment variables often but they are used extensively by container orchestrators like Docker Compose and Kubernetes.
5. Command Line Arguments
Command line arguments allow you to update configuration keys when running your application without modifying any files. Any configuration value can be modified at the command line by using the command line syntax of key=value. For example, to change a key of ConnectionString at runtime you can pass the string ConnectionString=”My new connection string”
dotnet WebApplication11.dll connectionstring=”my new connection string”
For additional information on configuring you application using command line arguments see the documentation here.
Summary
The Configuration API provided by ASP.Net Core does a great job of loading configuration information from many different sources and allowing us to write the same code to access those values regardless of it’s source. The default providers and order of precedence was hidden behind the method call WebHost.CreateDefaultBuilder(args) and hopefully, this article helps you understand how that process works.
Light
Dark
0 comments