Visual Studio を使用する Web アプリケーションプロジェクト配置の Web.config 変換構文

[アーティクル]
11/15/2012

このトピックでは 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 発行の更新

変換ファイルは、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 ファイルでは再作成されません。

変換、配置時に適用され、Visual Studio の変更のプレビューを表示できます。 ソリューションエクスプローラーでは、変換ファイル (Web.Release.config) を右クリックし、プレビューの変換を選択します。 Visual Studio は、元の Web.config ファイルと変換された 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/add[@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 の要素を選択する方法を示しています。次に、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 では、要素はそのままにして、選択された属性を変更できます。変更する属性を指定する変換ファイルの要素に含まれる属性をすべてが変更されます。

SetAttributes の変換はすべての要素に影響します。この動作は、複数の要素が選択されている場合は、最初に選択された要素にのみ影響する Replace の変換の属性とは異なります。

構文

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

注意

親要素に対し指定された Transform 属性は、たとえその子要素に Transform が指定されていなくても、それらの子要素に影響を及ぼします。たとえば、属性 xdt:Transform="Replace" を system.web 要素に配置した場合、system.web 要素の子であるすべての要素が、変換ファイルの内容に置き換えられます。

参照

概念

Visual Studio および ASP.NET の Web 配置コンテンツマップ

その他の技術情報

Web.config ファイルの変換 (ASP.NET Web サイトのチュートリアル)

Visual Studio を使用する Web アプリケーション プロジェクト配置の Web.config 変換構文