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

更新:2011 年 5 月

Web.config 檔包含的設定,通常需根據應用程式的執行環境而改變。 例如,部署 Web.config 檔時,可能必須變更資料庫連接字串或是停用偵錯功能。 對於 Web 應用程式專案,ASP.NET 有提供工具,可在部署 Web.config 檔時自動化此項變更 (轉換) 程序。 對於您要進行部署的每個環境,您需建立轉換檔,以指定該環境的原始 Web.config 檔和所部署 Web.config 檔之間的差異。

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

條件

指定在目前項目的 XPath 運算式後面加上的 XPath 運算式。 會選取符合合併之 XPath 運算式的項目。

語法

Locator="Condition(XPath expression)"

範例

下列範例顯示如何選取其 name 屬性值為 oldname 的連接字串項目,或是其值為 oldproviderproviderName 屬性。 在所部署的 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)"

範例

下列範例顯示如何選取開發 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 屬性的語法。

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>

Remove

移除選取的項目。 如果選取多個項目,則移除第一個項目。

語法

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 項目中移除 debugbatch 屬性。

<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 屬性,則要變更的項目會由 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 屬性來選取指定之路徑的 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 項目底下的所有子項目。

日期

記錄

原因

2011 年 5 月

更正有關 Replace 轉換運作方式的說明。

客戶回函。

顯示: