This second chapter is about application configuration, how to use it, and how to customize the ASP.NET configuration to employ different ways to configure your app. Perhaps you already have an existing XML configuration, or want to share a YAML configuration file over different kinds of applications. Sometimes, it also makes sense to read configuration values out of a database.

In this chapter, we will be covering the following topics:

• Configuring the configuration
• Using typed configurations
• Configuration using INI files
• Configuration providers

The topics in this chapter refer to the hosting layer of the ASP.NET Core architecture:

Figure 2.1 – ASP.NET Core architecture

To follow the descriptions in this chapter, you will need to create an ASP.NET Core MVC application. Open your console, shell, or bash terminal, and change to your working directory. Use the following command to create a new MVC application:

dotnet new mvc -n ConfigureSample -o ConfigureSample

Now, open the project in Visual Studio by double-clicking the project file or, in VS Code, by typing the following command in the already open console:

cd ConfigureSample
code.

All of the code samples in this chapter can be found in the GitHub repository for this book at https://github.com/PacktPublishing/Customizing-ASP.NET-Core-5.0/tree/main/Chapter02.

Let's start by looking at how to configure your various configuration options.

Since ASP.NET Core 2.0, the configuration is hidden in the default configuration of WebHostBuilder, and no longer part of Startup.cs. This helps to keep the startup clean and simple.

In ASP.NET Core 3.1 and ASP.NET Core 5.0, the code looks like this:

// ASP.NET Core 3.0 and later
public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }
    public static IHostBuilder CreateHostBuilder(string[]       args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            }
}

Fortunately, you are also able to override the default settings to customize the configuration in a way you need it.

When you create a new ASP.NET Core project, you will already have appsettings.json and appsettings.Development.json configured. You can, and should, use these configuration files to configure your app; this is the pre-configured way, and most ASP.NET Core developers will look for an appsettings.json file to configure the application. This is absolutely fine and works pretty well.

The following code snippet shows the encapsulated default configuration to read the appsettings.json files:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder
          .ConfigureAppConfiguration((builderContext, 
             config) =>
        {
            var env = builderContext.HostingEnvironment;
            config.SetBasePath(env.ContentRootPath);
            config.AddJsonFile(
                "appsettings.json", 
                optional: false, 
                reloadOnChange: true);
            config.AddJsonFile(
                $"appsettings.{env.EnvironmentName}.json", 
                optional: true, 
                reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .UseStartup<Startup>();
    });

This configuration also sets the base path of the application and adds the configuration via environment variables. The ConfigureAppConfiguration method accepts a lambda method that gets WebHostBuilderContext and ConfigurationBuilder passed in.

Whenever you customize the application configuration, you should add the configuration via environment variables as a final step, using the AddEnvironmentVariables() method. The order of the configuration matters, and the configuration providers that you add later on will override the configurations added previously. Be sure that the environment variables always override the configurations that are set via a file. This way, you also ensure that the configuration of your application on an Azure App Service will be passed to the application as environment variables.

IConfigurationBuilder has a lot of extension methods to add more configurations, such as XML or INI configuration files, and in-memory configurations. You can find additional configuration providers built by the community to read in YAML files, database values, and a lot more. In an upcoming section, we will see how to read INI files. First, we will look at using typed configurations.

Before trying to read INI files, it makes sense for you to see how to use typed configurations instead of reading the configuration via IConfiguration, key by key.

To read a typed configuration, you need to define the type to configure. I usually create a class called AppSettings, as follows:

public class AppSettings
{
    public int Foo { get; set; }
    public string Bar { get; set; }
}

This is a simple POCO class that will only contain the application setting values. These classes can then be filled with specific configuration sections inside the ConfigureServices method in Startup.cs:

services.Configure<AppSettings>
   (Configuration.GetSection("AppSettings"));

This way, the typed configuration also gets registered as a service in the dependency injection container and can be used everywhere in the application. You are able to create different configuration types for each configuration section. In most cases, one section should be fine, but sometimes it makes sense to divide the settings into different sections. The next snippet shows how to use the configuration in an MVC controller:

public class HomeController : Controller
{
    private readonly AppSettings _options;
    public HomeController(IOptions<AppSettings> options)
    {
        _options = options.Value;
    }

IOptions<AppSettings> is a wrapper around our AppSettings type, and the Value property contains the actual instance of AppSettings, including the values from the configuration file.

To try that, the appsettings.json file needs to have the AppSettings section configured, otherwise the values are null or not set. Let's now add the section to appsettings.json:

{
    "Logging": {
        "LogLevel": {
            "Default": "Warning"
        }
    },
    "AllowedHosts": "*",
    "AppSettings": {
        "Foo": 123,
        "Bar": "Bar"
    }
}

Next, we'll examine how INI files can be used for configuration.

To also use INI files to configure the application, you will need to add the INI configuration inside the ConfigureAppConfiguration() method in Program.cs:

config.AddIniFile(
    "appsettings.ini", 
    optional: false, 
    reloadOnChange: true);
config.AddJsonFile(
    $"appsettings.{env.EnvironmentName}.ini", 
    optional: true, 
    reloadOnChange: true);

This code loads the INI files the same way as the JSON configuration files. The first line is a required configuration, and the second line is an optional configuration depending on the current runtime environment.

The INI file could look like this:

[AppSettings]
Bar="FooBar"

As you can see, this file contains a section called AppSettings and a property called Bar.

Earlier, we said that the order of the configuration matters. If you add the two lines to configure via INI files after the configuration via JSON files, the INI files will override the settings from the JSON files. The Bar property gets overridden with "FooBar" and the Foo property stays the same, because it will not be overridden. Also, the values out of the INI file will be available via the typed configuration created previously.

Every other configuration provider will work the same way. Let's now see how a configuration provider will look.

A configuration provider is an implementation of IConfigurationProvider that is created by a configuration source, which is an implementation of IConfigurationSource. The configuration provider then reads the data from somewhere and provides it via Dictionary.

To add a custom or third-party configuration provider to ASP.NET Core, you will need to call the Add method on ConfigurationBuilder and insert the configuration source. This is just an example:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        
       webBuilder.ConfigureAppConfiguration((builderContext, 
         config) =>
        {
            var env = builderContext.HostingEnvironment;
            config.SetBasePath(env.ContentRootPath);
            config.AddJsonFile(
                "appsettings.json", 
                optional: false, 
                reloadOnChange: true);
            config.AddJsonFile(
                $"appsettings.{env.EnvironmentName}.json",
                optional: true, 
                reloadOnChange: true);
            // add new configuration source
            config.Add(new MyCustomConfigurationSource
            {
                SourceConfig = //configure whatever source
                Optional = false,
                ReloadOnChange = true
            });
            config.AddEnvironmentVariables();
        })
        .UseStartup<Startup>();
    });

Usually, you would create an extension method to add the configuration source more easily:

config.AddMyCustomSource("source", optional: false, 
     reloadOnChange: true);

A really detailed concrete example about how to create a custom configuration provider has been written by Andrew Lock. You can find this in the Further reading section of this chapter.

In most cases, you will not need to add a different configuration provider or to create your own configuration provider, but it's good to know how to change it, just in case. Also, using typed configuration is a nice way to read and provide the settings. In classic ASP.NET, we used a manually created façade to read the application settings in a typed manner. Now, this is automatically done by just providing a type. This type will be automatically instantiated, filled, and provided, via a dependency injection.

To learn more about customizing dependency injection in ASP.NET Core 5.0, let's have a look at the next chapter.

Andrew Lock, Creating a custom ConfiguationProvider in ASP.NET Core: https://andrewlock.net/creating-a-custom-iconfigurationprovider-in-asp-net-core-to-parse-yaml/.