次の方法で共有

DSC リソース マニフェスト whatIf プロパティ スキーマ リファレンス

  • [アーティクル]

概要

set コマンドがインスタンスを変更するかどうかを指定する方法と方法を定義します。

メタデータ

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

形容

dsc config set コマンドを使用して構成ドキュメントを適用する場合、ユーザーは --what-if オプションを指定して、リソースが実際に行わずにシステム状態を変更するかどうかを確認できます。 このプロパティは、DSC がリソースを呼び出してその情報を直接返す方法を定義します。

このプロパティが定義されていない場合、DSC は、リソースに対するテスト操作の結果をセット結果に変換することで、この動作を合成します。 合成結果は、操作でリソースのプロパティを変更する方法のみを示すことができます。 無効なパラメーターが原因で set 操作が失敗するか、リソースが操作から返す読み取り専用プロパティを示すことはできません。 次の一覧では、合成 what-if の結果がユーザーに十分な情報を返さないケースをいくつか示します。

  • 資格情報パラメーターを必要とするリソースは、インスタンスを正常にテストしても、変更するアクセス許可がない可能性があります。 この場合、ユーザーは dsc config set --what-if 実行し、リソースの明らかに成功した予測を確認できます。 次に、--what-if オプションを指定せずにコマンドを実行すると、ユーザーが調査する必要があるエラーがリソースによって発生します。 失敗したインスタンスの前に他のリソースが正常に適用された場合、システムは部分的に構成された状態のままになる可能性があります。
  • 依存関係サービスを持つリソースは、そのサービスを合成結果から再起動する必要があるかどうかを報告できません。 what-if の結果に基づいて構成の影響を確認した後、ユーザーが誤ってサービスを再起動したり、そのサービスが再起動されるまで構成を部分的に構成したままにしたりする可能性があります。

リソースでパラメーターを使用する場合、または set 操作から読み取り専用プロパティを返す場合は、このメソッドを定義して、リソースが what-if モードでシステム状態を変更するかどうかとその方法に関する最適な情報をユーザーが取得できるようにします。

DSC は、次の 3 つの方法でコマンドにデータを送信します。

  1. input が stdinされると、DSC は、データを圧縮された JSON オブジェクトとして表す文字列としてデータを送信します。オブジェクト のプロパティ間にスペースや改行はありません。
  2. input が envされると、DSC はデータを環境変数として送信します。 プロパティの名前と値を使用して、入力データ オブジェクト内の各プロパティの環境変数を作成します。
  3. args 配列に JSON 入力引数定義が含まれている場合、DSC は、データを圧縮された JSON オブジェクトとして表す文字列として、指定された引数にデータを送信します。

input プロパティを定義せず、JSON 入力引数を定義しない場合、DSC は入力 JSON をリソースに渡すことができません。 1 つのコマンドに対して定義できる JSON 入力引数は 1 つだけです。

input プロパティ、args プロパティ配列内の 1 つの JSON 入力引数、またはその両方を定義する必要があります。

例

例 1 - 完全な定義

"set": {
  "executable": "my_app",
  "args": [
    "config",
    "set",
    "--what-if"
  ],
  "input":            "stdin",
  "return":           "state"
}

my_app.exeではなく、executable を my_appとして定義します。 オペレーティング システムがコマンドを実行可能ファイルとして認識する場合、拡張機能は必要ありません。

マニフェストは、config、set、および --what-ifの 3 つの引数を定義します。 input プロパティの値は、whatIf コマンドが、stdinからの JSON BLOB として入力を受け取っていることを示します。

executableの値と組み合わせて、DSC は次を実行して、このリソースの what-if メソッドを呼び出します。

{ ... } | my_app config set --what-if

マニフェストは、return を stateとして定義し、set メソッドの実行後にのみリソースの予期される最終状態を返すように指定します。 DSC は、目的の状態をこのリソースの戻りデータと比較して、set メソッドが適用するリソースのプロパティ (存在する場合) を識別します。

必須プロパティ

whatIf 定義には、次のプロパティを含める必要があります。

  • 実行可能 を する

プロパティ

実行可能

executable プロパティは、実行するコマンドの名前を定義します。 値は、システムの PATH 環境変数で検出可能なコマンドの名前、またはコマンドの完全なパスである必要があります。 ファイル拡張子は、コマンドがオペレーティング システムによって実行可能ファイルとして認識されない場合にのみ必要です。

Type:     string
Required: true

args

args プロパティは、コマンドに渡す引数の一覧を定義します。 引数には任意の数の文字列を指定できます。 リソースのプロパティ バッグを表す JSON オブジェクトを引数に渡す場合は、配列内の 1 つの項目を JSON オブジェクトとして定義できます。これは、jsonInputArg 文字列プロパティを持つ引数の名前と、mandatory ブール型プロパティを持つコマンドに対して引数が必須かどうかを示します。

Type:     array
Required: false
Default:  []
Type:     [string, object(JSON Input Argument)]

文字列引数

引数配列内の任意の項目には、config や --formatなど、コマンドに渡す静的引数を表す文字列を指定できます。

Type: string

JSON 入力引数

JSON 入力オブジェクトを文字列として受け取るコマンドの引数を定義します。 DSC は、使用可能な場合に名前付き引数に JSON 入力を渡します。 JSON 入力引数は、次のプロパティを持つ JSON オブジェクトとして定義されます。

  • jsonInputArg (必須) - コマンドの JSON データを渡す引数 (--inputなど)。
  • mandatory (省略可能) - コマンドの JSON 入力がない場合でも、DSC が常に引数をコマンドに渡す必要があるかどうかを示します。 その場合、DSC は空の文字列を JSON 入力引数に渡します。

引数配列ごとに定義できる JSON 入力引数は 1 つだけです。

コマンドに対して JSON 入力引数と input の種類を定義すると、DSC は両方の方法で JSON データを送信します。

  • input を env と JSON 入力引数として定義すると、DSC は JSON 入力の各プロパティの環境変数を設定し、JSON 入力オブジェクトを文字列として定義された引数に渡します。
  • stdin と JSON 入力引数として input を定義すると、DSC は stdin を介して、および定義された引数に文字列として JSON 入力を渡します。
  • input プロパティを定義せずに JSON 入力引数を定義した場合、DSC は JSON 入力を文字列として定義された引数にのみ渡します。

input プロパティを定義せず、JSON 入力引数を定義しない場合、DSC は入力 JSON をリソースに渡すことができません。 これにより、マニフェストが無効になります。 input プロパティ、args プロパティ配列の JSON 入力引数、またはその両方を定義する必要があります。

Type:                object
RequiredProperties: [jsonInputArg]

インプット

input プロパティは、リソースに入力を渡す方法を定義します。 このプロパティが定義されておらず、定義でJSON 入力引数が定義されていない場合、DSC は 操作を呼び出すときにリソースに入力を送信しません。

このプロパティの値は、次のいずれかの文字列である必要があります。

  • env - リソースがインスタンスのプロパティを、同じ名前と大文字と小文字の環境変数として指定することを想定していることを示します。

    このオプションでは、インスタンス プロパティに対して次のデータ型のみがサポートされます。

    • boolean
    • integer
    • number
    • string
    • integer 値の array
    • number 値の array
    • string 値の array

    配列以外の値の場合、DSC は環境変数を as-is指定した値に設定します。 データ型が値の配列である場合、DSC は環境変数をコンマ区切りの文字列として設定します。 たとえば、[1, 2, 3] の値を持つプロパティ foo は、foo 環境変数に "1,2,3"として保存されます。

    リソースが object 値または複数型配列を持つ複合プロパティをサポートする必要がある場合は、代わりにこれを stdin に設定します。

  • stdin - stdinからインスタンスを表す JSON BLOB がリソースに必要であることを示します。 JSON は、リソースのインスタンス スキーマに従う必要があります。

Type:        string
Required:    false
ValidValues: [env, stdin]

implementsPretest

implementsPretest プロパティは、目的の状態を適用する前に、インスタンスが内部的に目的の状態であるかどうかをリソースがテストするかどうかを定義します。 リソースが set 操作の一部としてインスタンスをテストするときに、このプロパティを true に設定します。 このプロパティが設定されていない場合は、false します。 ほとんどの場合、この値は、リソース マニフェストで set メソッドの定義の プロパティと同じに設定する必要があります。

この値が falseされると、リソースに対して dsc resource set コマンドを呼び出す前に、ユーザーが常にインスタンスに対して dsc resource test を呼び出す必要があることを示します。

既定値は falseです。

Type:     boolean
Required: false
Default:  false

handlesExist

handlesExist プロパティは、リソースに set 操作の _exist プロパティの組み込み処理があるかどうかを定義します。 既定値は falseです。 ほとんどの場合、この値は、リソース マニフェストで set メソッドの定義の プロパティと同じに設定する必要があります。

このプロパティは、リソースが次の実装要件を満たしている場合に true に設定します。

  • リソースの インスタンス スキーマ では、_exist プロパティが有効なインスタンス プロパティとして定義されます。
  • リソースの set コマンドは、インスタンスの現在の状態と、目的の状態の _exist プロパティの値に基づいて、インスタンスの作成、更新、および削除を処理します。

このプロパティが trueに設定されている場合、リソースは、SetHandlesExist機能を持っていることを示します。 構成で SetHandlesExist 機能を使用してリソースを処理する場合、DSC は、インスタンスが falseとして _exist を定義するときに、リソースの set 操作を呼び出します。 この機能がないと、リソースのインスタンスの削除をサポートするために、リソースで 削除 操作を定義する必要があります。

リソース マニフェストでこのプロパティが true として定義されておらず、delete 操作が定義されていない場合は、_exist が falseに設定されているリソースのインスタンスが検出されると、DSC によってエラーが発生します。

帰る

return プロパティは、DSC がこのメソッドの出力を処理する方法を定義します。 このプロパティの値は、次のいずれかの文字列である必要があります。

  • state - 設定操作の後に、インスタンスの予期される最終状態のみが JSON BLOB として返されることを示します。
  • stateAndDiff - リソースがインスタンスの予期される最終状態と、リソースが変更したプロパティ名の配列を返します。

既定値は stateです。

Type:        string
Required:    false
Default:     state
ValidValues: [state, stateAndDiff]