ASP.NET 5 Configuration – Environment Specific Settings

ASP.NET 5 lets us use an environment variable named ASPNET_ENV to specify the environment that an application is running in (the variable can also be named Hosting:Environment). You can use any value for the environment name, but "Development", "Staging", and "Production" are used by convention.

Note: In earlier releases of ASP.NET 5, the environment variable name was ASPNET_ENV. This was recently changed to Hosting:Environment, but RC1 accepts both. According to comments on this issue, this could change again in RC2.

In application code, IHostingEnvironment is used to determine the environment.  IHostingEnvironment has extension methods to test whether the application is running in one of the three conventionally named environments. These methods take no arguments and return a boolean result:

  • IsDevelopment
  • IsStaging
  • IsProduction

IHostingEnvironment also has an extension method named IsEnvironment, which takes a string argument and returns a boolean result indicating whether the argument matches the environment name. All of these methods do a case-insensitive comparison against the environment name. The following code snippet illustrates how to use these methods:

We can also use the IHostingEnvironment.EnvironmentName property, which will have the value set for the ASPNET_ENV environment variable. The Visual Studio web project template uses this property to conditionally load settings based on environment. The following example illustrates this technique, but I have simplified it to focus on configuration.

The project.json file is the same as for our first configuration example:

We include an appsettings.json file, which will always be loaded and will contain common settings or default values:

We also include an appsettings file for each of our environments, named with the pattern appsettings.{environment}.json:

Finally, in our Startup class, we load the settings based on the environment (line 16). Note that we explicitly lower-case the environment name since our file names are all lower case and the file systems in Linux and OS X are case-sensitive. We also indicate that the environment-specific file is optional. You may choose to make the file required by omitting the optional argument or setting it to false, in which case a FileNotFoundException will be thrown if a file for the environment name does not exist.

To run this from the command line, we restore packages and run the application.

Windows PowerShell

Windows Command Prompt


Browsing to the site we see the expected value for the Development environment:


Now let’s change the environment to “BUILD” and run the application again:

Windows PowerShell

Windows Command Prompt


When we refresh the page we see the value for the Build environment:


You can download source code for the example projects here:

To set the environment in the Visual Studio project, go to the Debug tab of the project properties. Note that the Visual Studio project uses Hosting:Environment, but ASPNET_ENV will work as well.

Up to this point, we have been using hard-coded string keys to access configuration settings, which return values as strings.  We can create settings classes for typed access to configuration values, but first we need to take a detour and look at dependency injection.

Leave a Reply