DSC 资源清单 whatIf 属性架构参考

概要

定义如何指示 set 命令是否会修改实例以及如何修改实例。

元数据

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

描述

使用 dsc config set 命令强制执行配置文档时，用户可以指定 --what-if 选项来查看资源是否以及如何更改系统状态，而无需实际执行此作。 此属性定义 DSC 如何调用资源以直接返回该信息。

如果未定义此属性，DSC 通过将针对资源的测试操作的结果转换为集结果来合成此行为。 综合结果只能指示操作将如何更改资源属性。 它无法指示作是否 set 会因参数无效而失败，或者资源将从作返回哪些只读属性。 以下列表描述了合成模拟结果不会向用户返回足够信息的情况：

• 需要凭据参数的资源可能会成功测试实例，但无权对其进行修改。 在这种情况下，用户可能会运行 dsc config set --what-if 并看到对资源的明显成功的预测。 然后，当他们在没有选项 --what-if 的情况下运行命令时，资源会引发用户必须调查的错误。 如果在失败的实例之前成功应用了任何其他资源，系统可能处于部分配置状态。
• 具有依赖项服务的资源无法报告是否需要从综合结果重启该服务。 根据假设结果查看配置的影响后，用户可能会无意中重启服务或使配置处于部分配置状态，直到重新启动该服务。

如果您的资源使用参数或从作返回只读属性 set ，请定义此方法以确保您的用户获得有关资源是否以及如何在 what-if 模式下修改系统状态的最佳信息。

DSC 以三种方式将数据发送到命令：

1. When input is ， stdinDSC 将数据作为字符串发送，该字符串将数据表示为压缩的 JSON 对象，对象属性之间没有空格或换行符。
2. 当 input 为 时 env，DSC 会将数据作为环境变量发送。 它使用属性的名称和值为输入数据对象中的每个属性创建环境变量。
3. args当数组包含 JSON 输入参数定义时，DSC 会将数据作为字符串发送，该字符串表示数据为压缩的 JSON 对象到指定的参数。

如果未定义 input 属性且未定义 JSON 输入参数，则 DSC 无法将输入 JSON 传递给资源。 只能为命令定义一个 JSON 输入参数。

您必须定义 property、property 数组中的input一个 JSON 输入参数，或同时定义args两者。

例子

示例 1 - 完整定义

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

它将 定义为 executablemy_app，而不是 my_app.exe。 当操作系统将命令识别为可执行文件时，不需要扩展。

清单定义了三个参数 config、 、 set和 --what-if。 该 input 属性的值指示 whatIf 命令需要将其输入作为 JSON blob from stdin.

结合 的值 executable，DSC 通过运行以下命令来调用此资源的 what-if 方法：

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

清单定义为 returnstate，表示它仅在方法运行后 set 返回资源的预期最终状态。 DSC 将所需状态与此资源的返回数据进行比较，以确定该方法将强制执行哪些资源属性 set （如果有）。

必需属性

定义 whatIf 必须包括以下属性：

• executable

属性

可执行

该 executable 属性定义要运行的命令的名称。 该值必须是可在系统 PATH 环境变量中发现的命令的名称或命令的完整路径。 仅当操作系统无法将命令识别为可执行文件时，才需要文件扩展名。

Type:     string
Required: true

参数

该 args 属性定义要传递给命令的参数列表。 参数可以是任意数量的字符串。 如果要将表示资源属性包的 JSON 对象传递给参数，则可以将数组中的单个项目定义为 JSON 对象，指示具有 jsonInputArg string 属性的参数的名称，以及该参数对于具有 mandatory boolean 属性的命令是否是必需的。

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 （可选）- 指示 DSC 是否应始终将参数传递给命令，即使命令没有 JSON 输入。 在这种情况下，DSC 会将空字符串传递给 JSON 输入参数。

每个参数数组只能定义一个 JSON 输入参数。

如果您为命令定义了 JSON 输入参数和 input 类型，DSC 将双向发送 JSON 数据：

• 如果您定义 input as env 和 JSON 输入参数，DSC 会为 JSON 输入中的每个属性设置一个环境变量，并将 JSON 输入对象作为字符串传递给定义的参数。
• 如果您定义 input as stdin 和 JSON 输入参数，DSC 将通过 stdin 将 JSON 输入作为字符串传递给定义的参数。
• 如果您定义了 JSON 输入参数而 input 未定义属性，则 DSC 仅将 JSON 输入作为字符串传递给定义的参数。

如果未定义 input 属性且未定义 JSON 输入参数，则 DSC 无法将输入 JSON 传递给资源。 这使得清单无效。 您必须定义 input 属性和/或 property 数组中的 args JSON 输入参数。

Type:                object
RequiredProperties: [jsonInputArg]

输入

该 input 属性定义如何将输入传递给资源。 如果未定义此属性，并且定义未定义 JSON 输入参数，则 DSC 在调用 whatIf 作时不会向资源发送任何输入。

此属性的值必须是下列字符串之一：

• env - 指示资源希望将实例的属性指定为具有相同名称和大小写的环境变量。

  此选项仅支持实例属性的以下数据类型：

  • boolean
  • integer
  • number
  • string
  • array 的 integer 价值观
  • array 的 number 价值观
  • array 的 string 价值观

  对于非数组值，DSC 会将环境变量设置为指定的值 as-is。 当数据类型是值的数组时，DSC 会将环境变量设置为逗号分隔的字符串。 例如， foo 值为 的属性 [1, 2, 3] 在环境变量中 foo 保存为 "1,2,3"。

  如果资源需要支持具有 object 值或多类型数组的复杂属性，请改为将此项设置为 stdin 。

• stdin - 指示资源需要一个 JSON blob，该 blob 表示来自 stdin的实例。 JSON 必须遵循资源的实例架构。

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

实施预测试

该 implementsPretest 属性定义资源是否在强制执行 desired state 之前在内部测试实例是否处于 desired 状态。 将此属性设置为 true 当资源在作过程中 set 测试实例时。 将此属性设置为 false 不这样做时。 在大多数情况下，此值的设置应与 implementsPretest 资源清单中 set 方法 的定义中的属性相同。

当此值为 false时，表示用户应始终在对资源调用dsc resource test命令之前对实例进行调用dsc resource set。

默认值是 false。

Type:     boolean
Required: false
Default:  false

handles存在

该handlesExist属性定义资源是否具有对作中 set 属性的内置处理。 默认值是 false。 在大多数情况下，此值的设置应与 implementsPretest 资源清单中 set 方法 的定义中的属性相同。

将此属性设置为 true 资源满足以下实现要求时：

• 资源的 实例架构 将属性 _exist 定义为有效的实例属性。
• 该资源的 set 命令根据实例的当前状态和处于所需状态的属性 _exist 值处理实例的创建、更新和删除。

当此属性设置为 true时，资源指示它具有 SetHandlesExist功能。 在处理配置中具有 SetHandlesExist capability 的资源时，DSC 会在实例定义为 set_exist时调用false资源的作。 如果没有此功能，资源必须定义 delete 作以支持删除资源的实例。

如果资源清单未将此属性true定义为且未定义delete作，则 DSC 在遇到设置为 _exist的资源false实例时会引发错误。

返回

该 return 属性定义 DSC 应如何处理此方法的输出。 此属性的值必须是下列字符串之一：

• state - 指示资源在设置作后仅以 JSON blob 形式返回实例的预期最终状态。
• stateAndDiff - 指示资源返回实例的预期最终状态和资源修改的属性名称数组。

默认值是 state。

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