.NET web.config Transformations

One of the nice features that has been around for a while in .NET is web.config transforms. If you are unfamiliar, these config transforms allow you to create a base config file and then use transform files which only contain the differences between different deployment environments.

Here is an example of a very simple web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
<appSettings>
<add key="WebTransform" value="Raw/Dev"/>
...
</appSettings>
</configuration>

And here is the web.QA.config transform file that would update the key when deployed into the QA environment:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<appSettings>
<add key="WebTransform" value="QA" xdt:Locator="Match(key)" xdt:Transform="Replace" />
</appSettings>
</configuration>

This makes management of the config for each environment much simpler. The only draw back is that the transforms are only performed when either deploying manually or when using Team Foundation Server as your continuous integration system. If you happen to prefer a different CI tool, you will need to perform the config transforms a different way. Here is one way to use this feature from a command line.

First, copy the build targets to the CI agent.
The files can be found in the Visual Studio installation path in the Web folder.
For example: C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web
The files that need to be copied are:
Microsoft.Web.Publishing.Tasks.dll
Microsoft.Web.Publishing.targets

Now you need to create an MSBuild file on the CI agent in the path were the project builds. For this example we will use X:\CIAgent\WebApplication. Name it build_qa.proj and add the following content:
<project defaulttargets="Deploy" toolsversion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

<usingtask assemblyfile="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.Tasks.dll" taskname="TransformXml">

<propertygroup>
<projectpath>X:\CIAgent\WebApplication</projectpath>
<deploypath>X:\CIAgent\WebApplication\Output</deploypath>
<transforminputfile>$(ProjectPath)\Web.config</transforminputfile>
<transformfile>$(ProjectPath)\Web.QA.config</transformfile>
<transformoutputfile>$(DeployPath)\Web.config</transformoutputfile>
<stacktraceenabled>False</stacktraceenabled>
</propertygroup>

<target name="Transform">
<transformxml destination="$(TransformOutputFile)" source="$(TransformInputFile)" stacktrace="$(StackTraceEnabled)" transform="$(TransformFile)">
</transformxml></target>
</usingtask></project>

Now from the command line, run the following command:
\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe X:\CIAgent\WebApplication\build_qa.proj /t:Transform
A transformed web.config will be produced in X:\CIAgent\WebApplication\Output. This file can then be copied directly to your QA web server by using a file copy command from your CI agent.

Of course, this isn't the only way to generate these transformed web.config files. This is just the way we chose to solve the problem with one CI tool on one team. I may share additional methods in the future.