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

本主题提供有关 xdt:Transform 语法的信息，并在Web.config使用的 xdt:Locator 属性将以下产品的文件:

• Visual Studio 2012

• Visual Studio Express 2012 for Web

• 与 的Visual Studio 2010 Visual Studio Web发布更新

• 与 的Visual Web Developer 2010 Express Visual Studio Web发布更新

转换文件是一个 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="https://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 文件中重现。

转换在部署过程中应用的，但是，您可以看到更改的预览在Visual Studio中的。 在 解决方案资源管理器，右击转换文件(例如，Web.Release.config)并选择 预览转换。 Visual Studio并行显示原始Web.config文件和已转换的Web.config文件。

Locator 特性语法

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

Condition

指定一个 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/add[@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 元素。 然后插入到 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 特性使您能够按原样保留元素而只更改所选特性。 如果不指定哪些属性更改，它出现在转换文件中的元素更改的所有属性。

SetAttributes 变换影响所有选定的元素。 此行为与 Replace 不同转换特性，仅影响第一个选定的元素，如果选择了多个元素。

语法

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="https://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 特性，则不会进行任何更改。

请参见

概念

用于 Visual Studio 和 ASP.NET 的 Web 部署内容映射

其他资源

Web.config文件转换(指南在ASP.NET网站)