One of the challenges with ASP.NET in combination with containers, is the fact that you configure all your settings in the web.config. when using containers, we want to provide different settings for different environments we run our containers. E.g. you have a dev, test, acceptance and production environment, for which you want other connection strings and appsettings for your application.

Containers bring us the concept of immutability, meaning that once we bake our container, it is fixed. This implies that when we want to change settings in the web config per environment we are more or less stuck.

ASP.NET 4.7.1. to the rescue!

In ASP.NET 4.7.1 Microsoft added some awesome new capabilities to override your web.config settings using other mechanisms like environment variables.

The way this works is that you can now add configuration builders to your web.config file. You can build your own configuration builders, or use some of the pre-cooked configuration builders that Microsoft provides. One of them is particularly handy, since it helps us to override values in the web.config based on environment variables. And that exactly matches what we need to run in containers!

How do we use configuration builders?

Let me show you how to make this work for an legacy application we all know and love: The MVC Music Store.
First of all you need to set your target framework to .NET framework 4.7.1. or higher.


If you don’t find this target in your dropdown, you can install the developer packages here and install them, so they show up in Visual Studio.

In your web.config file you can now add a new configuration section handler, that will enable you to add attributes to various sections where you want to have an override of the configuration.

Here is the way you add configuration builders to your config:

After we added the configuration section, we can now specify which configuration builders we want to use. You can build your own, but you can also use the one provided by Microsoft. they have a couple of them, I am using the one to use environment variables.

Before this will work, you need to ad two nuget packages to your application, otherwise it is not able to find the assemblies mentioned in the config file.

You need the following packages:


Microsoft.Configuration.ConfigurationBuilders.Base is the infrastructure to intercept any calls to web.config to read configuration and it provides the option to have a configuration builder override the values in the current file.

Microsoft.Configuration.Configurationbuilders.Environment is the implementation to read from environment variables and override specific sections of the web.config file. The sections supported at the momen are: Connectionstrings, where you can replace the connectionstring value (not the providerName!) and the appsettings section in your config file.

The way to let a part of the configuration to be overridden is by adding an attribute to the section. For appsettings this looks as follows:

For your connection string it looks like follows:

You see in both sections we added an attribute that tells the configuration builder, which configuration builder to use to override the values. You can use multiple configuration builders that you configure for different sections. One builder is used per section.

Overriding the values

The syntaxt to override your app settings is quite straight forward. You can set an environment variable with the name of the app setting and provide it a value. E.g. overriding your ApplicationInsightsKey would be done by setting an environment variable with the name ApplicationInsightsKey and give it a new value.

For connection strings you also provide the name of the connection string and the value will then override the current connectionstring attribute. Overriding the connection string for MusicStoreEntities you provide an environment variable with the name MusicStoreEntities and give it the value of the connectionstring you want to use.

At the moment there is no solution yet for more complex settings, but you can build your own configuration builder to take care of this. How to build a configuration builder is described here:Writing a configuration builder

Using this in your containers

If you have build your container with a docker file, you can now very easily override your settings from the commandline.

I have created a docker image you can pull from docker hub to show you that it works. If you just pull the image : marcelv/mvcmusicstore-configbuilder and you provide it a connectionstring for a database you want to connect to it will show you the mvc musicstore using configuration builders.

You can run it as follows:

If you don’t have a database available, just use an docker container for that.

To start a sql server to be used with the music store, use the image : microsoft/mssql-server-windows-developer

To make this work together (without creating a compose file), first start your SQL server eg. like follows:

This will return you an id for the container that runs.

Now run the command:

Now the id you find for the sql server is what you can use as the host name of the sql server in the connectionstring.
Let’s assume it returned the number : 8bf45f8935c6

Now you can start the mvc music store container as follows:

Now you can browse to localhost with your browser of choice and you should see the MVC music store there.
(assuming you are on docker for windows 17.12.0-ce or higher, otherwise you need to browse to the ip address of the container. You can get this info by either running ipconfig in your container with docker exec command or by using the docker inspect command on the container id)


By using the new configuration builders you can override the values you normally have in your web.config file. This enables us to use containers in a very simple way with our classic ASP.NET applications. No need to move your site to .NET core, just to get environment variable support for your configuration. This should enable you to leverage the immutability of containers even for your existing classic ASP.NET applications!

CTO at Xpirit, Microsoft Regional Director, Visual studio ALM MVP, Speaker, Pluralsight Author and IT Architect Consultant