設定変換の適用

概要

XDT ベースの設定変換を適用する方法について説明します。

Sitecore の実装では、Web.configConnectionStrings.configDomains.configLayers.config など、Sitecore の設定パッチでは変更できない設定ファイルの修正が必要になることがよくあります。このような場合は、代わりに XDT 変換ファイルを使用します。

このトピックでは、Sitecore の Docker イメージを構築する際に、これらの XDT ベースの設定変換を適用する方法を紹介します。変換ファイルは、ソリューション内に存在する場合と、特定の Sitecore ロール用の Dockerfile にローカルに存在する場合があります。この例では、Sitecore Experience Management (XM1) インスタンスを使用しています。

Docker Examples リポジトリのクローンをまだ作成していない場合は、コンピューター上の C:\sitecore\docker-examples\ などの場所に作成します (例のクローン先は、このフォルダーになっています)。この例の custom-images フォルダーを使用します。

custom-imagesの例では、実行する前にいくつかの準備が必要です。まだ準備をしていない場合は、準備の手順に従うか、付属の init.ps1 スクリプトを実行して、これらの準備手順を自動的に実行してください。

  • PowerShell 管理者プロンプトを開き、custom-imagesフォルダーに移動して、このコマンドを実行し、-LicenseXmlPath を Sitecore ライセンス ファイルの場所に置き換えます。

    .\init.ps1 -LicenseXmlPath C:\License\license.xml

Docker サンプル ソリューションには、カスタムのDocker-Examples HTTP ヘッダーを操作する、Web.config 用の 2 つの XDT 設定変換ファイルが含まれています。custom-images フォルダーに移動して以下の変換ファイルを確認してください。

  • \src\DockerExamples.Website\Web.config.xdt

    この変換ファイルはソリューション内にあるため、すべてのコア Sitecore ロール (XM1 トポロジの CMとCD) に適用されます。これは、ソリューションの変換の例です。ここでは、Docker-Examples の HTTP ヘッダーを追加し、それを Solution transform に設定しています。

    <?xml version="1.0" encoding="utf-8"?>
    <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
      <system.webServer>
        <httpProtocol>
          <customHeaders>
            <add name="Docker-Examples" xdt:Locator="Match(name)" value="Solution transform" xdt:Transform="InsertIfMissing" />
          </customHeaders>
        </httpProtocol>
      </system.webServer>
    </configuration>
  • \docker\build\cm\transforms\Web.config.xdt

    この変換ファイルは、cm サービスのローカルの docker\build フォルダーにあります。これはロール変換の例です。Docker-Examples の HTTP ヘッダーを Role transform に変更しています。

    <?xml version="1.0" encoding="utf-8"?>
    <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
      <system.webServer>
        <httpProtocol>
          <customHeaders>
            <add name="Docker-Examples" xdt:Locator="Match(name)" value="Role transform" xdt:Transform="SetAttributes(value)" />
          </customHeaders>
        </httpProtocol>
      </system.webServer>
    </configuration>

ヒント

複数の変換を適用するときは、操作の順序を考慮することをお勧めします。ただし、変換は毎回新しい設定ファイルに適用されるため、変換がべき等であることを確認する必要はありません。

この例では、最初にソリューションの変換を適用し、次にロールの変換を適用します。

すべてのコア Sitecore ロールに適用する設定変換を、ソリューション構造に直接保存します。

次の例では、専用のソリューション ビルド アーティファクトを使用して、ソリューションの変換を収集して適用しています。このアプローチの利点は、同じ設定ファイルに対して複数の変換をサポートすることです。これは、Sitecore Helix ソリューションでよく使用されます。

たとえば、レイヤー間に以下の複数の Web.config 変換がある場合があります。

  • \src\Foundation\[Module Name]\website\Web.config.xdt

  • \src\Feature\[Module Name]\website\Web.config.xdt

  • \src\Project\[Module Name]\website\Web.config.xdt

この設定では、これらすべてをビルド出力に含めると (つまり、Build ActionContent に設定すると)、1 つだけが出力されて最終的に適用されます。代わりに、これらのファイルを個別に除外して (つまり、Build ActionNone に設定して)、ソリューションのビルド イメージに別々に収集できます。

変換ファイルをメインのビルド出力に残し、Web ルートで「その場で」変換を実行することもできますが、同じ設定ファイルに対して複数の変換がサポートされないという欠点があります。

ソリューションのビルドで設定する

custom-images フォルダーに移動して、フォルダー内の Dockerfile を確認します。

変換ファイル (.xdt 拡張子) は builder ステージ内で収集され、C:\out\transforms にドロップされていることがわかります。ここでは、robocopy を (/s フラグと一緒に) 使用することが、フォルダー構造を保持するために重要です。

RUN Invoke-Expression 'robocopy C:\build\src C:\out\transforms /s /ndl /njh /njs *.xdt'

これは msbuild の前に行われるため、ビルド出力から除外されていない余分な .xdt ファイルを拾う必要がないことに注意してください。これらのファイルは、builder ステージから最終イメージへと \artifacts\transforms の構造でコピーされます。

COPY --from=builder C:\out\transforms .\transforms\

Sitecore ランタイム イメージに適用する

ランタイム イメージに変換を適用するには:

  1. cm サービスの Sitecore ランタイム Dockerfile を開きます。先ほど収集したソリューション変換がコピーされ、\transforms\solution\ に配置されているのがわかります。

    COPY --from=solution \artifacts\transforms\ \transforms\solution\
  2. 開発ツールを tooling イメージから (C:\tools に) コピーし、Invoke-XdtTransform.ps1 スクリプトを使用して変換を適用します。

    COPY --from=tooling \tools\ \tools\
    RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\solution\DockerExamples.Website

Invoke-XdtTransform.ps1 スクリプトは、 -Path-XdtPath のパラメーターに 2 つのフォルダーを受け入れます。フォルダーを使用する場合、次の点に注意します。

  • -XdtPath のフォルダー構造が -Path と一致する必要があります。

  • -XdtPathに配置した変換ファイルは、設定に一致する名前を付け、ファイル拡張子として .xdt を追加する必要があります。

ここでは、-Pathは、C:\inetpub\wwwroot の現在の WORKDIR であり、-XdtPath は、Visual Studio の単一の Website プロジェクトのルートです。

Helix ソリューションの例

Docker Examples ソリューションは、単一の Website プロジェクトを用いた簡単な例です。Sitecore Helix のプラクティスに従った実際のソリューションでは、ネストされたフォルダー構造とレイヤーの優先順位 (プロジェクト、機能、Foundationなど) を反映するように、変換コマンドを調整する必要があります。

RUN Get-ChildItem C:\transforms\solution\Foundation\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName }; `
    Get-ChildItem C:\transforms\solution\Feature\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName }; `
    Get-ChildItem C:\transforms\solution\Project\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName };

別の方法: メインのビルド出力で変換ファイルを使用する

変換ファイルは、他のすべてのファイルと一緒にメインのビルド出力に保持できます。このアプローチの欠点は、同じ設定ファイルに対して複数の変換をサポートしないことですが、ソリューション ビルドの Dockerfile とイメージが存在せず、代わりに従来のビルドに依存している場合は、これが唯一のオプションになることがあります。

次に例を示します。

RUN $xdts = [System.Collections.ArrayList]@(); `
    $xdts.AddRange(@(Get-ChildItem -Path .\*.xdt)); `
    $xdts.AddRange(@(Get-ChildItem -Path .\App_Config\*.xdt -Recurse)); `
    $xdts | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path $_.FullName.Replace('.xdt', '') -XdtPath $_.FullName }; `
    $xdts | ForEach-Object { Remove-Item -Path $_.FullName };

Invoke-XdtTransform.ps1 スクリプトは、パラメーターとして一致する設定ファイルと変換ファイルも受け入れます。

この例では、Web ルートと App_Config フォルダー内の .xdt ファイルを探して、Invoke-XdtTransform.ps1 スクリプトを通じて渡し、.xdt ファイルを削除しています。

特定の Sitecore ロールにのみ適用される設定変換を、そのロールの専用フォルダーである docker\build に保存できます。

docker\build フォルダーに追加する

cm サービスの docker\build フォルダーに移動します。このロール用に、transforms フォルダーが追加されていることがわかります。

build
    cm
        transforms
            Web.config.xdt
        Dockerfile

Web.config.xdt 変換が 1 つだけありますが、この変換には、cm ロールに必要なその他の変換を含めることができます。ソリューション変換の場合と同様に、ターゲットのフォルダー構造に合わせて変換ファイルを構成します。

次に、これらの変換をロールの Sitecore ランタイム Dockerfile に適用します。

Sitecore ランタイム イメージに適用する

cm サービスの Sitecore ランタイム Dockerfile では、transforms フォルダーの内容が Docker ビルド コンテキストからコピーされて、\transforms\role\ に配置されていることがわかります。

COPY .\transforms\ \transforms\role\

次に、ソリューションの変換後に、同じ Invoke-XdtTransform.ps1 スクリプトを使って変換を適用します。

RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\role

Docker Examples ソリューションを実行するには:

  1. cd サービスの Sitecore ランタイム Dockerfile (C:\sitecore\docker-examples\custom-images\docker\build\cd\Dockerfile など) を開きます。cd サービスには、ソリューションの変換はありますが、ロールの変換はないことがわかります。

  2. PowerShell プロンプトを開き、custom-images フォルダーに移動します。Docker Compose の up コマンドを使用して Docker Examples を実行します。

    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml up -d

    注記

    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml のコマンドに注目してください。この例では、Sitecore Experience Management (XM1) インスタンスを使用しているため、docker-compose コマンドは、xm1 Compose ファイルを -f フラグで明示的に参照しています。デフォルトの Compose ファイルは XP0 です。

    Sitecore Experience Management (XM1) コンテナーには、次を使用してアクセスできます。

  3. インスタンスが稼働したら、ブラウザーの開発者ツールを使って HTTP ヘッダーを検査することができます。変換の例にある Docker-Examples のカスタム ヘッダーを確認できます。

    cm サイトでは "Role transform" と表示され、cd サイトでは "Solution transform" と表示されます。

実行中のコンテナーに更新を適用するには:

  1. 例の Web.config.xdt ファイルの 1 つを変更します。たとえば、ソリューション変換の valueMy transform に変更します。

  2. 次のコマンドを実行して、実行中のコンテナーに適用された変更を確認します。

    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml up --build -d

    選択を絞り込んで、影響を受けるコンテナーのみを構築することもできます。

    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml build solution cm cd
    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml up -d

    いずれの場合も、up コマンドを呼び出すと、Docker は cmcd のコンテナーだけを再作成します。残りのロールは引き続き実行されます。

  3. 終了したら、down コマンドを使用してコンテナーを停止して削除します。

    docker-compose -f docker-compose.xm1.yml -f docker-compose.xm1.override.yml down

ヒント

設定変換を積極的に開発する場合は、フィードバック ループを短縮するために、https://webconfigtransformationtester.apphb.com/ などの変換テストツールを使用すると便利です。