Channels ▼
RSS

Tools

Configuration-Specific web.config Files



When developing Web sites, you rely on settings stored in the web.config file that define the current environment. So, for example, the data access layer targets a development database where security settings are different from those required by the production environment. When deploying the site to the real host, you need to tweak web.config. This is usually a manual process; you open the development version of the web.config in Visual Studio, then make required changes.

To complicate things, you sometimes need to go through a battery of integration tests where you put the site to work in an environment that simulates the production. You may need yet another web.config file for this scenario. In the end, you likely need about three different versions of the web.config file -- debug, release, and test. How do you deal with this?

The simplest solution is keep the three individual files in sync manually. However, if you've moved to Visual Studio 2010 you can use the "skeleton," a new IDE feature that automatically maintains a single copy of the web.config file, then transforms it into as many versions as you need when you build the solution. This feature is supported by Web application projects and is not available for simple Web site projects.

To illustrate, assume you have a brand new Web application project open in Visual Studio 2010. Your web.config file shows up as a subtree in the Solution Explorer. If you expand the node, you see two child files -- web.debug.config and web.release.config. The debug version of web.config looks like a regular configuration file except for the root <configuration> element:


<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

The element includes the definition of a new namespace whose suffix is xdt. The namespace refers to a specific XML schema used to express transformations required on the content of the file.

On the other hand, the release web.config file contains:


<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

The <compilation> element needs updating when you move to a production environment. The Transform element identifies an element that needs transformation. RemoveAttributes() is an instruction to the config processor to remove the specified attribute from the file. As a result, when the web.release.config file is transformed the debug attribute is removed from the <compilation> element.

The idea is that you write a web.config file for debug, then express the delta between it and any other you may need, including the release version. The delta results from the transformation applied via the XDT transform. The XDT processor is incorporated in the msdeploy tool that runs within the build process. The XDT transform syntax is not limited to removing attributes. It also supports insertion and replacements. Here's how you can change a connection string when you move to release:


<connectionStrings>
    <add xdt:Locator="Match(name)" xdt:Transform="Replace"
         connectionString="..." name="NWind" />		
</connectionStrings>

The Transform attribute indicates the operation to performed on the current element and Locator points to the attribute to process.

You can have individual web.configs for each build configuration you handle in your solution. Once you add a new custom configuration, right-click the web.config file and select the Add Config Transform menu item. This adds a new web.Xxx.config file, where Xxx is the name of the new configuration. At this point, you can edit the file at and add as many XDT tags as needed. The file transformation occurs only when you generate a deployment package from the Project menu.

The creation of the package for setup is greatly simplified in this way and new configurations can be quickly and comfortably added to test new scenarios.

BYLINE: Dino Esposito

TEXT:

When developing Web sites, you rely on settings stored in the web.config file that define the current environment. So, for example, the data access layer targets a development database where security settings are different from those required by the production environment. When deploying the site to the real host, you need to tweak web.config. This is usually a manual process; you open the development version of the web.config in Visual Studio, then make required changes.

To complicate things, you sometimes need to go through a battery of integration tests where you put the site to work in an environment that simulates the production. You may need yet another web.config file for this scenario. In the end, you likely need about three different versions of the web.config file -- debug, release, and test. How do you deal with this?

The simplest solution is keep the three individual files in sync manually. However, if you've moved to Visual Studio 2010 you can use the "skeleton," a new IDE feature that automatically maintains a single copy of the web.config file, then transforms it into as many versions as you need when you build the solution. This feature is supported by Web application projects and is not available for simple Web site projects.

To illustrate, assume you have a brand new Web application project open in Visual Studio 2010. Your web.config file shows up as a subtree in the Solution Explorer. If you expand the node, you see two child files -- web.debug.config and web.release.config. The debug version of web.config looks like a regular configuration file except for the root <configuration> element:


<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

The element includes the definition of a new namespace whose suffix is xdt. The namespace refers to a specific XML schema used to express transformations required on the content of the file.

On the other hand, the release web.config file contains:


<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

The <compilation> element needs updating when you move to a production environment. The Transform element identifies an element that needs transformation. RemoveAttributes() is an instruction to the config processor to remove the specified attribute from the file. As a result, when the web.release.config file is transformed the debug attribute is removed from the <compilation> element.

The idea is that you write a web.config file for debug, then express the delta between it and any other you may need, including the release version. The delta results from the transformation applied via the XDT transform. The XDT processor is incorporated in the msdeploy tool that runs within the build process. The XDT transform syntax is not limited to removing attributes. It also supports insertion and replacements. Here's how you can change a connection string when you move to release:


<connectionStrings>
    <add xdt:Locator="Match(name)" xdt:Transform="Replace"
         connectionString="..." name="NWind" />		
</connectionStrings>

The Transform attribute indicates the operation to performed on the current element and Locator points to the attribute to process.

You can have individual web.configs for each build configuration you handle in your solution. Once you add a new custom configuration, right-click the web.config file and select the Add Config Transform menu item. This adds a new web.Xxx.config file, where Xxx is the name of the new configuration. At this point, you can edit the file at and add as many XDT tags as needed. The file transformation occurs only when you generate a deployment package from the Project menu.

The creation of the package for setup is greatly simplified in this way and new configurations can be quickly and comfortably added to test new scenarios.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video