[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
For Web application deployment, Visual Studio 2010 introduces Web.config transformation, which is a feature that lets you change a Web.config file from using development settings to using production settings. Transformation settings are specified in transform files named for the configuration setting, such as web.debug.config, web.release.config, and so on. The names of these files match MSBuild configuration settings.
A transform file includes the changes that you must make to a deployed Web.config file. You specify the changes by using XML attributes.
The following example shows a part of a web.release.config file that might be produced for deployment using a release configuration. The Replace keyword in the example specifies that during deployment, the connectionString node in the Web.config file will be replaced with the values that are listed in the example.
<connectionStrings xdt:Transform="Replace">
<add name="BlogDB" connectionString="connection string detail]" />
</connectionStrings>
The Web.config transformation feature includes a transformation engine and a set of attributes that specify transformation options.
The transformation engine performs the following tasks:
Identifies nodes in the transform XML that must be transformed. The engine uses the Locator attribute to identify nodes that will be changed.
Pulls out the nodes from the source XML based on the identified nodes from the transform XML.
Applies the transforms to the specified nodes of the source XML and writes transformed versions of the nodes to the destination XML. The engine uses the Transform attribute to determine what change to apply.
.gif) Note |
|---|
The transformation engine applies the XML DOM to all XML files. Therefore, the destination XML file, the source XML file, and the transform XML file must all be well-formed XML documents. |
The Locator and Transform Attributes
Transformation options are specified 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 namespace must be registered to use Web.config transformations. For example, the web.release.config node would resemble the following:
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
Each attribute can take values that specify a node's location when they are used with the Locator attribute, and to define an action when they are used with the Transform attribute.
The following table shows keywords used with the Locator attribute.
Keyword | Syntax | Comments |
|---|
Match |
<connectionStrings>
<add name="Northwind" connectionString="connection string detail"
providerName="System.Data.SqlClient"
xdt:Transform="Replace"
xdt:Locator="Match(name)" />
</connectionStrings>
| Creates an XPath expression that selects an element only if the value in the transform XML matches the corresponding value in the source Web.config file. The Match keyword can take multiple values. In the syntax example, the Replace transform occurs only when the name Northwind matches a value in the connection string in the source Web.config file. |
Condition |
<connectionStrings>
<add name="Northwind"
connectionString="connection string detail"
providerName="System.Data.SqlClient"
xdt:Transform="Replace"
xdt:Locator="Condition(@name=’Northwind or @providerName=' System.Data.SqlClient')" />
</connectionStrings>
| Creates an XPath expression that is appended to the current element if the XPath expression that has the predicate condition matches the corresponding XPath expression in the source Web.config file. This XPath expression is then used to locate the correct node in the source Web.config file. |
XPath |
<location path="c:\MySite\Admin" >
<system.web xdt:Transform="Replace" xdt:Locator="XPath(//system.web)">
...
</system.web>
<location>
| Uses an XPath expression to identify the element in the source Web.config file to be transformed into the destination XML. This keyword supports complex XPath expressions for identifying the source Web.config file nodes in the syntax. In the syntax example, the XPath expression enables the user to replace the system.web section regardless of where it is located in the Web.config file. |
The following table shows keywords that are used with the Transform attribute.
Keyword | Syntax in the transform XML (for example, web.release.config) | Comments |
|---|
Replace |
<assemblies xdt:Transform="Replace">
<add assembly="System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
</assemblies>
| Replaces the matching element and all its children from the transform XML (web.release.config) in the destination Web.config file. |
Remove |
<assemblies xdt:Transform="Remove">
</assemblies>
| Removes the first matching element and all its children from the destination Web.config file. |
RemoveAll |
<connectionStrings>
<add xdt:Transform="RemoveAll"/>
</connectionStrings>
| Removes all the matching elements under the current parent node from the destination Web.config file. |
Insert |
<authorization>
<deny users="*" xdt:Transform="Insert"/>
</authorization>
| Adds the element defined in transform XML to the bottom of the list of all the siblings in the destination Web.config file. |
SetAttributes |
<compilation
batch="false"
xdt:Transform="SetAttributes(batch)">
</compilation>
| Reads the value of the specified attributes from the transform XML and sets the attributes of the matching element in the destination Web.config file. This keyword takes a comma-separated list of attributes. |
RemoveAttributes |
<compilation xdt:Transform="RemoveAttributes(debug,batch)">
</compilation>
| Removes the specified attributes from the destination Web.config file. The syntax example shows how to remove multiple attributes. |
InsertAfter (XPath) |
<authorization>
<deny users="AName" xdt:Transform="InsertAfter(/configuration/system.web/authorization/ allow[@roles='Admins']") />
</authorization>
| Inserts the element defined in the transform XML directly after the specified element. In the syntax example, the <deny users="AName" /> element will be inserted after the <allow roles="Admins" /> element in the destination Web.config file. |
InsertBefore (XPath) |
<authorization>
<allow roles=" Admins" xdt:Transform="InsertBefore(/configuration/system.web/authorization/ deny[@users='*'])" />
</authorization>
| Inserts the element defined in the transform XML directly before the specified element. In the syntax example, the <allow roles="Admins" /> element will be inserted before the <deny users="*" /> element in the destination Web.config file. |
XSLT (filePath) |
<appSettings xdt:Transform="XSLT(V:\MyProject\appSettings.xslt)">
</appSettings>
| Reads the element defined in the source XML and applies the XSLT transform specified in the transform XML to replace the matching element in the destination Web.config file. In the syntax example, the transform engine reads the appSettings element from the source and applies the XSLT transform specified in appSettings.xslt to produce the new appSettings element in the destination Web.config file. |
For more information about how to use Web.config transforms, see Walkthrough: Using Web.config Transformation When Deploying a Web Application.
Concepts