次の方法で共有

コマンド ベースの DSC リソース マニフェスト スキーマ リファレンス

  • [アーティクル]

概要

コマンド ベースの DSC リソースを定義するデータ ファイル。

メタデータ

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

形容

すべてのコマンド ベースの DSC リソースにはマニフェストが必要です。 マニフェスト ファイルは次の必要があります。

  1. PATH 環境変数で検出できます。
  2. JSON または YAML として書式設定されます。
  3. 名前付け規則の <name>.dsc.resource.<extension>に従ってください。 有効な拡張機能には、json、yml、および yamlが含まれます。
  4. このドキュメントで説明されているスキーマに対して有効です。

このドキュメントの残りの部分では、マニフェストのスキーマについて説明します。

必須プロパティ

マニフェストには、次のプロパティを含める必要があります。

プロパティ

$schema

$schema プロパティは、マニフェストが検証するこのスキーマの正規 URI を示します。 このプロパティは必須です。 DSC では、この値を使用して、正しい JSON スキーマに対してマニフェストを検証します。

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

  • .../resource/manifest.json

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

  • .../bundled/resource/manifest.json

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

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

  • .../bundled/resource/manifest.vscode.json

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

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

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

種類

type プロパティは、リソースの完全修飾型名を表します。 dsc resource * コマンドを使用する場合は、構成ドキュメントでリソースを指定し、--resource フラグの値として指定するために使用されます。 リソースの種類名の詳細については、「DSC リソースの完全修飾型名スキーマ リファレンスを参照してください。

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

バージョン

version プロパティは、有効なセマンティック バージョン (semver) 文字列としてのリソースの現在のバージョンである必要があります。 バージョンは、管理するソフトウェアではなく、リソースに適用されます。

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

形容

description プロパティは、リソースの目的の概要を定義します。 このプロパティの値は短い文字列である必要があります。

Type:     string
Required: false

種類

kind プロパティは、DSC によるリソースの処理方法を定義します。 DSC では、Resource、Group、および Adapterの 3 種類のコマンド ベースの DSC リソースがサポートされています。

リソース マニフェストで kind が定義されていない場合、DSC はプロパティの値を推論します。 adapter プロパティがリソース マニフェストで定義されている場合、DSC は kind の値を Adapterと見なします。 adapter プロパティが定義されていない場合、DSC は kind の値を Resourceとして推論します。 DSC は、マニフェストがグループ リソース用であるかどうかを推測できません。

グループ リソースを定義する場合は、マニフェストの kind プロパティを必ず明示的に Groupとして定義します。

詳細については、「DSC リソースの種類スキーマ リファレンスを参照してください。

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

タグ

tags プロパティは、リソースの検索可能な用語の一覧を定義します。 このプロパティの値は、文字列の配列である必要があります。 各タグには、英数字とアンダースコアのみを含める必要があります。 他の文字は使用できません。 各タグは一意である必要があります。

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

輸出

export プロパティは、リソースを呼び出してすべてのインスタンスの現在の状態を取得する方法を定義します。 このプロパティを定義すると、ユーザーは次のことができます。

  • dsc config export コマンドの入力構成でリソースのインスタンスを指定して、使用可能な構成ドキュメントを生成します。
  • dsc リソース エクスポート コマンドを使用してリソースを指定し、リソースのすべてのインスタンスを定義する構成ドキュメントを生成します。
  • dsc リソース get コマンドと --all オプションを使用してリソースを指定し、リソースのすべてのインスタンスの現在の状態を返します。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義するオブジェクトの executable プロパティは必須です。 args プロパティは省略可能です。 詳細については、「DSC リソース マニフェスト のエクスポート プロパティ スキーマ リファレンス」を参照してください。

Type:     object
Required: true

取得

get プロパティは、リソースを呼び出してインスタンスの現在の状態を取得する方法を定義します。 このプロパティは、すべてのリソースに必須です。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義するオブジェクトの executable プロパティは必須です。 args プロパティと input プロパティは省略可能です。 詳細については、「DSC リソース マニフェスト get property schema reference」を参照してください。

Type:     object
Required: true

セット

set プロパティは、リソースを呼び出してインスタンスの目的の状態を設定する方法を定義します。 また、このメソッドのリソースからの出力を処理する方法も定義します。 このプロパティが定義されていない場合、DSC はリソースのインスタンスを管理できません。 現在の状態のみを取得し、インスタンスが目的の状態であるかどうかをテストできます。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義する executable プロパティは必須です。 args input、implementsPretest、および returns プロパティは省略可能です。 詳細については、「DSC リソース マニフェスト セットのプロパティ スキーマリファレンスを参照してください。

Type:     object
Required: false

whatIf

DSC リソースを呼び出して、set コマンドがインスタンスを変更するかどうか、および DSC リソースからの出力を処理する方法を示す方法を定義します。 リソースがマニフェストでこのメソッドを定義していない場合、DSC はリソースのテスト操作の結果をセット結果に変換することで、この動作を合成します。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義する executable プロパティは必須です。 args input、implementsPretest、および returns プロパティは省略可能です。 詳細については、「DSC リソース マニフェスト whatIf プロパティ スキーマ リファレンス」を参照してください。

試験

test プロパティは、リソースを呼び出して、インスタンスが目的の状態であるかどうかをテストする方法を定義します。 また、このメソッドのリソースからの出力を処理する方法も定義します。 このプロパティが定義されていない場合、DSC は DSC リソースのインスタンスに対して基本的な合成テストを実行します。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義するオブジェクトの executable プロパティは必須です。 args input、および returns プロパティは省略可能です。 詳細については、「DSC リソース マニフェストのテスト プロパティ スキーマリファレンスを参照してください。

Type:     object
Required: false

検証

validate プロパティは、DSC グループ リソースを呼び出してインスタンスを検証する方法を定義します。 DSC グループ リソースでは、このプロパティが必須です。 DSC は、他のすべてのリソースに対してこのプロパティを無視します。

このプロパティの値はオブジェクトである必要があります。 呼び出すコマンドの名前を定義するオブジェクトの executable プロパティは必須です。 args プロパティは省略可能です。 詳細については、「DSC リソース マニフェスト検証プロパティ スキーマ リファレンス」を参照してください。

Type:     object
Required: false

供給者

provider プロパティを指定すると、リソースが DSC リソース プロバイダーとして定義されます。

このプロパティの値はオブジェクトである必要があります。 オブジェクトの list プロパティと config プロパティは必須です。 list プロパティは、プロバイダーを呼び出して、プロバイダーが管理できるリソースを返す方法を定義します。 config プロパティは、プロバイダーが入力を期待する方法を定義します。 詳細については、「DSC リソース マニフェスト プロバイダーのプロパティ スキーマリファレンスを参照してください。

exitCodes

exitCodes プロパティは、リソースの有効な終了コードとその意味のセットを定義します。 このプロパティは、次のようなキーと値のペアのセットとして定義します。

  • キーは、リソースの既知の終了コードにマップされる符号付き整数を含む文字列です。 終了コードはリテラル符号付き整数である必要があります。 終了コードに代替形式を使用することはできません。 たとえば、"Access denied" 0x80070005 の 16 進数の値の代わりに、終了コードを -2147024891として指定します。
  • 値は、人間のリーダーの終了コードのセマンティックな意味を記述する文字列です。

DSC は、終了コード 0 を正常な操作として解釈し、その他の終了コードをエラーとして解釈します。

先端

リソース マニフェストを yaml で作成する場合は、終了コードを一重引用符で囲んで、YAML ファイルを正しく解析できることを確認してください。 例えば：

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

スキーマ

schema プロパティは、リソースのインスタンスを検証する JSON スキーマを取得する方法を定義します。 このプロパティは、常に次のいずれかのプロパティを定義するオブジェクトである必要があります。

  • command - command プロパティを指定すると、DSC は定義されたコマンドを呼び出して JSON スキーマを取得します。
  • embedded - embedded プロパティを指定すると、DSC は定義された値を JSON スキーマとして使用します。

詳細については、「DSC リソース マニフェスト スキーマ のプロパティ リファレンス」を参照してください。

Type:     object
Required: true