A key issue when deploying ASP.NET applications is the need to manage the many configurations needed for development, testing, staging, production and so on.  Configuration items such as connection strings, app & debug settings and service endpoints need to be set according to their target runtime environments.  Traditionally, developers on the ASP.NET platform have dealt with many hassles in getting projects configured for their target deployments and have turned to techniques such as:

• excluding local web.config copies from deployment then deploying separate web.config files to appropriate environments
• keeping one master web.config checked into source code control while excluding and modifying all developer’s local copies of web.config
• scripting/build hooks to create web.config files for each deployment environment

Much of the deployment process when using Visual Studio has been riddled with manual procedures, and lots of tweaking, as there was little built-in automation for configuration management. Automation consisted of creating and managing build scripts and hooks. Because of this, some folks don’t bother including web.config in source code control which can lead to deployment headaches later.  Web.config transformations were created to alleviate these types of hassles.

Web Config Transformations

VS 2010 now has support for Web Config Transformations which keep configurations consistent across target environments, making configuration management easier. Once setup, the transformations do this by allowing you to smoothly transition between deployment environments (e.g., debug, release or staging) without having to juggle .config files.  When a deployment package is built, a final version of the web.config specific to that configuration is created.  This happens as the transformation engine parses the transforms in the .config source file and outputs a customized web.config file. 

A config transform file is an XML file that specifies how the web.config file should be changed, by using transform syntax.  You should create one transform file for each configuration environment you need (e.g., debug, release or staging).  The transformation engine combines the source web.config file with the transforms in the transformation file then creates the final web.config ready to deploy. This process works without modifying the web.config or any of the configuration specific .config files.

The steps to create a web.config transformation are as follows:

1. Create a build configuration
2. Add config transforms to project
3. Write transforms
4. Build deployment package
5. Verify transformations

Be sure you add the information you want in the web.config such as connection strings, application settings, etc…If a setting isn’t  in the web.config, it can’t be transformed.

Creating a Web Config Transform:

1. Create a build configuration(s)

Select Configuration Manager to display the Configuration Manager dialog.

Once the dialog is displayed, select <New…> to create a new configuration.

Name your configuration and if you have an existing configuration you’d like to copy settings from, select it in the drop down.

This will also set the current build configuration to the configuration you’ve just created. You can check your configuration by looking in the toolbar area from step one or opening configuration manager.

2. Add Config Transform Files

If you’re starting with a new, greenfield app using VS 2010, you’ll notice there are two config transform files and a web.config file.  The debug and release files are added because there are both debug and release configurations built into each new project as part of the project template, and their naming convention reflects that.  To add your own transform files(s), right click on the web.config file and select Add Config Transforms from the context menu.

Transform files will be created for each configuration you’ve created.  To view the config transform file, open Solution Explorer and you’ll see a new file named web.<yourConfigurationName>.config displayed under the web.config file.  This config transform file follows the same naming convention as the others – in this case, web.staging.config.

You can add transforms to the web.staging.config file now that it’s setup.  You’ll notice the <configuration> element in any of the transform files (but not the web.config) points to the xdt namespace.

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

Since the XML Document Transformations definitions are defined in the xdt namespace, you’ll want to prefix elements in config transform files with xdt: so that transforms can work. 

3. Write Transforms

There are two key components to writing transforms; the transform itself and the locator.  A transform is an instruction in the config transform file that converts elements or sections of the web.config by using a locator.  Transforms define the activity that will happen in the transformation process such as replacing, inserting or deleteing nodes, and can set or remove attributes as well.  Locators are XPath style syntax that find the matching sections in the web.config for transformation.  Locators can find a an exact node match, attribute value matches, and they can also find elements using XPath search expressions.

The transform and locator syntax is as follows:

xdt:Transform=”value” 

xdt:Locator="Condition(XPath expression)"

Transform/locators are embedded right into the element or section you want to transform in the transformation file (not the web.config).  Check with this page of the MSDN documentation on transform and locator attribute values, and how to use transforms/locators in more detail.  The following sample demonstrates using a replace transform in the staging configuration file when the locator can match any element by the name attribute. In the example below, a replace transform on the <add> element will occur when the deployment package is built.

  <connectionStrings>

    <add name="SQLConnection"

      connectionString="Data Source=StagingSQL;Initial Catalog=StagingDB;Integrated Security=True"

      xdt:Transform="Replace" xdt:Locator="Match(name)"/>

  </connectionStrings>

The above config transform replaces the <add> element from web.config that matches the criteria of name=”SQLConnection” when it creates the final .config file.

4. Build Deployment Package

Build the project in Visual studio then right click on the project menu and select Build Deployment Package.  The deployment package is located in a folder specified in the Package/Publish Web tab in the project properties, and defaults to a subdirectory of the \obj\<your configuration name>\ folder (e.g., \obj\Staging).

Once built, the deployment package path is printed to the build output window; just Ctrl+Click the link to open the folder in Visual Studio.  The <projectName>.deploy-readme.txt found here contains detailed directions for using Web Deploy (msdeploy.exe), which is very convenient whether you run the utility yourself or give to sysadmins if you hand off deployments.

5. Verify Transform

Open Solution Explorer and navigate to the \obj\<Config name>\TransformWebConfig\transformed folder.  Look in the web.config and verify the changes. 

Summary

Web.config transformations helps you keep configurations consistent across target environments by creating Config Transforms, an XPath syntax for locating and manipulating config elements.  In Visual Studio 2010, deployment and configuration management has just become a lot easier for the masses.