ASP.NET has long had an AppSettings style configuration interface that you see used by most applications. AppSettings in current versions of ASP.NET (4 and prior) is based on very basic string based key value store that allows you to store and read configuration values at runtime. It works reasonably well if your configuration needs are simple, but it quickly falls apart if your configuration requirements are more complex. The biggest issues are that by default you have access to the ‘AppSettings’ key only – with a bit more verbose of a syntax to access other sections. The other big downfall of this tooling is that the values stored have to be strings when often configuration values need to be at the very least numeric or logical values that have to be converted.

New Configuration System in ASP.NET 5

The configuration system in ASP.NET 5 has been completely overhauled and entire web.config/app.config mechanism has been thrown out in favor of a new pluggable system. The default configuration implementation uses a config.json file as storage, but the system is pluggable so other providers can be used instead as well as at the same time. For example, the default project template uses both config.json and environment variables, the latter of which override values in the .json file.

Default AppSettings

A new stock ASP.NET 5 project created with Visual Studio comes with a default AppSettings class which is meant to replace the old AppSettings functionality. Let’s start by looking of how this is hooked up.

Configuration settings are represented by a class that is mapped to configuration values that are stored in the configuration store. By default this store is a JSON file, but it can come from a number of sources. Here’s the default AppSettings class:

public class AppSettings
{
    public string SiteTitle { get; set; }
}

You can add properties to this class and those properties then become configuration values that you can match in your configuration file which by default is config.json – again with  default settings here from  a new project:

{
    "AppSettings": {
        "SiteTitle": "WebApplication2",
    },
    "Data": {
        "DefaultConnection": {
            "ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=aspnet5-WebApplication1-414415dc-a108-49f3-a5e3-fdc4cf24ef96;Trusted_Connection=True;MultipleActiveResultSets=true"
        }
    }
}

The properties of the AppSettings property in the config.json are mapped to your AppSettings class.

Hooking up Configuration

As most system components in ASP.NET 5, configuration is hooked up via dependency injection and configured during startup of the application. It starts in the Startup class with the Startup method which is the entry point to any ASP.NET 5 application and configures basic feature support:

public class Startup
{
    public IConfiguration Configuration { get; set; }

    public Startup(IHostingEnvironment env)
    {
        // Setup configuration sources.
        var configuration = new Configuration()
            .AddJsonFile("config.json")
            .AddJsonFile($"config.{env.EnvironmentName}.json", optional: true);

        configuration.AddEnvironmentVariables();
        Configuration = configuration;
    }

}

Here the configuration provides is set up and support for Json file and Environment variable storage is defined. Notice that there are also two configuration files, the config.json and config.[Environment].json where

Once the application is bootstrapped, the ConfigureServices method is fired in the same class which is used to essentially hook up and configure  behavior of various components. One of the things you can do in this method is to map configuration values to a configuration class.

public void ConfigureServices(IServiceCollection services)
{
    // Add Application settings to the services container.
    services.Configure<AppSettings>(Configuration.GetSubKey("AppSettings"));
    …
}

This code basically maps the AppSettings configuration key to an instance of your configuration class. You can map more than one configuration class here so it’s possible to make your configuration more modular – think of this like separate configuration sections in the old style.

Using Configuration Values

If you now want to use configuration values in your application you can inject the value into your code or Razor content.

This example injects AppSettings into a Controller:

public class HomeController : Controller
{
    private IOptions<AppSettings> AppSettings;

    public HomeController(IOptions<AppSettings> appSettings)
    {
        AppSettings = appSettings;
    }

    public IActionResult Index()
    {
        string siteName = AppSettings.Options.SiteTitle;
        return View();
    }
}

which is likely the most common scenario on how you would use a configuration object in your Web code. From here you can pass the AppSettings into view if required.

Injecting AppSettings into a View

You can also inject AppSettings directly into a view using the new @inject tag (although that seems dubious at best) and in fact that’s what the Shared _layout template does by default:

@inject IOptions<AppSettings> AppSettings
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewBag.Title - @AppSettings.Options.SiteTitle</title>

It injects the AppSettings class and uses the Options to display the Site title in the header. I suppose the injection in this case makes sense since the _Layout template doesn’t have an explicit model associated, but for any other type of view I’d recommend passing any configuration object as part of your model rather than injecting it.

Adding additional Configuration Values

If you want to add additional configuration values, you simply add a new property to your configuration class and add a key to the config.json file.

Add the property:

public class AppSettings
{
    public string SiteTitle { get; set; }
    public int MaxListCount { get; set; } = 15;
}

and also add the value in the config.json:

{
    "AppSettings": {
        "SiteTitle": "My Lovely Application",
        "MaxListCount":  20
    }
}

Technically you don’t have to add the value in the file, but you should make sure that the two match.

Then if you want to access this value in your code you should be able to do:

public IActionResult Index()
{
    string siteName = AppSettings.Options.SiteTitle;
    int maxItems = AppSettings.Options.MaxListCount;  // 20
    return View();
}

and you should get a value of 20 based on the value we have stored in the config file. Note that the value is a number and automatically converted for you unlike in the old ASP.NET configuration system.

Nested Configuration

Ok strongly typed configuration is nice for simple types, but it’s even nicer if you are dealing with more complex configurations. You can create nested types for nested configuration storage. So for example we could change AppSettings to:

public class AppSettings
{
    public string SiteTitle { get; set; }
    public int MaxListCount { get; set; } = 15;
    public ThemeOptions ThemeOptions { get; set; } = new ThemeOptions();
}

public class ThemeOptions
{
    public string ThemeName { get; set; } = "Default";
    public string Font { get; set; } = "'Trebuchet MS','Trebuchet','sans serif'";
}

and our config.json to:

"AppSettings": {
    "SiteTitle": "My Lovely Application",
    "MaxItems": 20,
    "ThemeOptions": {
        "ThemeName": "WaveBot",
        "Font": "'Helvetica Neue',Arial,'sans serif'"
    }
},

Then to use it in our HomeController:

string theme = AppSettings.Options.ThemeOptions.ThemeName; // WaveBot

Nice.

Adding a new Configuration Class

Having a single configuration class works, but sometimes you need more than a single piece of configuration. If you’re building a self-contained component for example, you won’t want to mix in your configuration settings with the standard AppSettings – it’s much cleaner to have a completely separate configuration key.

To do this we first need a new class. Here’s an example:

public class LoggingConfiguration
{
    public LogModes LogMode { get; set; } = LogModes.TextFile;
    public string LogFile { get; set; } = "~/logs/ApplicationLog.txt";
    public string ConnectionString { get; set; }
    public int LogDays { get; set; } = 7;
}

public enum LogModes
{
    TextFile = 0,
    Database = 1,
    XmlFile = 2
}

Now we need to register this class as a configuration source in the ConfigureServices code in Startup.cs so ASP.NET knows about it and can inject the class:

public void ConfigureServices(IServiceCollection services)
        {
            // Add Application settings to the services container.
            services.Configure<AppSettings>(Configuration.GetSubKey("AppSettings"));
            services.Configure<LoggingConfiguration>(Configuration.GetSubKey("LoggingConfiguration"));

Then I need to add the key to my config.json:

"LoggingConfiguration": {
    "LogMode": "XmlFile",
    "LogFile": "~/logs/MyApplicationLog.xml",
    "ConnectionString": "",
    "LogDays": 10
},

Next I need to inject into my point of use – the Controller in this case:

private IOptions<AppSettings> AppSettings;
private IOptions<LoggingConfiguration> LoggingConfiguration;

public HomeController(IOptions<AppSettings> appSettings,
                      IOptions<LoggingConfiguration> loggingConfig)
{
    AppSettings = appSettings;
    LoggingConfiguration = loggingConfig;
}

And finally I can use the values in my controller code:

string logFile = LoggingConfiguration.Options.LogFile;
int days = LoggingConfiguration.Options.LogDays;

And voila – we now have our custom configuration values and even a custom configuration object.

But, hold on – not so fast. There is a problem…

Enums are not Serialized

Above I mentioned that serialization from JSON is capable of strongly typed values – and that’s not entirely true. This enum value:

var mode = LoggingConfiguration.Options.LogMode;

is not properly deserialized. The mode value in this case always comes up with the default value set as the class property default (TextFile).

Unfortunately, this is a bug (in beta4) in the runtime code and unless you want to dig into runtime code and modify it we’re stuck with this behavior. For now – if you don’t want to change anything – stay away from enum values but it looks like this issue is fixed for the next beta/rc release.

In my next post I’ll describe how we can track down this runtime bug, fix it and actually apply it to the running application.

Other Configuration Sources

The JSON configuration is the most obvious configuration store because it actually shows up in your project as a file. But you can also use other configuration stores like EnvironmentVariables, INI files and a UserSecrets store. You can also build your own by extending the configuration interfaces which are relatively easy to create.

Configuration sources are applied only if you configure them as part of the startup configuration. For example, in this application I added:

var configuration = new Configuration()
    .AddJsonFile("config.json")
    .AddJsonFile($"config.{env.EnvironmentName}.json", optional: true);

if (env.IsEnvironment("Development"))
{
    // This reads the configuration keys from the secret store.
    // For more details on using the user secret store see http://go.microsoft.com/fwlink/?LinkID=532709
    configuration.AddUserSecrets();
}
configuration.AddEnvironmentVariables();

Configuration providers are cumulative and last one that has a match wins. So if I configure my JSON.config file with SiteName but then add an environement variable with the key I’m looking for the environment variable wins – that’s the value used.

How does this work?

Behind the scenes the configuration system consists of two major components: the configuration provider whose responsibility it is to capture the configuration values as key value pairs, and an OptionsModel that essentially exposes that dictionary as the strongly typed object source (or key values) that you created.

In your application you typically interact only with the IOption<T> instance of the strongly typed class you provided – the raw IConfiguration class is not injectable by default and I couldn’t see an easy way to get access to this raw store of the parsed configuration data. The configuration class is typically accessible only during startup configuration where you’ll see the string based path syntax used, while in application code you are likely to see the injected IOption<T> strongly typed values instead.

So typically you get a hold of the configuration via injection of the options:

public HomeController(IOptions<AppSettings> appSettings,
                      IOptions<LoggingConfiguration> loggingConfig)

The Options object is populated when the application starts, and unlike classic ASP.NET applications, changes to config.json or any other of the configuration files don’t automatically restart the Web application with the changes applied.

You might think that it would be easy to parse a JSON object to an a model class, but that’s not how the system actually works. Instead the input configuration source is parsed into a string dictionary first. For the JSON provider this means parsing the JSON object into a tokenized JSON list (using Json.net’s JsonReader) and then creating the keys for each of the non-complex properties.

Internally configuration information is initially stored as a string dictionary that represents keys as a ‘path string’ in the format of:

AppSettings:SiteTitle
AppSettings:ThemeOptions:ThemeName

You essentially build a configuration ‘path’ that describes the same structure you’d see in a config.json file replacing each . with a :

{
"AppSettings": {
    "SiteTitle": "My Lovely Application",
    "MaxItems": 20,
    "ThemeOptions": {
        "ThemeName": "WaveBot",
        "Font": "'Helvetica Neue',Arial,'sans serif'"
    }
},
"LoggingConfiguration": {
    "LogMode": "XmlFile",
    "LogFile": "~/logs/MyApplicationLog.xml",
    "ConnectionString": "",
    "LogDays": 10
},
}

Because the data is parsed into string keys and values first, it’s possible to present the layout with just about any provider. So with environment variables you can declare an environment variable like this:

SET DATA:APPSETTINGS:THEMEOPTIONS:THEMENAME=Console
dnx . web

In a live environment you’d either setup these environment variables as part of your global configuration or you set them as part of a startup command script you run before the application is launched from the command line with dnx . web for example.

If you’re debugging inside of Visual Studio with IIS Express there’s a Debug option that allows you to set environment variables as part of the startup:

If you’re on a live standalone server you can set system level keys, as you can on Azure by setting the values in the Azure Portal for your Web application. Be careful if you end up using global environment variables so that you don’t duplicate keys!

Environment variables are useful for some override scenarios but I don’t think they are a great solution for most configuration options. I’d consider using them only for overriding configuration values that are otherwise set in a common configuration. Curious to hear other use cases where environment variables make sense.

User Secrets Store

The ASP.NET runtime also includes a user secrets store which is a command line tool that adds values to a machine only store. The only way to get values in and out of that service is via a command line tool that uses a secret key which is great for configuration values that are user or machine specific and should not be shared in source control. You have to explicitly add the values and those values.

You can find out more about how this works on the GitHub documentation page for the DNX Secret Documentation. Personally I had issues getting the tool to work – I kept getting errors related to a missing assembly on Beta4. But I’ve had this working in previous versions so this is likely just a glitch in my configuration.

Summary

These configuration changes are a big improvement over the old string only configuration system. Having strongly typed POCO resources to hold configuration information is the way to go. In the past I’ve used my Westwind.ApplicationConfiguration library for providing many of the same features (and a bit more), and I’m happy to see that I probably can retire that library and just use the existing config system in ASP.NET 5 now.

There’s a little more complexity here and as with anything in ASP.NET 5 you have to deal with the dependency injection to get the values into your app. There’s also some inconsistency with how you use the config values between the startup confguration (string paths/values) vs the strongly typed classes that are injected. While all of this works just fine for ASP.NET applications, I’m not so sure that it will work so well if you need to build configuration features into your own components where you might not so easily have access to the DI features – it’ll bear some experimenting.

Overall I like what I see and the way configuration works now addresses most of the complaints I’ve had about the AppSettings API that existed in older versions of .NET natively.

Although I ran into that Enum bug I mentioned, that’s a bug that’s already addressed in future releases. In my next post I’ll describe how to drill into the problem runtime code, fix it in the beta 4 build I’m using and then use it in my own application. Until then…