ASP.NET 5 Configuration – Using the Built-In Providers

In older versions of ASP.NET, configuration information was stored in XML files, with a machine.config file for machine-wide settings and one or more web.config files for ASP.NET site settings.  ASP.NET 5 introduces a new configuration system, allowing configuration information to come from files (JSON, XML, INI), environment variables, or custom configuration providers.

In this post, we’ll look at some of the built-in configuration providers that come with ASP.NET 5, starting with the JSON file configuration provider.  For the command line example, we need only three files: project.json, appsettings.json, and Startup.cs.  Links to source code for both the command line project and a Visual Studio 2015 project follow the code listings.

The project.json file is straightforward, including only a dependency on the Kestrel server, and a command to launch the site. Note that we don’t list a dependency on any of the configuration packages (Microsoft.Extensions.Configuration.*). It turns out that the Kestrel server package has a dependency on Microsoft.AspNet.Hosting, which in turn has dependencies on Microsoft.Extensions.Configuration and Microsoft.Extensions.Configuration.Json, so our dependency on Microsoft.AspNet.Server.Kestrel includes the packages we need to work with JSON configuration files.

The appsettings.json file contains a simple setting entry and a hierarchical entry for data related settings:

The Startup.cs file is where we load our configuration file and, in this example, access the configuration settings. To load the appsettings.json file, we create a new ConfigurationBuilder and call the AddJsonFile extension method, passing in the name of the settings file.  We then call the ConfigurationBuilder’s Build method, storing the results in the _configuration variable.  To get the configuration values, we use the setting name as a key. Note the use of colons as path separators for hierarchically organized settings.

To run this example from the command line, navigate to the directory where the source files are located and run the following commands:

Running the example and browsing to the site returns a page displaying the configuration setting values:


Source code for the command line project and Visual Studio 2015 project can be found at github:

In our next example we’ll use multiple configuration sources, including an XML file and environment variables, and we’ll see that sources added later to the ConfigurationBuilder take precedence over those added earlier.

To work with XML files, we add Microsoft.Extensions.Configuration.Xml to our dependencies list since it is not in the dependencies list of Microsoft.AspNet.Hosting.  Building on the the first example, update the project.json file to include the dependency:

Update appsettings.json to have a setting1setting2 and setting3 entry with values identifying the source of data as JSON:

Next, add an appsettings.xml file.  Note that it has values for setting2 and setting3.  It also defines a new data setting, commandTimeout:

To set environment variables when running on Windows, we’ll create a PowerShell script.  This script will set values for setting3 and data:connectionStrings:default that only last for the duration of the command window:

Finally, update Startup.cs to add appsettings.xml and environment variables as configuration sources and add code to display the new settings values in the Configure method.

To run the example on Windows, execute the setvars.ps1 script and do another dnu restore (since we have modified dependencies):

To run the example on Linux, set the environment variables, then run dnu restore and dnx web. Note the use of double underscores in place of colons, which can’t be used in environment variable names:

Browsing to the site returns a page displaying the following configuration values:


Note that when settings appear in multiple configuration sources, the value from the source that is added last is used.  In this example, setting3 was defined in all three configuration sources, but the value from the environment variable was used since they were the last configuration source added to the ConfigurationBuilder.

For projects in Visual Studio, you can set environment variables on the project properties page:


Source code for example 2 can be found here:

In this post, we’ve used the built-in configuration providers for JSON files, XML files, and environment variables.  Providers also exist for INI files, command line arguments, and in-memory configuration sources, but I do not plan to cover them as I cannot think of a configuration scenario that wouldn’t be served as well as or better using JSON files, XML files, environment variables, or a custom provider.  Should I learn of a practical use case for these providers, I will update this post to add examples.

In the next post we will look at conditionally loading configuration sources based on the hosting environment.

Leave a Reply