Web.config Transformation Syntax for Web Application Project Deployment

Other Versions

Updated: May 2011

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

Each of the following sections explains the syntax for one Locator attribute.

Condition

Specifies an XPath expression that is appended to the current element's XPath expression. Elements that match the combined XPath expression are selected.

Syntax

Locator="Condition(XPath expression)"

Example

The following example shows how to select connection string elements whose name attribute value is oldname or a providerName attribute whose value is oldprovider. In the deployed Web.config file, the selected elements are replaced with the element that is specified in the transform file.

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

  <connectionStrings>

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

       providerName="newprovider"

       xdt:Transform="Replace"

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

         or @providerName='oldprovider')" />

  </connectionStrings>

</configuration>

The effective XPath expression that is applied to the development Web.config file as a result of the specified Condition expression is the following:

configuration/connectionStrings/add[@name='AWLT' or @providerName='System.Data.SqlClient']

This expression is a result of combining the implicit XPath condition for the current element (configuration/connectionStrings) with the expression that is specified explicitly.

Match

Selects the element or elements that have a matching value for the specified attribute or attributes. If multiple attribute names are specified, only elements that match all the specified attributes are selected.

Syntax

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

Example

The following example shows how to select the connection string add element that has AWLT in the name attribute in the development Web.config file. In the deployed Web.config file, the selected element is replaced with the add element that is specified in the transform file.

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

  <connectionStrings>

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

       providerName="newprovider"

       xdt:Transform="Replace"

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

  </connectionStrings>

</configuration>

XPath

Specifies an absolute XPath expression that is applied to the development Web.config file. (Unlike Condition, the expression that you specify is not appended to the implicit XPath expression that corresponds to the current element.)

Syntax

Locator="XPath(XPath expression)"

Example

The following example shows how to select the same elements that are selected by the preceding example for the Condition keyword.

<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

Each of the following sections explains the syntax for one Transform attribute.

Replace

Replaces the selected element with the element that is specified in the transform file. If more than one element is selected, only the first selected element is replaced. For an example of how to use the Replace keyword, see the examples for the Locator attributes.

Syntax

Transform="Replace"

Insert

Adds the element that is defined in the transform file as a sibling to the selected element or elements. The new element is added at the end of any collection.

Syntax

Transform="Insert"

Example

The following example shows how to select all the connection strings in the development Web.config file. In the deployed Web.config file, the specified connection string is added to the end of the collection.

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

  <connectionStrings>

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

       providerName="newprovider"

       xdt:Transform="Insert" />

  </connectionStrings>

</configuration>

InsertBefore

Inserts the element that is defined in the transform XML directly before the element that is selected by the specified XPath expression. The XPath expression must be an absolute expression, because it is applied to the development Web.config file as a whole; it is not appended only to the current element's implicit XPath expression.

Syntax

Transform="InsertBefore(XPath expression)"

Example

The following example shows how to select the deny element that denies access to all users, and then inserts an allow element before it that grants access to administrators.

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

  <authorization>

    <allow roles="Admins"

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

  </authorization>

</configuration>

InsertAfter

Inserts the element that is defined in the transform XML directly after the element that is selected by the specified XPath expression. The XPath expression must be an absolute expression, because it is applied to the development Web.config file as a whole; it is not appended to the current element's implicit XPath expression.

Syntax

Transform="InsertAfter(XPath expression)"

Example

The following example shows how to select the allow element that grants access to administrators, and inserts a deny element after it that denies access to a specified user.

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

  <authorization>

    <deny users="UserName"

      xdt:Transform="InsertAfter

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

  </authorization>

</configuration>

Remove

Removes the selected element. If multiple elements are selected, removes the first element.

Syntax

Transform="Remove"

Example

The following example shows how to select all the connection string add elements in the development Web.config file. In the deployed Web.config file, only the first connection string element is removed.

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

  <connectionStrings>

    <add xdt:Transform="Remove" />

  </connectionStrings>

</configuration>

RemoveAll

Removes the selected element or elements.

Syntax

Transform="RemoveAll"

Example

The following example shows how to select all the connection strings in the development Web.config file. In the deployed Web.config file, all the elements are removed.

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

  <connectionStrings>

    <add xdt:Transform="RemoveAll" />

  </connectionStrings>

</configuration>

RemoveAttributes

Removes specified attributes from the selected elements.

Syntax

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

Example

The following example shows how to select all the compilation elements in the development Web.config file. (Because there can be only one compilation element in the configuration file, you do not have to specify a Locator attribute.) In the deployed Web.config file, the debug and batchattributes are removed from the compilation element.

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

  <compilation

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

  </compilation>

</configuration>

SetAttributes

Sets attributes for selected elements to the specified values. The Replace transform attribute replaces an entire element including all of its attributes. In contrast, the SetAttributes attribute enables you to leave the element as it is but change selected attributes. If you do not specify which attributes to change, all of the attributes that are present in the element in the transform file are changed.

The SetAttributes transform affects all selected elements. This is different from the Replacetransform attribute, which affects only the first selected element if multiple elements are selected.

Syntax

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

Example

The following example shows how to select all the compilation elements in the development Web.config file. (Because there can be only one compilation element in the configuration file, you do not have to specify a Locator attribute.) In the deployed Web.config file, the value of the compilation element's batch attribute is set to false.

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

  <compilation

    batch="false"

    xdt:Transform="SetAttributes(batch)">

  </compilation>

</configuration>

Omitting Locator Attributes

Locator attributes are optional. If you do not specify a Locator attribute, the element to be changed is specified implicitly by the element that the Transform attribute is specified for. In the following example, the entire system.web element is replaced, because no Locator attribute is specified to indicate otherwise.

<?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.

Change History

Date	History	Reason
May 2011	Corrected the explanation of how the Replace transform works.	Customer feedback.

Community Additions

Config file is a big mistake

It not so easy to implement......i hope microsoft will make better approach than this

Menelio M. Patapat

9/1/2014

This system is way more complicated than it needs to be...

Simplicity is elegant. This is way over engineered. Unless the purpose was to support the new and growing profession of configuration engineer.

Howard Swope

7/25/2014

You guys need to simply this.

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.

ROBOCOPVERSION3014

6/18/2014

is there a way to add a comment?

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

mfinky

8/9/2012

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

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.

Abhishikt Jain

5/30/2012

Web.Config transforms with new line symbol

Exists:

<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?

lAnubisl

12/4/2011

Not all web.config elements have the "file" attribute

@Artem,

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.

Thomas Lee

11/27/2011

Preserve <CRLF> from the transform file?

We use <CRLF> between attributes for readablility, and to make file compares between existing and generated .config files easier to compare.

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?

Thomas Lee

11/27/2011

Managing elements with a different namespace

In case you would like to change some element values (in my case of the Microsoft.Unity framework) within the web.config that have a different schema (not part of the orginal Web.Config schema) then you need to do the following:

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>

zoran maksimovic

10/18/2011

RE: Build with TFS

Good stuff, THANK YOU, tlingenf !!

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.

R0m4n

6/30/2011

Transformation Test Tool

I have created a tool to debug and test web.config transformation. It is found here: http://webconfigtransformationtester.apphb.com/

friism

3/20/2011

How to simply generate the Transformed 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

</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

3/18/2011

XML Formatting may affect some application settings of type String

The "Replace" and "Insert" transform can append linebreaks within an element value. For instance, if you have an application setting that contains a root filepath and use the replace transform in the web config transform it may insert a linebreak after your string value placing the closing </value> tag on the next line. This linebreak will carry over into your application setting if it is of type String.

e.g.

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

</setting>

sks04

3/14/2011

"file" attribute of appSettings node

All of this makes very little sense because you can achieve more by using the "file" attribute of the appSettings node of web.config. This allows you to completely hide from employees (developers and QA, for example) really sensitive company information such as payment gateway account login, production SMTP credentials, production db connection strings, etc. There is nothing more dangerous than an angry developer whom you just fired :) Find and read the documentation of the appSettings, pay attention to its "file" attribute.

https://msdn.microsoft.com/en-us/library/dd465326(VS.100).aspx