Managing Web.Config Settings For Multiple Environments

By: Steven Nelson | October 4, 2011

Configuration plays an important part of any .NET application. Each application typically contains many settings that are controlled in the application configuration file. Some examples of settings controlled through configuration might be connection strings to database resources, file paths for error logs, URLs for webservices, or a custom configuration setting used in application logic. In an ASP.NET web application the web.config file is used to hold the configuration settings that an application may use.

Each of the various environments that an ASP.NET web application might use typically requires different configuration settings. For example, when an ASP.NET web application is run on the developer’s local PC, a database connection string may reference a local database, and a webservice URL will point to the developer’s PC. When the web application is deployed to a staging server for QA testing, the connection string and webservice URL will need to be changed to reference the appropriate resources used for testing. In a similar fashion, when the web application is deployed to the production environment a different set of configuration settings maybe be required.

Visual Studio 2010 introduced a feature into the web application publishing pipeline that allows a web configuration file to be automatically transformed. The web.config transformation occurs when the web app is published for deployment. During the publish process, the publishing engine uses the current build configuration to locate the web.config transformations that should be performed in order to create the resulting web.config file that will be packaged into the deployment.

First, create separate build configurations that correspond to the deployment environments that you will need to manage. For example, a Debug config which will be used for development, a Test config that is used for testing on a staging server, and finally a Production config which represents the final production environment.

Sample Configurations

In the Configuration Manager, the Test config may look like this:

Notice that the highlighted ASP.NET web project MKC.CustomizeIt.Portal.Web is set to the ‘Test’ configuration when the selected solution configuration is set to ‘Test’. When the solution configuration of ‘Test’ is used to publish the, then the web.config transformations for the ‘Test’ configuration are applied to the web.config file.


In order to create the web.config transformations, locate the web.config file in the ASP.NET project, and right-click the item in the solution explorer. Notice the menu item “Add Config Transforms”. This menu item will create a web.config file that corresponds to each of the configurations that exists for this project. Notice in the following diagram that the web.config file is opened and there are additional files attached to it. The naming convention of the resulting files will be web.XXX.config where XXX corresponds to the name of the configuration.

The file Web.Test.config contains the transformations that should be applied when then Test config is used for publishing the web project. In a similar fashion, the Web.Prod.config contains the transformations that should be applied to the web.config file when publishing for production.

The important thing to know about the transformation process is that the web.config file should contain all of the settings that should be used. The smaller transform files (such as web.test.config) contain only the transformation rules that should be performed against the web.config file.

Consider the Following Web.Config File:

Transformation Specifics

Suppose that the connection string for “AspnetServicesDb” should be changed in the test config. The web.test.config file would look as follows. The highlighted line indicates the transformation to replace the connection string.

The transform makes use of an xml syntax that the transformation engine uses to know how the transformation should take place. The xdt:Locator attribute is used to exactly identify the node in the configuration that the transformation should be applied to. The xdt:Transform attribute identifies the way to modify located configuration item. In this case we are matching on the name of the node “AspnetServicesDb” from within the <connectionStrings> node. Then we are setting the attributes of the connectionString node as specified in the transform file.

The xdt:Locator attributes may be used to locate a node based on the following:

  • Match on the name of the node
  • Exact Xpath expression that can locate the node
  • Condition match to find the node

The xdt:Transform may perform the following types of modifications:

  • Replace a node
    <param name=”File” value=”errorlog.log” xdt:Transform=”Replace” />
  • Insert a node
  • Delete a node
  • Remove attributes
    <compilation xdt:Transform=”RemoveAttributes(debug)” />
  • Set attributes

The web.config transformation process that occurs while publishing an ASP.NET web app is a compelling model to automate the management of separate configuration settings for different deployment targets.

To Learn More
Additional information on web.config transformations
More info on web deployment concerns

Whether you are deploying a collaboration platform or modernizing your application portfolio, we put security at the forefront.

New call-to-action
Steve is a Senior Solution Architect with deep experience using .NET to build web applications and service communication applications.

Subscribe to our Newsletter

Stay informed on the latest technology news and trends

Relevant Insights

How to Turn Your Software Licensing into a Strategic Asset

Most people groan when they hear the words “software licensing”. Licensing can be complicated, and usually businesses will continue with...
Read More

How to Manage Your Hybrid Workforce with Compliance

The pandemic accelerated a real change in the way people do their work. Before, employees worked in a physical office...
Read More

Windows Server 2012 End-of-Life Risks, Options, and Next Steps

In October 2023, Windows Server 2012/2012 R2 will reach the end of extended support – leaving your infrastructure and applications...
Read More