Web. config conversion syntax for Web application project deployment

The Web. config file usually includes settings that must be different based on the running environment of the application. For example, when deploying the Web. config file, you may have to change the database connection string or disable debugging. ASP. NET provides some tools for Web application projects to automatically change (convert) The Web. config file when deploying these projects. For each environment to be deployed, you will create a conversion file, which only specifies the differences between the original Web. config file and the deployed Web. config file that applies to the environment.

The conversion file is an XML file that specifies how to change the file when deploying the Web. config file. The conversion operation is specified by using the XML feature defined in the XML-Document-Transform namespace (mapped to the xdt prefix. The XML-Document-Transform namespace defines two features: Locator and Transform. The Locator attribute specifies the Web. config element or a group of elements to be modified in some way. The Transform Feature specifies the operations to perform on the elements to be searched for by the Locator feature.

The following example shows the contents of the conversion file. The conversion file will change the connection string and replace the customErrors element:

Copy

<?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 the conversion file must specify the XML-Document-Transform namespace in its start tag, as shown in the preceding example. The Locator and Transform elements are not reproduced in the deployed Web. config file.

The following sections provide reference information about the syntax to be used in the conversion file.

Locator feature syntax

Each section below describes the syntax of a Locator feature.

Condition

Specify an XPath expression that is appended to the XPath expression of the current element. Elements matching the combination of XPath expressions are selected.

Syntax

Copy

Locator="Condition(XPath expression)"

Example

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

Copy

<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 following is a valid XPath expression that is used as the result of the specified Condition expression to develop the Web. config file:

Configuration/connectionStrings [@ name = 'awlt 'or @ providerName = 'System. Data. sqlclient']

This expression combines the implicit XPath condition of the current element (configuration/connectionStrings) with the explicitly specified expression.

Match

Select one or more elements with matching values for one or more specified features. If multiple feature names are specified, only the elements matching all specified features are selected.

Syntax

Copy

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

Example

The following example shows how to select the add element of the connection string. This element has AWLT in the name feature of the Web. config file. In the deployed Web. config file, the selected element is replaced with the add element specified in the conversion file.

Copy

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Match(name)" />
  </connectionStrings>
</configuration>

Replace

Replace one or more selected elements with the elements specified in the conversion file. For examples of how to use the Replace keyword, see examples of the Locator feature.

Syntax

Copy

Transform="Replace"

XPath

Specifies the absolute XPath expression applied to the development Web. config file. (Unlike Condition, the specified expression is not appended to the implicit XPath expression corresponding to the current element .)

Syntax

Copy

Locator="XPath(XPath expression)"

Example

The following example shows how to select an element that is the same as the element selected in the preceding Condition keyword example.

Copy

<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 Feature syntax

Each section below describes the syntax of A Transform Feature.

Insert

Add the elements defined in the conversion file as the same level of one or more selected elements. The new element is added to the end of any set.

Syntax

Copy

Transform="Insert"

Example

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

Copy

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Insert" />
  </connectionStrings>
</configuration>

InsertBefore

Insert the elements defined in the conversion XML directly before the elements selected by the specified XPath expression. This XPath expression must be an absolute expression because it is applied as a whole to the development Web. config file, not just to the implicit XPath expression of the current element.

Syntax

Copy

Transform="InsertBefore(XPath expression)"

Example

The following example shows how to select a deny element that denies access from all users and insert an allow element that grants access permissions to the administrator before it.

Copy

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

InsertAfter

Insert the elements defined in the conversion XML directly to the elements selected by the specified XPath expression. This XPath expression must be an absolute expression because it is applied to the development Web. config file as a whole, rather than being appended to the implicit XPath expression of the current element.

Syntax

Copy

Transform="InsertAfter(XPath expression)"

Example

The following example shows how to select the allow element that grants access permissions to the Administrator, and then insert the deny element that denies access from the specified user.

Copy

<configuration xmlns:xdt="...">
  <authorization>
    <deny users="UserName"
      xdt:Transform="InsertAfter
        (/configuration/system.web/authorization/allow[@roles='Admins'])" />
  </authorization>
</configuration>

Remove

Removes selected elements. If multiple elements are selected, the first element is removed.

Syntax

Copy

Transform="Remove"

Example

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

Copy

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="Remove" />
  </connectionStrings>
</configuration>

RemoveAll

Removes one or more selected elements.

Syntax

Copy

Transform="RemoveAll"

Example

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

Copy

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="RemoveAll" />
  </connectionStrings>
</configuration>

RemoveAttributes

Removes the specified feature from the selected element.

Syntax

Copy

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

Example

The following example shows how to select and develop all the compilation elements in the Web. config file. (The configuration file can have only one compilation element, so you do not need to specify the Locator feature .) In the deployed Web. config file, the debug and batch features are removed from the compilation element.

Copy

<configuration xmlns:xdt="...">
  <compilation 
    xdt:Transform="RemoveAttributes(debug,batch)">
  </compilation>
</configuration>

SetAttributes

Set the feature of the selected element to the specified value. The Replace Conversion Feature replaces the entire element, including all its features. In contrast, the SetAttributes feature enables you to retain elements as they are and only change the selected features.

Syntax

Copy

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

Example

The following example shows how to select and develop all the compilation elements in the Web. config file. (The configuration file can have only one compilation element, so you do not need to specify the Locator feature .) In the deployed Web. config file, set the batch attribute value of the compilation element to false.

Copy

<configuration xmlns:xdt="...">
  <compilation 
    batch="false"
    xdt:Transform="SetAttributes(batch)">
  </compilation>
</configuration>

XSLT

Apply the XSLT file to the selected element.

Syntax

Copy

Transform="XSLT(file path)"

Example

The following example shows how to select the appSettings element and specify the transformations defined in the appSettings. xslt file.

Copy

<configuration xmlns:xdt="...">
  <appSettings
    xdt:Transform="XSLT(C:\MyProject\appSettings.xslt)" />
  </appSettings>
</configuration>

Locator is omitted.

The Locator feature is optional. If the Locator attribute is not specified, the element to be modified is implicitly specified by the element that specifies the Transform attribute for it. In the following example, the entire system. web element is replaced, because no Locator attribute is specified to indicate other aspects.

Copy

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

Use the Transform and Locator features for independent elements

 

You do not need to set the Transform Feature in the same element as the Locator element. You can specify the Locator element on the parent element to select the element to use its child element. You can then specify the Transform Feature in the child element to apply the change to the child element.

The following example shows how to use the Locator feature to select the location element for a specified path. However, only the child elements of the selected location element can be converted.

Copy

<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 the Locator feature is specified in the same element or sub-element but the Transform feature is not specified, no changes will be made.

Description
The Transform Feature on the parent element affects the child element, even if no Transform is specified for the child element. For example, if the feature xdt: Transform = "Replace" is placed in the system. web element, all child elements of the system. web element are replaced with the content in the conversion file.