Work With Configuration In ASP.NET Core

Before going into the new configuration system, let’s discuss in brief how we used to have a configuration system in the earlier versions of .NET applications.

• We have a Configuration assembly in .NET framework which is used for reading the configuration elements.
• For any custom elements we used to create ConfigurationElement derived class, and if we have multiple repeated elements we used to have a ConfigurationElementCollection. This way of implementation is like a pester in the earlier versions of .NET because for every custom element, there should be a custom class and then access those custom class elements in the application.
• And, another thing is web.config file which basically is used as configuration values, and it doesn’t support other forms of files.

ASP.NET Core Configuration System

• ASP.NET Core/ .NET Core is the restructuring of the existing way of implementation into a set of NuGet Packages. Even though the configuration system is a set of NuGet Packages, the primary package is Microsoft.Extensions.Configuration.
• The new configuration system is not just the web.config file. It also supports multiple files (JSON, INI etc). Basically Configuration read at runtime.
• There are several different configuration providers for file formats, like JSON, XML and INI file and it also supports in-memory configuration.
• It also supports command line and Environment variables.
• All of these are parts of each individual NuGet Package.

The new configuration system is like a hierarchical element configuration. Let’s move onto the next line to understand better what exactly hierarchical element configuration means.

When we create a new project with ASP.NET Core template, by default, it provides some support for the configuration values.

The project structure looks like below,



If you are not aware of this project structure, I recommend you go through the link below before continuing with configuration system in ASP.NET Core project.

http://www.c-sharpcorner.com/article/installing-and-understanding-the-asp-net-core-web-api-project-structure/  

If we look at the startup file the first thing we observe is like ConfigurationBuilder

var builder = new ConfigurationBuilder()
                .SetBasePath(env.ContentRootPath)
                .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
                .AddEnvironmentVariables();
Configuration = builder.Build();

• ConfigurationBuilder is one of the primary classes in the new configuration system. Basically It sets up the configuration for the application, it creates the new ConfigurationBuilder class and sets the base path where to look for the configuration provider files and it is adding the JSON file appsettings.json and saying it is an optional which means if the file is not present it will not detonate.
• It is also providing an environment specific JSON file to override the values for that particular environment like development or production configuration.
• One important note is that the environment specific file takes the priority here.
• And also the last line describes that it adds support for environment variables as well.

At the end, it calls the Build(), which returns the IConfiguration root object. The configuration builder follows builder design pattern. Let’s move on to the sample code to understand configuration system in clear.

Lets open appsettings.json file and create some new set of values as shown in the below.

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "applicationInfo": {
    "application": {
      "files": [
        {
          "resourceType": "custom",
          "resourceUrl": "https://<websiteAddress>/StorageID/applicationName/resource1"
        },
        {
          "resourceType": "pictures",
          "resourceUrl": "https://<websiteAddress>/SID/applicationName/pictures/rs2"
        }
      ]
    },
    "runmode": {
      "id": "AO839PJ",
      "framework": "dotnetFX45"
    },
    "safemode": true
  }
}

This sample json specifies some application information with some resources/files and pictures locations. We need to use this custom configuration values in our WebAPI end point. As we know there is a default controller created by the template, we can access those values from that controller.

In the startup class, there is a configuration root created at the end of the startup (the below line)

public IConfigurationRoot Configuration { get; }

This is the class that needs to be available everywhere to access those values inside the JSON file. To make this available into the controllers, we have to inject this configuration for each controller. We can add this as a singleton class because we don’t want a separate instance for each controller. Add the below line in ConfigureServices method in startup class.

services.AddSingleton<IConfiguration>(Configuration);

So, this makes a configuration object available for all the controllers wherever it is referred in the constructor. To understand better let’s add the below code in values controller.

public class ValuesController : Controller
    {
        IConfiguration _configuration;

        public ValuesController(IConfiguration config)
        {
            _configuration = config;
        }

        // GET api/values
        [HttpGet]
        public string[] Get()
        {
            List<string> configValues = new List<string>();
            configValues.Add(_configuration.GetValue<string>("applicationInfo:runmode:framework"));
            configValues.Add(_configuration.GetValue<string>("applicationInfo:safemode"));
            configValues.Add(_configuration.GetValue<string>("applicationInfo:files:0:resourceType"));
            configValues.Add(_configuration.GetValue<string>("applicationInfo:files:1:resourceUrl"));
            return configValues.ToArray();
        }

    }

Here we added a configuration parameter to the constructor and created a class level property _configuration that can be used as an endpoint. Initialized the property in the constructor and using that configuration object we can access the configuration values. We have a method called GetValue where we can specify the type of element value being retrieved and the key. As we know configuration system supports hierarchical elements we can access the multi level elements as shown above. For demonstration purpose, the values are displayed on the browser. In real time, we will be using this configuration values to perform any business logic/connecting to a server. Once you run the application the output should look like below.



This is about reading simple properties from configuration files. Another interesting feature of configuration system is, it supports reading entire section into POCO class. This can be achieved by something called IOptions. Let see the below example to work with IOptions.

To Configure options we should add another NuGet Package called Microsoft.Extensions.Options.ConfigurationExtensions. And also we need to tell the dependency injection system which section of the configuration file need to be used to create a RunMode class. It’s a kind of mapping between class and configuration section. Let's add the below line in ConfigurationServices method in startup class.

services.Configure<RunMode>(Configuration.GetSection("runmode"));

I have already created a RunMode class for mapping the configuration values. The RunMode class should look like below,

using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace SampleWebApiCoreProject
{
    public class RunMode
    {
        public string Id { get; set; }
        public string Framework { get; set; }
    }
}

Now, let's go back to the controller and inject a parameter into the constructor IOptions<RunMode> runModeInstance. So, this option class will provide as a runModeInstance and it (ie IOptions) has a property called Value which holds the actual POCO class. After adding this IOptions to the values controller constructor should looks like below,

IConfiguration _configuration;
RunMode _runModeInstance;

public ValuesController(IConfiguration config, IOptions<RunMode> runModeInstance)
{
    _configuration = config;
    _runModeInstance = runModeInstance.Value;
}

Once you instantiated the endpoint with Options, we can directly access configuration values as properties to an object as shown below.

[HttpGet]
public string[] Get()
{
   var framework = _runModeInstance.Framework;
}

So, this is the new configuration system in ASP.NET Core / .NET Core. For more details about how to work with Console based commandLine and InMemory Collection etc. in configuration system in ASP.NET core, please go through the Microsoft official website. If you are not able to understand those options, please drop a comment or message to me and I will prepare a new article for you with those features like CommandLine, InMemory, Web.Config, and IOptionsSnapshot etc.