转MSDN 用于 Web 应用程序项目部署的 Web.config 转换语法

用于 Web 应用程序项目部署的 Web.config 转换语法

.NET Framework 4

Web.config 文件通常包括根据应用程序的运行环境而必须不同的设置。例如，在部署 Web.config 文件时，您可能必须更改数据库连接字符串或禁用调试。对于 Web 应用程序项目，ASP.NET 提供了一些工具，用于自动完成在部署这些项目时更改（转换）Web.config 文件的过程。对于要部署到的每个环境，您将创建一个转换文件，该文件仅指定原始 Web.config 文件和适用于该环境的已部署 Web.config 文件之间的差异。

转换文件是一个 XML 文件，该文件指定在部署 Web.config 文件时应如何更改该文件。转换操作通过使用在 XML-Document-Transform 命名空间（映射到 xdt 前缀）中定义的 XML 特性来指定。XML-Document-Transform 命名空间定义两个特性：Locator 和 Transform。Locator 特性指定要以某种方式更改的 Web.config 元素或一组元素。Transform 特性指定要对 Locator 特性所查找的元素执行哪些操作。

下面的示例演示了转换文件的内容，该转换文件将更改连接字符串并替换 customErrors 元素：

复制

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

转换文件的根元素必须在其开始标记中指定 XML-Document-Transform 命名空间，如前面的示例所示。Locator 和 Transform 元素本身不会在部署的 Web.config 文件中重现。

下面各节提供有关要在转换文件中使用的语法的参考信息。

Locator 特性语法

下面每一节说明一个 Locator 特性的语法。

条件

指定一个 XPath 表达式，该表达式会追加到当前元素的 XPath 表达式。选择了与组合 XPath 表达式匹配的元素。

语法

复制

Locator="Condition(XPath expression)"

示例

下面的示例演示如何选择其 name 特性值为 oldname 的连接字符串元素，或其值为 oldprovider 的 providerName 特性。在部署的 Web.config 文件中，所选元素将替换为在转换文件中指定的元素。

复制

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Condition(@name='oldname'
         or @providerName='oldprovider')" />
  </connectionStrings>
</configuration>

作为指定的 Condition 表达式的结果应用于开发 Web.config 文件的有效 XPath 表达式如下所示：

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

此表达式是将当前元素 (configuration/connectionStrings) 的隐式 XPath 条件与显式指定的表达式组合起来的结果。

Match

选择针对指定的一个或多个特性具有匹配值的一个或多个元素。如果指定了多个特性名称，则将仅选择与所有指定特性匹配的元素。

语法

复制

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

示例

下面的示例演示如何选择连接字符串 add 元素，该元素在开发 Web.config 文件的 name 特性中具有 AWLT。在部署的 Web.config 文件中，所选元素将替换为在转换文件中指定的 add 元素。

复制

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

XPath

指定应用于开发 Web.config 文件的绝对 XPath 表达式。（与 Condition 不同，所指定的表达式不追加到与当前元素对应的隐式 XPath 表达式。）

语法

复制

Locator="XPath(XPath expression)"

示例

下面的示例演示如何选择与前面的 Condition 关键字示例中所选元素相同的元素。

复制

<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 特性语法

下面每一节说明一个 Transform 特性的语法。

Replace

将所选的一个或多个元素替换为在转换文件中指定的元素。有关如何使用 Replace 关键字的示例，请参见 Locator 特性的示例。

语法

复制

Transform="Replace"

Insert

将转换文件中定义的元素作为所选的一个或多个元素的同级进行添加。该新元素被添加到任何集合的末尾。

语法

复制

Transform="Insert"

示例

下面的示例演示如何选择开发 Web.config 文件中的所有连接字符串。在部署的 Web.config 文件中，指定的连接字符串将添加到集合的末尾。

复制

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

InsertBefore

将转换 XML 中定义的元素直接插入到由指定 XPath 表达式选择的元素之前。该 XPath 表达式必须是一个绝对表达式，因为它作为一个整体应用于开发 Web.config 文件，而不只是追加到当前元素的隐式 XPath 表达式中。

语法

复制

Transform="InsertBefore(XPath expression)"

示例

下面的示例演示如何选择拒绝所有用户访问的 deny 元素，然后在它之前插入为管理员授予访问权限的 allow 元素。

复制

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

InsertAfter

将转换 XML 中定义的元素直接插入到由指定 XPath 表达式选择的元素之后。该 XPath 表达式必须是一个绝对表达式，因为它作为一个整体应用于开发 Web.config 文件，而不是追加到当前元素的隐式 XPath 表达式中。

语法

复制

Transform="InsertAfter(XPath expression)"

示例

下面的示例演示如何选择为管理员授予访问权限的 allow 元素，然后在它之后插入拒绝指定用户的访问的 deny 元素。

复制

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

移除

移除选定元素。如果选择了多个元素，则移除第一个元素。

语法

复制

Transform="Remove"

示例

下面的示例演示如何选择开发 Web.config 文件中的所有连接字符串 add 元素。在部署的 Web.config 文件中，将仅移除第一个连接字符串元素。

复制

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

RemoveAll

移除选定的一个或多个元素。

语法

复制

Transform="RemoveAll"

示例

下面的示例演示如何选择开发 Web.config 文件中的所有连接字符串。在部署的 Web.config 文件中，将移除所有元素。

复制

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

RemoveAttributes

从所选元素移除指定的特性。

语法

复制

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

示例

下面的示例演示如何选择开发 Web.config 文件中的所有 compilation 元素。（由于配置文件中只能有一个 compilation 元素，因此不必指定 Locator 特性。）在部署的 Web.config 文件中，将从 compilation 元素移除 debug 和 batch 特性。

复制

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

SetAttributes

将所选元素的特性设置为指定的值。Replace 转换特性将替换整个元素，包括其所有特性。相反，SetAttributes 特性使您能够按原样保留元素而只更改所选特性。

语法

复制

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

示例

下面的示例演示如何选择开发 Web.config 文件中的所有 compilation 元素。（由于配置文件中只能有一个 compilation 元素，因此不必指定 Locator 特性。）在部署的 Web.config 文件中，compilation 元素的 batch 特性的值设置为 false。

复制

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

省略 Locator 特性

Locator 特性是可选的。如果未指定 Locator 特性，要更改的元素将由为其指定 Transform 特性的元素隐式指定。在下面的示例中，将替换整个 system.web 元素，因为未指定任何 Locator 特性来指示其他方面。

复制

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

对独立元素使用 Transform 和 Locator 特性

不必在与 Locator 元素相同的元素中设置 Transform 特性。可以在父元素上指定 Locator 元素，以选择要使用其子元素的元素。然后可以在子元素中指定 Transform 特性来将更改应用于子元素。

下面的示例演示如何使用 Locator 特性为指定路径选择 location 元素。但是，只有所选 location 元素的子元素才能进行转换。

复制

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

如果在同一元素或子元素中指定 Locator 特性但未指定 Transform 特性，则不会进行任何更改。

注意

父元素上的 Transform 特性会影响子元素，即使没有为子元素指定任何 Transform 也是如此。例如，如果将特性 xdt:Transform="Replace" 放在 system.web 元素中，则 system.web 元素的所有子元素将替换为转换文件中的内容。