Last week I had two discussions with different people regarding configuration and environments in ASP.NET Core. Both conversations started from the same question: how do I use ASP.NET Core configuration and environments in practice? Since this seems to be a fairly popular topic among more inexperienced developer, I thought it might be worth sharing some thoughts about this in a blog post. Please note, however, that this is only a getting started guide that shows how an ASP.NET Core application is supposed to work in different environments. It’s only a first building block towards more complex scenarios.
Configuration in ASP.NET Core
Configuration in ASP.NET Core is surely a topic that has its depths. My goal here is not to explore them. App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. Configuration providers read configuration data into key-value pairs from a variety of configuration sources. The most common configuration source in ASP.NET Core is the appsettings.json file.
This file is the place where you usually put all the application settings, like connection strings, hosts, ports, other network connections or any other settings that your application needs to work properly. In the Startup.cs class you can then use the Configuration property to get different sections of your settings file using different mechanisms like direct binding or options pattern. Using the latter one, here is a single line of code that would bin the contents of the “Env” section of the appsettings.json file to the “Env” POCO object:
That’s easy. So what about environments?
One misconception that I heard during my discussions was that environments are, in a certain way, a part of the ASP.NET Core application. However, that’s not exactly true. Any ASP.NET Core application is running on a host system. The host is responsible for the entire lifetime of the application, from start to stop. Basically, the host system is running your ASP.NET Core application. It could be an Azure Web App or an IIS server, whatever.
This means that if you deploy your application to two different host systems, you application is running on two different hosts. And this might be actually very important since you can have one application that you deploy to a host that you’ll consider your “Test” environment, to another host that might be considered as your “Staging” environment and probably another one that will serve as your “Production” environment.
Of course, for each environment you will probably have different settings: like different connection strings and so on. Now, the challenge is to make your ASP.NET Core application recognize what is the purpose of the environment / host it is running on and use the correspondent settings. That’s very easy!
Different appsettings.json files
ASP.NET Core is actually very developer friendly in this regard. The only thing you would need to do is creating different appsettings.json files that contain also the name of the environment separated by colon. This would look similar to this:
By the way, if you want to follow along, HERE is a repo with a very small ASP.NET Core API that uses configuration and environments.
In this example, the appsettings.QA.json contains following section:
The appsettings.Development.json file would contain the same section but with different information:
And the appsettings.json file would contain the same section, but, again, with different information. Also this might be the settings file for your production environment:
Cool! So how can ASP.NET Core work with this?
Environment variables to the rescue
In my discussions I noticed that the whole concept of environment variables is misunderstood. The whole idea about these variables it these are provided by the host. Therefore they are not inherent to the code we write. It’s just a value that’s passed to our code as the host executes our application.
To wire things up, ASP.NET Core uses a predefined environment variable named ASPNETCORE_ENVIRONMENT. The only thing we would need to do is to configure the host to pass in this environment variable to the application with the desired value. Taking note of the information discussed above this would mean something like that:
- If you pass in ASPNETCORE_ENVIRONMENT with value “QA”, the ASP.NET Core application will use the appsettings.QA.json file as its settings source
- If you pass in ASPNETCORE_ENVIRONMENT with value “Developement”, the ASP.NET Core application will use the appsettings.Development.json file as its settings source
- If you don’t pass any ASPNETCORE_ENVIRONMENT environment variable, ASP.NET Core will use the default appsettings.json file as its settings source.
So how can you test around?
Testing configuration and environments in Visual Studio 2019
Once again, if you want to follow along, clone this repository, where you’ll find a very basic ASP.NET Core API that showcases these concepts!
If you want to play around in Visual Studio and see how the different files are used, you need to change the
If you change the value to “QA”, run the API and make a call to the “env” endpoint, the output will be
…because the appsettings.QA.json file will be used.
If you delete the environment variable entirely, you will get the following output:
"name": "Probably production",
… because in this case the appsettings.json file is used. If you change it to “Development”, then the settings from the appsettings.Development.json file will be used.
But remember, even if you we change the value of the environment variable in Visual Studio, this is not actually something that is inherent to our code. We just set up the IDE to pass in this variable when it runs the application.
Testing configuration and environments in an Azure Web App
From Azure perspective, having different environments means that you’ll most probably have different Azure Web Apps. On each Azure Web App you have full control to customize the environment variables that the host will pass to your application. Here’s a screenshot that shows how you can do that:
In this screenshot I passed “QA” as value to the ASPNETCORE_ENVIRONMENT variable and therefore if you execute the following request: GET: https://cwkenvapi.azurewebsites.net/env … you’ll get the following response:
You can, of course, create your own Azure Web App and play around with the variable. Don’t forget to restart the web app each time after you change the value of the variable.
This is the most basic way to configure different environments for your ASP.NET Core app, each with its own connection strings and specific settings. Things can, of course get a little bit more complicated but in a lot of real life project having this basic knowledge already helps you get the job done.
How useful was this post?
Click on a star to rate it!
Average rating / 5. Vote count:
Latest posts by Dan Patrascu-Baba (see all)
- Configuration and environments in ASP.NET Core - 25/11/2019
- GraphQL in the .NET ecosystem - 19/11/2019
- A common use case of delegating handlers in ASP.NET API - 12/11/2019