<capture> 要素は、当該スナップショットの一部としてキャプチャされるファイルとリソースを定義します。キャプチャは、<prepare> ブロック内のステップが実行されたあとでしか行われません。キャプチャが完了すると、<cleanup> ブロック内のステップが実行されます。
<capture> 要素の子は、1 つ以上の <addFile>、<addSnapshot>、および <addResource> 要素から構成されます。このブロックに挙げられるファイルとディレクトリは、指定された順にキャプチャされます。包含される子は、スナップショットブロックで宣言されたローカルパラメータおよびローカル変数と、隠蔽されていない component 置換変数を参照できます。
<addFile> 要素は <capture> 要素の子であり、包含するスナップショットの一部としてキャプチャされるファイルを指定します。
path – 必須属性で、ターゲットホストのファイルシステム上のファイルまたはディレクトリのパス名を指定します。この属性は、単純置換変数を参照できます。
ownership – オプション属性で、キャプチャされたファイルの所有権オプションを指定します。
スナップショットによってキャプチャされるインストール状態の情報の 1 つに、ファイルおよびディレクトリの所有権があります。この所有権は UNIX のアクセス許可と同じではありません。所有権は、参照カウントの概念により近いと言えます。具体的には、ファイルまたはディレクトリは、1 つ以上のスナップショットによって所有されているものとしてキャプチャできます。
ほかのコンポーネントのインストールにより、ファイルの所有者が変更された場合、そのファイルがその初期状態と比較されたときに、この変更が認識され報告されます。この機能により、あるコンポーネントが、別のコンポーネントに関連付けられているファイルを誤って上書きしたために生じた差異を追跡することができます。スナップショットの所有権情報は、所有者テーブルと呼ばれる、ターゲットホスト上のリポジトリ内にキャプチャされます。
ownership 属性の値は以下のセマンティクスを持ちます。
SET_SELF – ownership 値がこの値に設定された場合、所有者テーブルは関連付けられたファイルまたはディレクトリ用の単一のエントリを含むように更新されます。そのエントリは、実行するインストール済みコンポーネントとスナップショットを所有者としてリストします。また、キャプチャされたファイルコンテンツまたはディレクトリコンテンツのキャプチャ領域 ID もリストします。
ADD_SELF – ownership がこの値に設定された場合、インストール済みコンポーネントとスナップショットを付加的な所有者として追加し、以前の所有者として既存のキャプチャ領域 ID を共有させる必要があります。
ADD_TEMP – この値は ADD_SELF と似ていますが、新しいキャプチャが常に作成されてその ID が常に新しいエントリに使用されます (ほかの所有者の ID を共有することはありません)。
この属性を指定しない場合、デフォルト値は SET_SELF です。
filter – boolean 型のオプション属性で、ファイルまたはディレクトリ、あるいはそれらの両方をキャプチャすべきかを示します。
path の値がディレクトリである場合、この属性は、ディレクトリ自体、そのディレクトリに含まれるファイル、またはそれらの両方のどれをキャプチャすべきかを示すために使用されます。path の値がディレクトリでない場合、この属性は無視され、ファイルが直接キャプチャされます。この属性を指定しない場合、デフォルトの BOTH が使用されます。
この属性の値には次のものがあります。
DIRECTORIES
FILES
BOTH
recursive – オプション属性で、現在のフィルタ設定を使用してサブディレクトリを再帰的にキャプチャすべきかどうかを示します。
path の値がディレクトリである場合、この属性は、現在のフィルタ設定を使用してサブディレクトリを再帰的にキャプチャすべきかどうかを示します。path の値がディレクトリでない場合、この属性は無視され、ファイルが直接キャプチャされます。デフォルト値は true です。
displayName – オプション属性で、当該スナップショットエントリがほかのエントリと比較される際に表示に含めるテキスト。
この属性は、単純置換変数を参照できます。
<addSnapshot> 要素は、外部スナップショットブロックを実行する必要があること、およびそのコンテンツを当該スナップショットに追加すべきであることを示します。
<addSnapshot> ステップを使用することは、次のシナリオのすべてと意味的に同じです。
呼び出されたスナップショットの <prepare> ステップを、呼び出し側スナップショットの prepare ブロックの最後に追加する
呼び出されたスナップショットの <cleanup> ステップを、呼び出し側スナップショットの cleanup ブロックの先頭に追加する
呼び出されたスナップショットの <capture> ステップを、(<addSnapshot> ステップの代わりに) 呼び出し側スナップショットの capture ブロックに追加する
呼び出される側および呼び出し側のスナップショットブロックによって参照されるファイルが重複しないように注意する必要があります。
<capture> 要素には任意の数の <addSnapshot> ステップを指定できます。呼び出される側のスナップショットは、その <capture> 要素に任意の数の <addSnapshot> ステップを含むことができます。
<addSnapshot> コールアウトを使用してファイルをスナップショットに間接的に追加する場合、スナップショットのキャプチャを開始した最上位のコンポーネントは (<addFile> 命令が入ったコンポーネントとは対照的に) ファイルの所有者と見なされます。同様に、スナップショットに対して比較が実行される場合は、スナップショットを開始した最上位コンポーネントの <diff> 要素の <ignore> 命令だけが考慮されます。<addSnapshot> コールアウトの結果として出現したコンポーネントに含まれる <diff> 要素の <ignore> 命令は考慮されません。
<addSnapshot> 要素には、entityName 型の 1 つの必須要素 blockName があります。これは、実行する外部スナップショットブロックの名前です。
<addSnapshot> ステップには次の子要素があります。
<argList> – オプション要素で、スナップショットブロックに渡す引数の一覧。この要素は 1 回しか出現できません。
Installed component targeter – オプション要素で、スナップショットブロックを含むコンポーネントを特定します。この要素を指定しない場合は、<thisComponent> が使用されます。
<addResource> 要素は、包含するスナップショットの一部としてキャプチャされるコンポーネントに関連付けられたリソースを指定します。この要素は、単純コンポーネントにしか含めることができません。
この要素は、次に示すように、同等の <addFile> 要素の簡略構文として機能します。
関連付けられたリソースが deployMode =ADD_TO のディレクトリリソースである場合、<addResource> は次の文と同義です。
<addFile path="path-of-deployed-directory" filter="FILES" displayName="resourceSourcePath"/> |
関連付けられたリソースが deployMode =REPLACE のディレクトリリソースである場合、<addResource> は次の文と同義です。
<addFile path="path-of-deployed-directory" displayName="resourceSourcePath"/> |
これらのどちらでもない場合、関連付けられたリソースはファイルベースのリソースであり、<addResource> は次の文と同義です。
<addFile path="path-of-deployed-file" displayName="resourceSourcePath"/> |