Configuration in ASP.NET Core

The ASP.NET Core Configuration system provides an excellent mechanism for storing & reading the configuration data from various sources like JSON files, INI Files, XML files, environment variables, command-line arguments, etc. ASP.NET Core uses the Configuration Providers to read from the Configuration Sources. We can extend it by creating our own Custom Configuration Provider and read from a Custom Configuration Source. This tutorial covers the basics of the configuration system in ASP.NET Core.

What is Configuration

The Configuration is the parameters or the initial settings specific to the application. These settings are stored separately from the code and in an external file.  This gives the developers and administrators control and flexibility over the way applications are run.

For example, the Connection String required to connect to the database is stored in a configuration file. By Modifying the connection string you can change the database name, location, etc without modifying the code.

The ASP.NET Applications used the Web.config to store the Configurations. For Example, the connection string is stored as shown below

Configuration Sources

The ASP.NET Core allows us to read the configuration values from the various sources and file formats. Some of the commonly used sources are

• Json files
• INI files
• XML files
• Command-line arguments
• Environment variables
• Azure Key Vault
• Azure App Configuration
• Directory files
• Encrypted User Secrets
• In-memory .NET objects
• Custom providers

All of them store the configuration values in different formats. The configuration system reads them and combines them into a single unified configuration model.

Configuration Provider

The ASP.NET Core uses the Configuration Providers to read the configuration. Each configuration source has its own Provider. The following is the list of providers available to ASP.NET Core apps.

How Configuration is stored

We specify the configurations key-value pairs, but how we store them depends on the Configuration Source.

Following is an example configuration in JSON format. You can see that we can arrange them in a multi-level hierarchical format.

Similarly, an INI configuration file is as shown below. You can use the [mainOption] to group settings. Also, use the : as in [Logging:LogLevel] to create a multi-level hierarchy.

Configuration is flattened to Key/Value Pair

It does not matter how & where the configuration is stored, once the configuration system loads it flattens them to key/value pair

For Example, the following hierarchical json configuration

is flattened to the following key/value pair.

The important points are

1. Keys are case-insensitive. For example, ConnectionString and connectionstring are treated as equivalent keys.
2. Values are strings. (The booleans are represented as string “True” or “False”)
3. The hierarchy delimiter is a colon (:).
4. You can also use double underscore (__), which automatically converted into a colon (:).
5. In Azure Key Vault, hierarchical keys use -- as a separator. Configuration system automatically replaces it with : 

How to load the Configuration

If we create the new ASP.NET Core application using the dot new command or using the Visual Studio, then code for loading the configuration is already set up by default for us.

Default configuration

Open Visual Studio 2019 and create a new  ASP.NET Core 3.1 Empty project. If you are new to ASP.Net core, we recommend you to read the tutorial

Open program.cs It has the Main method, which is the entry point to the application. 

The Main method calls the CreateDefaultBuilder, which is a helper class. You can take a look at the source code from the GitHub.

One of the tasks performed by the CreateDefaultBuilder is to load the configuration from various sources. The following is the relevant part of the source code from CreateDefaultBuilder method.

The part of the code where configurations are loaded is in builder.ConfigureAppConfiguration method.

ConfigureAppConfiguration

The ConfigureAppConfiguration method takes two parameters. HostingContext & config.

HostingContext: is an instance of HostBuilderContext. It exposes the property HostingEnvironment, which lets us know whether we are running Development (isDevelopment), Production (IsProduction) or staging (IsStaging) environment

config: which is an instance of IConfigurationBuilder. it exposes several helper methods, which we can use to load the configuration file

The default Configuration loaded loads the configuration from the following sources

1. appsettings.json 
2. appsettings.Environment.json  For example, appsettings.Production.json and appsettings.Development.json.
3. App secrets when the app runs in the Development environment.
4. Environment variables.
5. Command-line arguments.

appsettings.json

The AddJsonFile Loads the configuration from the json file.

The first argument is the name of the json file. The path is relative to the ContentRoot.

If the second parameter is optional. if it is set to true the AddJsonfile does not throw any errors if the appsettings.json file is not found.

The third parameter reloadOnChange if true, reloads the configuration if contents of the configuration file changes. There is no need to restart the application.

The next line of code loads the which matches the name appsettings.{env.EnvironmentName}.json This allows us to have different configuration files for each environment like appsetting.development.json, etc

The ASP.NET Core determines the current environment for the ASPNETCORE_ENVIRONMENT variable.

You can read more about appsettings.json.

User secrets

This is a new feature in ASP.NET Core, where the configuration is stored outside the repository. It’s called user secrets and applicable only in the Development environment.

env.IsDevelopment() is true only if the ASPNETCORE_ENVIRONMENT is set to Development

Environment variables

The AddEnvironmentVariables reads all the user and system environment variables.

Command line arguments

The AddCommandLine loads all the command line arguments to the configuration

Custom Configuration

The built-in default configuration is sufficient for most of the applications. We can also easily extend it to suit our requirements.

The default configuration loads from the appsettings.json, command-line arguments & environment variables.

We can read the configurations from custom configuration files like custom.json or custom.ini as shown in the example below.

Create a custom.json & custom.ini. in the application root folder.

custom.json

custom.ini

Right-click on both the files select Properties and Select Copy to output directory to Copy always.

Now, open the program.cs and the update the code as shown below.

The code uses the ConfigureAppConfiguration method to load the configurations from the custom.json & custom.ini files

Reading the Configuration

Finally it is time to read the configurations in our code.

The ASP.NET core configuration systems load all the configurations from various sources and make all of them available to use in the Configuration Service.

We use the dependency injection to get the instance of configuration service (using the interface IConfiguration ) in the constructor of our startup class. Note that configuration service is one of the few classes, which is available to be injected in the startup class. The startup constructor is as shown below.

Similarly, you can inject You can use the same technique in the controller class.

To Read the values use the GetSection method of the configuration object.

In case of multi-level hierarchical configuration we can use the : to separate each level as show below

Summary

We looked at how the new  Configuration system works in ASP.NET Core. The ASP.NET Core Empty project template sets up the application to read the configuration from appsettings.json, appsettings.{env.EnvironmentName}.json, user secrets, environment variables, and command-line arguments. We can extend this by adding our own configuration files.