使用 Visual Studio 之 Web 應用程式專案部署的 Web.config 轉換語法

本主題提供有關 xdt:Transform 語法的參考資訊，而且您在 Web.config 所使用的 xdt:Locator 屬性轉換在下列產品的檔案:

• Visual Studio 2012

• Visual Studio Express 2012 for Web

• 使用的Visual Studio 2010Visual Studio Web 發行更新

• 使用的Visual Web Developer 2010 ExpressVisual Studio Web 發行更新

轉換檔是一個 XML 檔，其中指定 Web.config 檔在部署時應如何變更。 轉換動作是以 XML-Document-Transform 命名空間中定義的 XML 屬性指定，該命名空間會對應至 xdt 前置詞。 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 屬性的語法。

條件

指定在目前項目的 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)"

範例

下列範例顯示如何選取開發 Web.config 檔中 name 屬性為 AWLT 的連接字串 add 項目。 在所部署的 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 插入項目，在 deny 項目才能授與系統管理員之前的輸入。

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

Transform 屬性不需要和 Locator 項目設定在相同的項目中。 您可以在父項目上指定 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 也是如此。例如，如果您在 system.web 項目中加上 xdt:Transform="Replace" 屬性，則會以轉換檔的內容取代 system.web 項目底下的所有子項目。

請參閱

概念

Visual Studio 及 ASP.NET 的 Web 部署內容對應

其他資源

Web.config 檔案轉換 (教學課程的 ASP.NET 網站)