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

Synopsis

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

Metadata

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

Description

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

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

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

必須プロパティ

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

プロパティ

$schema

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

DSC の JSON スキーマは、複数のバージョンと形式で公開されています。 このドキュメントは、最新バージョンのスキーマ用です。 便宜上、GitHub でホストされているスキーマの完全な URI を指定するか、短い aka.ms URI を使用できます。 特定のセマンティック バージョンのスキーマ、マイナー バージョンの最新のスキーマ、または DSC のメジャー バージョンの最新のスキーマを指定できます。 スキーマ URI とバージョン管理の詳細については、「 DSC JSON スキーマ URI」を参照してください。

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

  • .../resource/manifest.json

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

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

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

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

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

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

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

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.2/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.json
             ]

型

type プロパティは、リソースの完全修飾型名を表します。 これは、構成ドキュメントでリソースを指定するため、および--resourceコマンドを使用するときにdsc 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

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

Type:     string
Required: false

kind

kind プロパティは、DSC がリソースを処理する方法を定義します。 DSC は、 resource、 group、 adapter、 importer、 exporter のいくつかの種類の DSC リソースをサポートしています。

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

グループ リソースを定義するときは、マニフェストで kind プロパティを group として常に明示的に定義します。 インポーターリソースを定義するときは、マニフェストで常に kind プロパティを importer として明示的に定義します。

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

Type:        string
Required:    false
ValidValues: [resource, adapter, group, importer, exporter]

tags

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

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

エクスポート

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

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

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

Type:     object
Required: true

バージョン変更

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

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

Type:     object
Required: true

set

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" の 16 進数値 0x80070005 代わりに、終了コードを -2147024891 として指定します。
  • 値は、人間のリーダーの終了コードのセマンティックな意味を記述する文字列です。

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

Tip

リソース マニフェストを 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
  • Last updated on