カスタムSitecore画像の作成

配置変換の適用

Version:

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

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

このトピックでは、Sitecore Docker画像を作成する際にXDTベースの構成変換をどのように適用するかを示します。変換ファイルはソリューション内にある場合もあれば、特定のSitecoreロールのローカルDockerfileに存在する場合もあります。この例ではSitecore Experience Management (XM1) インスタンスを使用しています。

Docker Examplesリポジトリをクローンする

まだやっていなければ、Docker Exampleリポジトリをマシン上のC:\sitecore\docker-examples\のような場所にクローンしてください(例ではこのフォルダが使われています)。例ではcustom-imagesフォルダを使います。

例の準備

カスタム画像の例は実行前にある程度の準備が必要です。まだ準備をしていなければ、準備手順に従うか、付属のinit.ps1スクリプトを実行して自動的に準備手順を実行してください。

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

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

Docker Examples transform files

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

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

この変換ファイルは解の中にあるため、すべての コアSitecore役割(XM1トポロジーにおけるCMおよびCD)に適用されます。これは解変換の例です。ここでDocker-Examples HTTPヘッダーが追加され、Solution transformに設定されます:
\docker\build\cm\transforms\Web.config.xdt

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

!ヒント複数の変換を適用する際には、操作順序を考慮するのがベストプラクティスです。しかし、変換は毎回新しい設定ファイルに適用されるため、冪等性を必ずしも確保する必要はありません。

この例ではまず解変換を適用し、その後に役割変換を行います。

解変換

すべてのコア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 ActionがContentに設定されている場合)、最終的には1つだけが出力に入り、最終的に適用されます。代わりに、これらのファイルはNoneに設定されているBuild Actionを除外し、それぞれがソリューションビルドイメージに個別に収集されます。

変換ファイルをメインのビルド出力に残し、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のランタイムイメージに適用

ランタイム画像に変換を適用するには:

CMサービスのSitecoreランタイムDockerfileを開きます。\transforms\solution\に格納された解変換がコピーされたのが見えます:

COPY --from=solution \artifacts\transforms\ \transforms\solution\
開発ツールは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例の解決策は、単一のWebsiteプロジェクトを持つシンプルな例です。 Sitecore Helixの実践に従う実際の解決策では、変換コマンドをネストされたフォルダ構造やレイヤーの優先度(プロジェクト 、フィーチャー、基礎など)に合わせて調整する必要があります。

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スクリプトは、設定ファイルや変換ファイルをパラメータとして一致させることも受け入れます。

この例では、ウェブのルートファイルと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変換がありますが、この変換には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

Run Docker Examples solution

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

cdサービスのSitecoreランタイムDockerfileを開きます(例:C:\sitecore\docker-examples\custom-images\docker\build\cd\Dockerfile)。cdサービスには解変換はありますが、役割変換は含まれていません。
PowerShellプロンプトを開き、custom-imagesフォルダに移動します。Docker Compose upコマンドでDocker例を実行します:

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ファイルはXP**0です。

以下のSitecore Experience Management (XM1) コンテナにアクセスできます:
- Sitecore Content Management(cm): https://cm.dockerexamples.localhost
- Sitecore Content Delivery(CD): https://cd.dockerexamples.localhost
インスタンスが稼働したら、ブラウザの開発者ツールを使ってHTTPヘッダーを確認できます。変換例にあるDocker-Examplesカスタムヘッダーを確認できます。

cmサイトはRole transformを表示しますが、cdサイトはSolution transformを表示します。

実行中のコンテナにアップデートを適用する

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

例Web.config.xdtファイルのいずれかに変更します。例えば、解変換valueをMy transformに変更します。
以下のコマンドを実行して、実行中のコンテナに適用された変更を確認します:

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はcmコンテナとcdコンテナのみを再作成します。その他の役割は引き続き実行されます。
終わったら、downコマンドを使って容器を停止し、取り外してください。

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

!ヒント構成変換を積極的に開発している場合、https://webconfigtransformationtester.apphb.com/ のような変換テストツールを使ってフィードバックループを短縮すると役立ちます。

さらなる参考文献

この記事を改善するための提案がある場合は、お知らせください!