コマンド ベースの DSC リソースの構造
DSC リソースは、システムの設定を管理するための標準化されたインターフェイスを提供します。 リソースは、管理できるプロパティを定義し、リソースのインスタンスを取得するために必要なコードを実装します。
コマンド ベースの DSC リソースは、少なくとも 2 つのファイルで定義されます。
- DSC リソースと対話する方法を DSC に指示する DSC リソース マニフェスト。
- リソースのインスタンスを管理するための 1 つ以上の実行可能ファイルとその依存関係。
DSC リソース マニフェスト
DSC リソース マニフェストは JSON ファイルとして定義されます。 DSC が JSON ファイルをマニフェストとして認識するには、ファイルが次の条件を満たしている必要があります。
- ファイルは環境変数で
PATH検出可能である必要があります。 - ファイル名は で終わる
.dsc.resource.json必要があります。
DSC は、ローカル システムで使用可能なコマンド ベースの DSC リソースを検索すると、 内のすべてのフォルダーで PATH 、DSC リソース マニフェストの名前付け規則を使用するファイルを検索します。 DSC は、検出された各ファイルを解析し、 DSC リソース マニフェスト JSON スキーマに対して検証します。
JSON ファイルがスキーマに対して検証される場合、DSC は DSC リソースを使用できます。
マニフェストでは、少なくとも次を定義する必要があります。
- 互換性のある DSC リソース マニフェスト JSON スキーマのバージョン。
- リソースの完全修飾名 (例:
Microsoft.Windows/Registry)。 完全修飾名の構文は です<owner>[.<group>][.<area>]/<name>。 完全修飾名のグループコンポーネントとエリアコンポーネントを使用すると、リソースを名前空間に編成できます。 - DSC がコマンドを呼び出してリソース インスタンスの現在の状態を取得する方法。
- インスタンスを検証する方法。 DLL は、次のいずれかの場所に置くことができます。
- インスタンスを記述する JSON スキーマ
- コマンド DSC は、実行時にスキーマを取得するために を呼び出す必要があります
- 入れ子になった DSC リソースを検証するコマンド。 この最後のオプションは、DSC グループ リソースと DSC プロバイダー リソースにのみ適用されます。
マニフェストでは、必要に応じて次を定義できます。
- DSC でコマンドを呼び出して、インスタンスが目的の状態であるかどうかをテストする方法。
- DSC がコマンドを呼び出してインスタンスを目的の状態に設定する方法。
- コマンドによって返される 0 以外の終了コードの意味。
- リソースが DSC グループ リソースまたは DSC プロバイダー リソースである場合に、DSC でコマンドを呼び出して他の DSC リソースを管理する方法。
- 作成者や簡単な説明など、リソースに関するメタデータ。
マニフェストでリソースのインスタンスをテストする方法が定義されていない場合、DSC はリソース インスタンスの合成テストを実行します。 DSC の合成テストは常にインスタンスの実際の状態を取得し、インスタンスのプロパティと目的の状態を厳密に比較します。 合成テストでは、アンダースコア () またはドル記号$ (_) が付いたプロパティはすべて無視されます。 いずれかのプロパティが定義された目的の状態とまったく同じでない場合、DSC はインスタンスを非準拠として報告します。
マニフェストで DSC リソースのインスタンスを設定する方法が定義されていない場合、DSC はリソースを使用して目的の状態を適用できません。
マニフェストでは、すべての操作に同じ実行可能ファイルを指定する必要はありません。 各操作の定義は独立しています。
DSC リソース実行可能ファイル
コマンド ベースの DSC リソースでは、DSC を実行するための実行可能ファイルが常に必要です。 DSC リソース マニフェストを実行可能ファイルにバンドルする必要はありません。 実行可能ファイルには、バイナリ アプリケーションやシェル スクリプトなどの任意の実行可能ファイルを指定できます。 リソースでは、操作ごとに異なる実行可能ファイルを使用できます。
DSC で実行可能ファイルを使用するには、環境変数で PATH 検出可能である必要があります。 DSC は、実行可能ファイルから返された終了コードを使用して、コマンドが成功したかどうかを判断して、操作ごとに 1 回実行可能ファイルを呼び出します。 DSC は終了コード 0 を成功として扱い、その他すべての終了コードをエラーとして扱います。
入力
DSC は、コマンド ベースの DSC リソースに、stdin 経由の JSON データ BLOB として、または引数フラグと値のセットとして入力を送信します。 入力処理は、DSC リソース マニフェストで操作ごとに定義されます。
DSC が入力を stdin 経由で JSON として送信する場合、データ BLOB はインスタンスの目的の状態の JSON 表現です。 これは、リソースが入れ子になったオブジェクトを持つ複雑なプロパティをサポートできるため、リソースにとって最も堅牢なオプションです。
DSC は、入力を引数として送信すると、指定されたプロパティごとに引数のペアを生成します。 最初の引数は、 などの --durationプレフィックスが付いた--プロパティの名前です。 2 番目の引数は、プロパティの値です。 引数ペアの順序は保証されません。 この入力メソッドは、複雑なプロパティをサポートしていません。
出力
コマンド ベースの DSC リソースの実行可能ファイルは、DSC によって呼び出されたときに JSON データを stdout に返す必要があります。 出力エンコードは UTF-8 である必要があります。 リソースがインスタンスの状態を返すと、DSC はリソースのインスタンス スキーマに対して JSON データを検証します。
DSC プロバイダー リソースの場合、DSC では、実行可能ファイルが管理するリソースのインスタンス状態を、単一の JSON 配列または一連の JSON Lines として渡すことが想定されています。
コマンド ベースの DSC リソースでは、STDerr に JSON 行を出力することで、ログ情報を DSC に報告できます。 各ログ エントリは、次の 2 つのキーを含む JSON オブジェクトである必要があります。
- キーは
message、ログ エントリの人間が判読できる文字列を定義します。 - キーは
level、メッセージが 、、またはInformationを表ErrorWarningすかどうかを定義します。
DSC はリソースからメッセージを収集し、構成操作の結果に表示します。 DSC が構成の外部でリソースを直接呼び出しても、メッセージは収集されません。 代わりに、stderr に出力されるだけです。
