Use Visual Studio web.config transform for debugging

• Visual Studio, ASP.NET

I have a Visual Studio project which is under version control and is developed by several people, all of whom need to have different database and logfile settings during development. Visual Studio has built-in support for Config Transforms for web.config files; all you need to do is right-click the web.config file in the solution explorer and click 'Add Config Transforms'. However, these transforms are applied only when publishing the project, not when debugging it using Visual Studio.

The solution to this is to implement the config transforms manually with a pre-build task and leave the debug transform out of version control, so each developer can have their own copy.

Setup

Step 1: Create base web.config file

Rename your existing web.config file to web.base.config. This file will be transformed by the web.configuration.transform.config files to create the final web.config file.

You will probably also want to add the autogenerated web.config to the list of files ignored by your version control system, as it will vary depending on which configuration you build with.

Step 2: Create transform files

For each build configuration (e.g. Debug and Release), create a web.configuration.transform.config (e.g. web.Debug.transform.config) file with the following contents:

<?xml version="1.0"?>
<!-- For more information on using web.config transformation visit http://go.microsoft.com/fwlink/?LinkId=125889 -->
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

</configuration>

These files specify how to transform the web.base.config file for each build configuration. The section on Useful transform file snippets below explains how to use this file.

Step 3: Add reference to Microsoft Web Publishing Tasks library

The Microsoft Web Publishing Tasks library comes with Visual Studio, and is installed to C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\VS Version\Web\. It provides the TransformXml build task which we need to generate the final web.config file from the base file and the transform file.

To add a reference to it in your project, right-click 'References' and choose 'Add Reference...'. Browse to C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\VS Version\Web\ and select Microsoft.Web.Publishing.Tasks.Dll.

Step 4: Create Project.wpp.targets

Next to the .csproj file for your project, create a .wpp.targets file with the same name. For example, if your project file is Website.csproj, make a file called Website.wpp.targets.

This file should have the following contents:

<?xml version="1.0" encoding="utf-8"?>
<!-- You may find the following file helpful when editing this .wpp.targets file:
  C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets
-->
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <UsingTask TaskName="TransformXml" AssemblyName="Microsoft.Web.Publishing.Tasks.dll" />

  <!-- This target will run right before you run your app in Visual Studio -->
  <Target Name="UpdateWebConfigBeforeRun" BeforeTargets="Build">
    <Message Text="Configuration: $(Configuration): web.$(Configuration).transform.config"/>
    <TransformXml Source="web.base.config"
              Transform="web.$(Configuration).transform.config"
              Destination="web.config" />
  </Target>

  <!-- Exclude the config template files from the created package -->
  <Target Name="ExcludeCustomConfigTransformFiles" BeforeTargets="ExcludeFilesFromPackage">
    <ItemGroup>
      <ExcludeFromPackageFiles Include="web.base.config;web.*.transform.config"/>
    </ItemGroup>
    <Message Text="ExcludeFromPackageFiles: @(ExcludeFromPackageFiles)" Importance="high"/>
  </Target>
</Project>

Important Note: Visual Studio does not reload this file when you change it; when you modify this file you will need to quit and restart Visual Studio.

After you have restarted Visual Studio you should be able to build the project and have the web.config file autogenerated for your configuration.

Useful transform file snippets

These are a few examples of simple things you can do to your web.config file. The XML Document Transform language is very powerful, and can be used to change the web.config file however you want.

The MSDN document Web.config Transformation Syntax for Web Application Project Deployment explains the full syntax and is very useful for figuring out how to do what you want.

Enable debug mode

<?xml version="1.0"?>
<!-- For more information on using web.config transformation visit http://go.microsoft.com/fwlink/?LinkId=125889 -->
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.web>
    <compilation xdt:Transform="SetAttributes(debug)" debug="true" />
  </system.web>
</configuration>

Disable cache

<?xml version="1.0"?>
<!-- For more information on using web.config transformation visit http://go.microsoft.com/fwlink/?LinkId=125889 -->
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location xdt:Locator="Match(path)" path="cache"> <!-- XDT: Find the <location> element where path="cache"... -->
    <system.webServer>
      <staticContent>
        <!-- ... and set the cacheControlMode attribute of <clientCache> to "DisableCache" -->
        <clientCache xdt:Transform="SetAttributes(cacheControlMode)" cacheControlMode="DisableCache"/>
      </staticContent>
    </system.webServer>
  </location>
</configuration>

Sources