Read the application's configuration in ASP.NET Core
As an ASP.NET developer you always used web.config to store and retrieve the
application's configuration information. ASP.NET Core uses a different
configuration system that is more flexible and powerful than before. In this
article you will learn the basics of storing and retrieving the configuration
information from JSON and XML files. You will also learn to use DI to inject
this information into controllers.
Storing configuration in a JSON file
In ASP.NET Core the preferred format for storing the application's
configuration is JSON. So, your application's configuration resides as a JSON in
a physical file (there are in-memory ways too but we won't discuss them in this
article). You can place this JSON file anywhere inside your application but the
project's root folder (not same as web root) is a common location to store these
files.
You can add an application configuration into your website using the Add New
Item dialog :

By default, the configuration file name is appsettings.json but you can give
any other name also.
Once added, you can store your application configuration into the file in
JSON format. The following sample stores a few settings into the file :
{
"SiteSettings": {
"AdminEmail": "user@localhost",
"UploadFolder": "Uploads",
"Logo": "/images/logo.png",
"Timeout" : 20
}
}
The above JSON contains a key named SiteSettings that holds a set of
hypothetical sub-keys viz. AdminEmail, UploadFolder, Logo and Timeout. This way
you could have added any keys with any kind of nesting as required.
Reading the application configuration
Now that you have stored some application configuration, let's retrieve these
values in code.
Open Startup.cs and remove the code that's already there in the constructor
(I would like to show a bit simplified version of the code). Then write the
following code :
public Startup(IHostingEnvironment env)
{
var builder = new ConfigurationBuilder();
builder.SetBasePath(env.ContentRootPath);
builder.AddJsonFile("appsettings.json", false, true);
Configuration = builder.Build();
string adminEmail = Configuration["SiteSettings:AdminEmail"];
}
Notice the code carefully. The first line creates a ConfigurationBuilder()
object. It then sets the base path where configuration files are located. Here,
we added the appsettings.json in the project's root folder and hence
ContentRootPath has been used as the base path. The AddJsonFile() method
specifies name of a JSON file containing the configuration information. The
second parameter (false) indicates whether the file is optional or not. The
value of false means the file must be present at the specified location. The
third parameter indicates whether the configuration is to be reloaded if the
file changes.
Then Build() method of the ConfigurationBuilder is called to load the
configuration into IConfigurationRoot object. Notte that the Configuration is a
property of the Startup class. Now you can read the configuration values. The
simplest way to do so is to specify the colon ( : ) delimited nesting leading to
the key to be accessed. Since we want to read the AdminEmail setting, we
specified SiteSettings:AdminEmail. The returned string is assigned to a
variable.
You could have also used Get() method of IConfigurationRoot as shown below :
string adminEmail = Configuration.GetValue<string>
("SiteSettings:AdminEmail");
Here, we used GetValue<T>() method and specified a key whose value is to be
retrieved. The advantage of GetValue() comes where your values are not strings
but other simple types such as integers (consider our Timeout key). Using the
GetValue() method you can easily specify the type of the value you expect.
int timeout = Configuration.GetValue<int>
("SiteSettings:Timeout");
Storing configuration in multiple files
You can store the application's configuration in multiple files. You then
need to load all of them and call Build() method as before. The following
example shows how that can be done :
public Startup(IHostingEnvironment env)
{
var builder = new ConfigurationBuilder();
builder.SetBasePath(env.ContentRootPath);
builder.AddJsonFile("appsettings.json", false, true);
builder.AddJsonFile("appsettings2.json", false, true);
Configuration = builder.Build();
string adminEmail1 = Configuration["SiteSettings:AdminEmail"];
string adminEmail2 = Configuration["SiteSettings:AdminEmail2"];
}
The above code assumes that you have two configuration files -
appsettings.json and appsettings2.json. The second file contains keys
AdminEmail2, Timeout2 and so on. To load both the configuration files you call
AddJsonFile() twice - one for each file. You can then access the individual keys
as before. You you can see the Configuration object contains the sum total of
the configuration from both the files.
What if the second configuration file redefines a same key as the first file
(say AdminEmail is redefined in appsettings2.json)? In that case the value from
the second file overwrites the earlier value.
Storing database connection strings
It's quite common to store database connection strings in a configuration
file. You can store them simply as a key as discussed earlier or you can use a
simplified way designed specially for connection strings :
{
"ConnectionStrings": {
"Northwind": "conn. str. here"
}
The above JSON consists of a ConnectionStrings section with a key - Northwind.
The ConnectionStrings is a special section in that the Configuration object is
aware of its purpose and hence treats it bit differently. To read the connection
string shown above you would use the following code :
string connectionString = Configuration.
GetConnectionString("Northwind");
The GetConnectionString() method simply accepts the name of the connection
string (Northwind in this case), looks for the ConnectionStrings section and
returns the value if a match is found.
Passing the configuration information to controllers
In the preceding section you read the configuration information inside the
Startup class itself. The Configuration is a property of the Startup class and
you can access it anywhere within the class. What if you want to read the values
inside the controllers? or some other class?
You can use Dependency Injection (DI) to inject the Configuration object in
such cases. Let's see how that can be done.
Inside the ConfigureServices() method add the following line of code :
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSingleton<IConfigurationRoot>(Configuration);
}
Here, you registered the Configuration object with the DI framework. The
AddSingleton() method ensures that only one instance of the object is used by
all the requests.
Now, you can receive this injected object into a controller like this :
public HomeController(IConfigurationRoot config)
{
string adminEmail = config["SiteSettings:AdminEmail"];
}
The constructor of the HomeController accepts the IConfigurationRoot object.
You can then read the configuration settings as before.
Strongly typed configuration settings
In the preceding examples you used a string key to read a value. That means
every time you need to type the whole key path to access its value. There is a
better way to deal with this situation. You can fill a custom object with the
configuration settings and then use the object wherever you wish to read the
values. This way configuration settings can be accessed in a strongly typed
manner. Let's see how this can be done.
Add a class - SiteSettings - to the project and write the following code in
it.
public class SiteSettings
{
public string AdminEmail { get; set; }
public string UploadFolder { get; set; }
public string Logo { get; set; }
public int Timeout { get; set; }
}
The SiteSettings is a simple class with four properties namely AdminEmail,
UploadFolder, Logo and Timeout. As you might have guessed these property names
match with the key names used inside the configuration file.
Now, write the following code to the ConfigureServices() method :
public void ConfigureServices(IServiceCollection services)
{
services.AddOptions();
services.Configure<SiteSettings>
(Configuration.GetSection("SiteSettings"));
services.AddMvc();
}
The AddOptions() method adds the DI support for injecting IOptions object.
The Configure<T>() method registers SiteSettings with the DI framework. Notice
that we used GetSection() method to retrieve just the SiteSettings key of the
configuration file. This way other sections (if any) and keys won't be loaded.
Now, you can receive the injected settings in a controller as shown below :
public class HomeController : Controller
{
SiteSettings options;
public HomeController(IOptions<SiteSettings> options)
{
this.options = options.Value;
}
}
The constructor of the HomeController accepts IOptions<T> object injected by
the DI framework. You can access the SiteSettings object using the Value
property. Once you have the SiteSettings object you can use its properties (such
as options.AdminEmail) anywhere in the controller.
Storing configuration in XML files
So far you used JSON files to store configuration information. However, you
can also use XML files if you so wish. Let's conclude this article with an
example that illustrates just that.
Add an XML file to the project root folder named appsettings.xml and write
the following markup into it :
<configuration>
<SiteSettings>
<AdminEmail>user@localhost</AdminEmail>
<UploadFolder>Uploads</UploadFolder>
<Logo>/images/logo.png</Logo>
<Timeout>20</Timeout>
</SiteSettings>
</configuration>
Here, the <configuration> root element (you can name it anything you wish)
contains <SiteSettings> section. The SiteSettings section further contains four
elements - <AdminEmail>, <UploadFolder>, <Logo> and <Timeout>.
To work with XML configuration you need to add this NuGet package -
Microsoft.Extensions.Configuration.Xml. Once added you can modify the Startup
constructor as shown below :
public Startup(IHostingEnvironment env)
{
var builder = new ConfigurationBuilder();
builder.SetBasePath(env.ContentRootPath);
builder.AddXmlFile("appsettings.xml", false, true);
Configuration = builder.Build();
string adminEmail1 = Configuration["SiteSettings:AdminEmail"];
}
Notice that the code uses AddXmlFile() method to add an XML file. Once loaded
the configuration can be accessed in exactly same manner as before.
That's it for now! Keep coding!!