DSC 構成ドキュメント スキーマ リファレンス

概要

DSC 構成を定義する YAML または JSON ファイル。

メタデータ

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
Type:          object

説明

DSC 構成を使用すると、ユーザーはさまざまな DSC リソースを組み合わせて状態を定義できます。 構成ドキュメントでは、パラメーターと変数を使用して、目的の状態を定義する 1 つ以上のリソースのセットに渡します。

構成ドキュメントは、YAML または JSON として定義できます。 作成を容易にするために、YAML で構成ドキュメントの下書きを行うことをお勧めします。

DSC の作成ツールでファイルを DSC 構成ドキュメントとして認識するには、ファイル名の末尾 .dsc.config.jsonが 、 .dsc.config.yml、または .dsc.config.yamlである必要があります。

構成ドキュメント関数を使用して、実行時にドキュメント内の値を動的に決定できます。 詳細については、「DSC 構成ドキュメント関数リファレンス」を参照してください。

このドキュメントの残りの部分では、DSC が検証構成ドキュメントに使用するスキーマについて説明します。

例

必須プロパティ

すべての構成ドキュメントには、次のプロパティが含まれている必要があります。

• [$schema]
• [リソース]

プロパティ

$schema

プロパティは $schema 、ドキュメントが準拠しているこのスキーマのバージョンの正規 URL を示します。 DSC は、構成操作の前に構成ドキュメントを検証するときに、このプロパティを使用します。

現在、公開されているスキーマのバージョンは 3 つあり、さまざまなバージョンの DSC と互換性があります。

• 2024/04 はスキーマの最新バージョンであり、DSC バージョン 3.0.0-preview.7 以降と互換性があります。
• 2023/10 はスキーマの以前のバージョンであり、DSC バージョン 3.0.0-alpha.4 および と 3.0.0-alpha.5互換性があります。
• 2023/08はスキーマの最初のバージョンであり、 を介して 3.0.0-alpha.3DSC バージョン3.0.0-alpha.1と互換性があります。

このドキュメントは、スキーマの最新バージョンに関するものです。 構成ドキュメントとリソース マニフェストを最新バージョンのスキーマに更新する必要があります。 以前のバージョンは、DSC の新しいリリースでは機能しません。 スキーマは発行されたままですが、更新プログラムは取得されません。

スキーマのすべてのバージョンに対して、次の 3 つの有効な URL があります。

• .../config/document.json

  正規のバンドルされていないスキーマの URL。 検証に使用する場合、検証クライアントは、このスキーマと参照するすべてのスキーマを取得する必要があります。

• .../bundled/config/document.json

  バンドルされたスキーマの URL。 検証に使用する場合、検証クライアントはこのスキーマを取得するだけで済みます。

  このスキーマでは、JSON Schema 2020-12 用に導入されたバンドル モデルを使用します。 DSC では、このスキーマを使用するときにドキュメントを検証できますが、他のツールでエラーが発生したり、予期しない方法で動作したりする場合があります。

• .../bundled/config/document.vscode.json

  拡張オーサリング スキーマの URL。 このスキーマには、他のスキーマに含まれていないコンテキスト ヘルプとスニペットを提供する追加の定義が含まれるため、他のスキーマよりもはるかに大きくなります。

  このスキーマでは、VS Code によってのみ認識されるキーワードが使用されます。 DSC では、このスキーマを使用するときにドキュメントを検証できますが、他のツールでエラーが発生したり、予期しない方法で動作したりする場合があります。

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
             ]

metadata

プロパティは metadata 、キーと値のペアのセットを構成の注釈として定義します。 DSC はメタデータを検証しません。 構成には、このプロパティに任意の情報を含めることができます。

Type:     object
Required: false

parameters

プロパティは parameters 、構成のランタイム オプションのセットを定義します。 各パラメーターは、キーと値のペアとして定義されます。 各ペアのキーは、 パラメーターの名前を定義します。 各ペアの値は、DSC がパラメーターを処理する方法をtype示すキーワード (keyword)を定義するオブジェクトである必要があります。

パラメーターは実行時にオーバーライドされ、異なるコンテキストで同じ構成ドキュメントを再利用できます。

構成でのパラメーターの定義の詳細については、「 DSC 構成のドキュメント パラメーター スキーマ」を参照してください。

Type:                object
Required:            false
ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json

variables

プロパティは variables 、ドキュメント内のリソースの再利用可能な値のセットをキーと値のペアとして定義します。 各ペアのキーは、変数の名前を定義します。 名前で変数を参照するリソースは、変数の値にアクセスできます。

これにより、構成内のリソースのコピーされた値とオプションの量を減らすことができます。これにより、ドキュメントの読み取りと保守が容易になります。 パラメーターとは異なり、変数は構成でのみ定義でき、実行時にオーバーライドすることはできません。

Type:     object
Required: false

resources

プロパティは resources 、構成が管理する DSC リソース インスタンスの一覧を定義します。 リスト内のすべてのインスタンスは一意である必要がありますが、インスタンスは同じ DSC リソースの種類を共有できます。

構成で有効なリソース インスタンスを定義する方法の詳細については、「 DSC 構成ドキュメント リソース スキーマ」を参照してください。

Type:             array
Required:         true
MinimumItemCount: 1
ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json