The New Configuration Model in ASP.NET Core

ASP.NET Core has a lot of changes compared with the others versions of ASP.NET. One change I want to highlight is the new way to configure settings. With previous versions, this configuration was made by using the common file web.config, but this file simply doesn’t exist anymore in ASP.NET Core. Instead, a new easy way to declare and access to the settings is provided. Let’s take a look.

// “The New Configuration Model in ASP.NET Core” is one of our top 5 .NET articles of 2017. See the full list here.

Goodbye web.config

Before we examine the new way to configure settings, let’s look at how it was done in versions prior to ASP.NET Core.

First, you go to the web.config file and, inside the appsettings node, add all the settings that you need. This works like a key-value dictionary:

    <add key="SmtpServer" value="" />
    <add key="SmtpUser" value="" />
    <add key="SmtpPass" value="12345678" />
    <add key="SmtpPort" value="25" />
    <!-- More Settings -->

The next step is to access these values. This is done using the ConfigurationManager class:


Hello appsettings.json

In ASP.NET Core, it is possible to read settings from different sources like XML, JSON and INI files. To see how it works in your ASP.NET Core Application, add a new section to store the SMTP info in the appsettings.json file:

  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Verbose",
      "System": "Information",
      "Microsoft": "Information"
  "Smtp": {
    "Server": "",
    "User": "",
    "Pass": "123456789",
    "Port": "25"

One of the key advantages in this new configuration model is that it’s easy to create a class to work with the data. To do that for the example above, create a new class called SmtpConfig inside the folder ViewModels (or whatever folder you prefer) and define four properties:

public class SmtpConfig

    public string Server { get; set; }
    public string User { get; set; }
    public string Pass { get; set; }
    public int Port { get; set; }

Next, go to the Startup.cs class, add the following code within the constructor to read the appsettings.json file:

var builder = new ConfigurationBuilder()
Configuration = builder.Build();

In the same class, go to the ConfigureServices function. The following code will read the Smtp section, then use the Configure method of Services to set this to the SmtpConfig class:

public void ConfigureServices(IServiceCollection services)
    //Other services

Using Configuration

ASP.NET Core has built-in dependency injection. To use the SmtpConfig class, you can inject them using the Interface IOptions<T>. The following examples usesthis in a MVC Controller:

public class HomeController : Controller
    public SmtpConfig SmtpConfig { get; }
    public HomeController(IOptions<SmtpConfig> smtpConfig)
        SmtpConfig = smtpConfig.Value;
    //Action Controller

Looking at the constructor, you’ll see that it’s injecting an object of type SmtpConfig through IOptions<SmtpConfig> and assigning it to a property of the same type:


All’s good and pretty easy.

Configuring Multiple Environments

What if you need different configuration values for different environments? If you remember web.config transformations, there is a similar concept here that is related to determining the environment (dev, QA, staging, production, etc). Let’s see how it works.

Add a new JSON file and set the name then add only the smtp section

with the values associated with this new environment:

    "Smtp": {
        "Server": "",
        "User": "",
        "Pass": "Ke!2546hg#$",
        "Port": "427"

So how does the framework know what the current environment is? There is an environment variable called Hosting:Environment. To access it inside Visual Studio, open the project properties, go to the Debug tab and change the value for this variable to qa:

Project Properties

Return to Startup.cs class and next to the line that read the appsettings file, tell the framework to read the additional appsettings file base on the environment. If this file exists, the property values are overridden:

public Startup(IHostingEnvironment env)
    var builder = new ConfigurationBuilder()
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
    Configuration = builder.Build();

Test the application again, and look the values that are used this time:

QA Settings


APS.NET Core offers a new configuration model that is clean and very easy to use. Plus it works with XML, it works with JSON, INI and any other file type you may need. Lastly, it is very customizable and is built with dependency injection in mind.


  • Pingback: Dew Drop – April 8, 2016 (#2226) | Morning Dew()

  • Pingback: Dew Drop – April 8, 2016 (#2226) | Tech News()

  • Pingback: The Morning Brew - Chris Alcock » The Morning Brew #2069()

  • Pingback: The Morning Brew #2069 | Tech News()

  • Pingback: Build 2016, One Last Time | Codango.Com()

  • Jim Gilbert

    good grief! This is “clean”, “easy to use”? By my count, in this example, using the new json settings requires 4 steps instead of 1…

    • ᅠᅠᅠ

      And it will pay off the moment your setup starts getting a bit more complex, with multiple deployment types and integration environments.

      Counting lines or steps are the wrong metrics to evaluate patterns in software engineering. It may not be concise, but it definitely is clean and easy-to-use, and also, most importantly, scales well.

  • Pingback: Notes from the ASP.NET Community Standup – April 12, 2016 | .NET Web Development and Tools Blog()

  • ozbob

    great snippet. thanks

  • What “using” statement do I need for Configuration = as I have a conflict?

    • David Keller

      As of RC2 you need using Microsoft.Extensions.Configuration and you need to plug in an action: services.Configure(options => configuration.GetSection(nameof(AppSettings)));

  • Nice article. Thank you for sharing

  • Vincent

    Nice article and learnt something new. However I also found that we can’t have single environment variables with Development and Staging values. It gives duplicate key error. But you can have different startup based on ASPNET_ENV variable value as pointed here.

    Is there any way to add development and qa values in debug tab and then how to use it further?

  • Дмитрий Осипович

    The type or namespace name ‘IOptions’ could not be found (are you missing a using directive or an assembly reference?)

  • I hope they add support for SMTP settings soon. Like Jim Gilbert mentions, this was a 1 step process before (Add mailSettings node to app/web config). No need to read AppSettings value manually

  • Roman Alvarado M.

    How could be different environments configuration with Visual Studio Code?

  • Vik

    Nice article . how can i send html template email with core ?

  • Tim Schmidt

    Thanks! Exactly what I needed

  • James Wierzba

    How do you specify different environment variable values for different build configurations? For example if I am building using “DEV” configuration, I want the “ASPNETCORE_ENVIRONMENT” env variable to have the value “DEV” but if I’m building QA, it should be QA. Do you have to manually change this each time? How then would you enable CI?

  • Joseba

    GoodBye appsettings.json
    Hello web.config… again

  • xumix

    Is there any way to retrieve smth like Dictionary from settings?
    I have “Codes”: { “079A3EFA-F665-4509-9394-A7E2239BD5AD”: [ “” ] } and the Codes dictionary is empty in options

  • vamshee goud

    Thanks for the article very useful