Web.config files typically include settings that have to be different depending on which environment the application is running in. For example, you might have to change a database connection string or disable debugging when you deploy a Web.config file. For Web application projects, ASP.NET provides tools that automate the process of changing (transforming) Web.config files when they are deployed. For each environment that you want to deploy to, you create a transform file that specifies only the differences between the original Web.config file and the deployed Web.config file for that environment.

A transform file is an XML file that specifies how the Web.config file should be changed when it is deployed. Transformation actions are specified by using XML attributes that are defined in the XML-Document-Transform namespace, which is mapped to the xdt prefix. The XML-Document-Transform namespace defines two attributes: Locator and Transform. The Locator attribute specifies the Web.config element or set of elements that you want to change in some way. The Transformattribute specifies what you want to do to the elements that the Locator attribute finds.

The following example shows the contents of a transform file that changes a connection string and replaces the customErrors element:

<?xml version="1.0"?>

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

  <connectionStrings>

    <add name="MyDB"

      connectionString="value for the deployed Web.config file"

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

  </connectionStrings>

  <system.web>

    <customErrors defaultRedirect="GenericError.htm"

      mode="RemoteOnly" xdt:Transform="Replace">

      <error statusCode="500" redirect="InternalError.htm"/>

    </customErrors>

  </system.web>

</configuration>

The root element of a transform file must specify the XML-Document-Transform namespace in its opening tag, as shown in the preceding example. The Locator and Transform elements themselves are not reproduced in the deployed Web.config file.

This following sections provide reference information about the syntax to use in transform files.

Locator Attribute Syntax

Locator="Condition(XPath expression)"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add name="AWLT" connectionString="newstring"

       providerName="newprovider"

       xdt:Transform="Replace"

       xdt:Locator="Condition(@name='oldname'

         or @providerName='oldprovider')" />

  </connectionStrings>

</configuration>

Locator="Match(comma-delimited list of one or more attribute names)"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add name="AWLT" connectionString="newstring"

       providerName="newprovider"

       xdt:Transform="Replace"

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

  </connectionStrings>

</configuration>

Locator="XPath(XPath expression)"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add name="AWLT" connectionString="newstring"

       providerName="newprovider"

       xdt:Transform="Replace"

       xdt:Locator="XPath(configuration/connectionStrings[@name='AWLT'

         or @providerName='System.Data.SqlClient'])" />

  </connectionStrings>

</configuration>

Transform Attribute Syntax

Transform="Replace"

Transform="Insert"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add name="AWLT" connectionString="newstring"

       providerName="newprovider"

       xdt:Transform="Insert" />

  </connectionStrings>

</configuration>

Transform="InsertBefore(XPath expression)"

<configuration xmlns:xdt="...">

  <authorization>

    <allow roles="Admins"

      xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />

  </authorization>

</configuration>

Transform="InsertAfter(XPath expression)"

<configuration xmlns:xdt="...">

  <authorization>

    <deny users="UserName"

      xdt:Transform="InsertAfter

        (/configuration/system.web/authorization/allow[@roles='Admins'])" />

  </authorization>

</configuration>

Transform="Remove"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add xdt:Transform="Remove" />

  </connectionStrings>

</configuration>

Transform="RemoveAll"

<configuration xmlns:xdt="...">

  <connectionStrings>

    <add xdt:Transform="RemoveAll" />

  </connectionStrings>

</configuration>

Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"

<configuration xmlns:xdt="...">

  <compilation

    xdt:Transform="RemoveAttributes(debug,batch)">

  </compilation>

</configuration>

Transform="SetAttributes(comma-delimited list of one or more attribute names)"

<configuration xmlns:xdt="...">

  <compilation

    batch="false"

    xdt:Transform="SetAttributes(batch)">

  </compilation>

</configuration>

Omitting Locator Attributes

<?xml version="1.0"?>

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

  <system.web xdt:Transform="Replace">

    <customErrors defaultRedirect="GenericError.htm"

      mode="RemoteOnly">

      <error statusCode="500" redirect="InternalError.htm"/>

    </customErrors>

  </system.web>

</configuration>

Using Transform and Locator Attributes on Separate Elements

A Transform attribute does not have to be set in the same element as a Locator element. You can specify a Locator element on a parent element in order to select elements whose child elements you want to work with. You can then specify a Transform attribute in a child element in order to apply a change to the children.

The following example shows how to use the Locator attribute to select location elements for the specified path. However, only elements that are children of the selected location elements are transformed.

 

 

<configuration xmlns:xdt="...">

  <location path="C:\MySite\Admin" xdt:Locator="Match(path)">

    <system.web>

      <pages viewStateEncryptionMode="Always"

        xdt:Transform="SetAttributes(viewStateEncryptionMode)" />

    </system.web>

  </location>

</configuration>

If you specify a Locator attribute but you do not specify a Transform attribute in the same element or in a child element, no changes are made.

Note
A Transform attribute on a parent element can affect child elements even if no Transform is specified for them. For example, if you put the attribute xdt:Transform="Replace" in the system.web element, all the elements that are children of the system.web element are replaced with the content from the transform file.

See Also

Change History

Have you guys took a look at rails framework. It automatically sets up debug, QA and dev environments.

Depending on which DB you are using you need to find the config file and set the server credentials.

This article puts me to sleep.

Is there a way to add a comment to a customized web.config?

Example:
In web.prod.config:
<!--

 Web.Config for the PRODUCTION server 

-->

in web.QA.config:
<!--

Web.Config for the Q.A. server 

-->

Thanks,
Marcelo

Is there way to do "InsertAtTop", basically the "Insert" add the node at the end, is there a way to add it as the first node?

InsertBefore isn't useful, as we may not know what's the current first node in source xml.

<applicationSettings>
     <ADM.Web.Admin.ADMSettings>
          <settingname="ApplicationWebAddress"serializeAs="String">
              <value>http://localhost:8929</value>
          </setting>
     </ADM.Web.Admin.ADMSettings>
</applicationSettings>
Do transform:

<settingname="ApplicationWebAddress"serializeAs="String"xdt:Transform="Replace"xdt:Locator="Match(name)">
     <value>http://live.site.com</value>
</setting>

Get a config with new line character:

<settingname="ApplicationWebAddress"serializeAs="String">
     <value>http://live.site.com
     </value>
</setting>

Anyone knows how to solve this issue?

While it is true you can use the file attribute for appSettings instead, it is not true that you can use it for all elements. For instance, we write a log of WCF applications. The system.service.model element does not have a file attribute, and we must provide overrides to have diffent endpoints, bindings, etc. for different environment configurations.

The article is about how to write transforms. Using <appSettings> as an example is just an easy pedagogical technique, since everyone is so familiar with that element.

It seems that the transform tool ignores, somewhat randomly, our <CRLF> characters between attributes. Is there a way to preserve them?

Or is there a way (particularly in a continuous build/deploy environment) to apply the formatting rules in Visual Studio for XML files to the generated output?

1) Add the (new) schema in question to the <configuration> element. For example:

<

configurationxmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform" xmlns:u="http://schemas.microsoft.com/practices/2010/unity">

2) In case you need to set an attribute on the alias tag within Unity, then use the following

<

u:unity>

<u:alias    alias="yourAliasGoesHere" 
                type="yourTypeGoesHere"
                xdt:Transform="SetAttributes"
                xdt:Locator="Match(alias)"/>

</u:unity>

To use the web.config transformations you need to use a compatable web project and have it properly configured for each of your build configurations. For more information see: http://msdn.microsoft.com/en-us/library/dd483479.aspx

You can use TFS to build your web projects and it too can perform the web.config transformations. To do this you can include the following MSBuild command-line parameters /p:CreatePackageOnPublish=true /p:DeployOnBuild=True. If you are using TFS 2008 place each parameter on a separate line in the TFSBuild.rsp file. On build, you will get a new folder for your project package under the drop folder's _PublishedWebsites folder that contains your web deployment configuration package with the transformed web.config.

For testing your transformation or for a low-key transformation (avoiding a full publish of the project) you can add this custom task in your *.csproj

<UsingTask TaskName="TransformXml" AssemblyFile="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.Tasks.dll" />

<Target Name="Transform">

<MakeDir Directories="obj\$(Configuration)" Condition="!Exists('obj\$(Configuration)')" />

<TransformXml Source="Web.Config" Transform="Web.$(Configuration).config" Destination="obj\$(Configuration)\Web.config" StackTrace="true" />

</Target>

Afterwards you can generate the transformation using :

call "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat"

"msbuild" "D:\Solutions\Web.csproj" /m /t:Transform /p:Configuration=QA

Regards,

Jan Hebnes

e.g.

<setting name="VersionDate" serializeAs="String">
    <value>14th September 2010
    </value>

</setting>