Web アプリケーション プロジェクト配置の Web.config 変換構文

Web.config ファイルには、通常、アプリケーションが実行される環境に応じて変える必要がある設定が含まれています。 たとえば、Web.config ファイルを配置するときに、データベース接続文字列を変更したり、デバッグを無効にしたりする必要がある場合があります。 Web アプリケーション プロジェクトの場合は、配置時の Web.config ファイルの変更 (変換) プロセスを自動化するツールが ASP.NET に用意されています。 配置先の環境ごとに、その環境用の、元の Web.config ファイルと配置する Web.config ファイル間の差分のみを指定する変換ファイルを作成します。

変換ファイルは、Web.config ファイルの配置時の変更方法を指定する XML ファイルです。 変換操作は、xdt プレフィックスにマップされる XML-Document-Transform 名前空間で定義されている XML 属性を使用して指定します。 XML-Document-Transform 名前空間では、Locator と Transform の 2 つの属性が定義されています。 Locator 属性で、なんらかの方法で変更する Web.config の 1 つまたは一連の要素を指定します。 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 ファイルでは再作成されません。

以降のセクションでは、変換ファイルで使用する構文についてのリファレンス情報を示します。

Locator 属性の構文

以下の各セクションでは、特定の Locator 属性の構文について説明しています。

状態

現在の要素の XPath 式に追加される XPath 式を指定します。 結合された XPath 式に一致する要素が選択されます。

構文

Locator="Condition(XPath expression)"

例

次の例は、name 属性の値が oldname であるか、または providerName 属性の値が oldprovider である接続文字列要素を選択する方法を示しています。 配置される 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

指定した 1 つ以上の属性に一致する値を持つ 1 つ以上の要素を選択します。 複数の属性名を指定した場合は、指定したすべての属性に一致する要素のみが選択されます。

構文

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"

[挿入]

変換ファイルで定義されている要素を、選択された 1 つ以上の要素の兄弟として追加します。 新しい要素は、任意のコレクションの末尾に追加されます。

構文

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 式は、絶対式である必要があります。これは、この XPath 式は、現在の要素の暗黙的な XPath 式だけに追加されるのではなく、開発用の Web.config ファイル全体に適用されるためです。

構文

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 式は、絶対式である必要があります。これは、この XPath 式は、現在の要素の暗黙的な XPath 式に追加されるのではなく、開発用の Web.config ファイル全体に適用されるためです。

構文

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

選択された 1 つ以上の要素を削除します。

構文

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 要素は構成ファイル内に 1 つしか存在しないため、Locator 属性を指定する必要はありません)。 配置される Web.config ファイルでは、debug 属性と batch 属性が compilation 要素から削除されます。

<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 要素は構成ファイル内に 1 つしか存在しないため、Locator 属性を指定する必要はありません)。 配置される Web.config ファイルでは、compilation 要素の batch 属性の値が false に設定されます。

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

Locator 属性の省略

Locator 属性は省略できます。 Locator 属性を指定しない場合、変更する要素は、Transform 属性が指定される要素によって暗黙的に指定されます。 次の例では、対象を示す Locator 属性が指定されていないため、system.web 要素全体が置き換えられます。

<?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 属性を同じ要素または子要素に指定しない場合は、何も変更されません。

参照

概念

ASP.NET Web アプリケーション プロジェクトの配置の概要

チュートリアル: Web 配置パッケージを使用した Web アプリケーション プロジェクトの配置 (パート 1/4)

履歴の変更