.NET Core Configurations

.NET Core gives you the ability to easily manage configurations for your application across multiple environments (eg: local, dev, production, etc). Read on to find out how to set your environment on the command line and even for Docker.

Startup Methods For .NET Core 1.x & 2.0 Projects

For your .NET Core 1.x projects, your Startup.cs should contain code along the lines of:

public Startup(IHostingEnvironment env)
{
    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();
}

As of .NET Core 2.0 in your program.cs you'll notice this simplified code by default:

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .Build();

In the .NET Core 2.0 code the CreateDefaultBuilder() method performs a lot of tasks that most every web application or API will need, including configuring Kestrel as the default web server, setting the root contet directory (where appsettings.json will be located), and the item most relevant to this blog post, loads configurations. The configurations that are loaded come from appsettings.json & appsettings.{environment}.json similar to how a 1.x application would be setup.

Setting The .NET Core Application Environment

For both 1.x & 2.0 when you dotnet new webapi -n sample the CLI will create a new project with two appsettings where config values are being loaded from the give JSON files. appsettings.json is pretty straight forward. appsettings.{environment}.json will use the value you specify with ASPNETCORE_ENVIRONMENT to load your JSON config file. Set the ASPNETCORE_ENVIRONMENT on your command line prior to a dotnet run and your application will pick up the environment-specific configuration file. This can also be configured in your environment variables in Visual Studio or your launch.json if you set up a VS Code configuration within your project.

Let's look at a quick example. Assuming you're on the Windows command line:

c:\example>set ASPNETCORE_ENVIRONMENT=Development
c:\example>dotnet run
Hosting environment: Development
Content root path: c:\example
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

Notice that the "Hosting environment" is set to "Development", the same value we set on the ASPNETCORE_ENVIRONMENT variable. Now when the app runs it will turn appsettings.{environment}.json into appsettings.Development.json and load the configuration values from that file. If you have the same key in both of your files, your environment-specific configuration file will override the basic appsettings file, so now you can change settings based on the environment you're working with.

Setting The .NET Core Environment With Docker

If you've used Docker you might be wondering how do you make this work with Docker... This too is pretty straightforward after you know the magic command line flags. docker run allows you to set environment variables for the container with the -e flag. So for example docker run -it -e ASPNETCORE_ENVIRONMENT=dev -p 80:80 sample would run the sample service in a container, set the ASPNETCORE_ENVIRONMENT variable to "dev" and would then look for the appsettings.dev.json configuration file.

A second way to handle setting environment variables for Docker is with then --env-file flag. If you can't (or don't want to) supply the variables on the command line, you can specify them in a configuration file that will be given to the Docker run command. In the example docker run -it --env-file ./dev.env -p 80:80 sample, the dev.env would contain one or more variables and it's associated value (one per line). When Docker runs it will load the variables and set them in the environment for your service.

Conclusion

Setting your environment specific configurations has been made fairly easy in .NET core. The framework provides several methods for setting configuration values, but in this article I focused just on the appsettings.json files and the ASPNETCORE_ENVIRONMENT variable.