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

2024-06-25

概要

定义如何指示 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 配置集命令强制实施配置文档时，用户可以指定 --what-if 选项，以查看资源是否会更改系统状态，而无需实际执行此操作。此属性定义 DSC 如何调用资源以直接返回该信息。

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

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

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

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

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

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

必须定义 input 属性、args 属性数组中的一个 JSON 输入参数，或同时定义这两个属性。

例子

示例 1 - 完整定义

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

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

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

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

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

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

必需属性

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

可执行文件

性能

可执行

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

Type:     string
Required: true

args

args 属性定义要传递给命令的参数列表。参数可以是任意数量的字符串。如果要将表示资源属性包的 JSON 对象传递给参数，则可以将数组中的单个项定义为 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 （可选） - 指示 DSC 是否应始终将参数传递给命令，即使命令没有 JSON 输入也是如此。在这种情况下，DSC 会将空字符串传递给 JSON 输入参数。

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

如果为命令定义 JSON 输入参数和 input 类型，DSC 会以两种方式发送 JSON 数据：

如果将 input 定义为 env 和 JSON 输入参数，DSC 将为 JSON 输入中的每个属性设置环境变量，并将 JSON 输入对象作为字符串传递给定义的参数。
如果将 input 定义为 stdin 和 JSON 输入参数，DSC 会将 JSON 输入传递到 stdin，并将字符串传递给定义的参数。
如果在未定义 input 属性的情况下定义 JSON 输入参数，DSC 仅将 JSON 输入作为字符串传递给定义的参数。

如果未定义 input 属性且未定义 JSON 输入参数，DSC 无法将输入 JSON 传递给资源。这使得清单无效。必须定义 input 属性、args 属性数组中的 JSON 输入参数，或同时定义这两个属性。

Type:                object
RequiredProperties: [jsonInputArg]

输入

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

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

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

此选项仅支持实例属性的以下数据类型：
- boolean
- integer
- number
- string
- integer 值的 array
- number 值的 array
- string 值的 array
对于非数组值，DSC 会将环境变量设置为指定的值 as-is。当数据类型是值的数组时，DSC 会将环境变量设置为逗号分隔的字符串。例如，具有 [1, 2, 3] 值的属性 foo 以 "1,2,3"形式保存在 foo 环境变量中。

如果资源需要支持具有 object 值或多类型数组的复杂属性，请改为将此属性设置为 stdin。
stdin - 指示资源需要一个 JSON blob，表示来自 stdin的实例。 JSON 必须遵循资源的实例架构。

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

implementsPretest

implementsPretest 属性定义资源在强制实施所需状态之前，资源是否在内部测试实例是否处于所需状态。当资源测试实例作为 set 操作的一部分时，请将此属性设置为 true。将此属性设置为不 false。在大多数情况下，此值应与资源清单中 set 方法定义中的 implementsPretest 属性相同。

当此值 false时，它指示用户应始终对实例调用 dsc resource test，然后再对资源调用 dsc resource set 命令。

默认值为 false。

Type:     boolean
Required: false
Default:  false

handlesExist

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

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

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

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

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

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

state - 指示资源仅在将设置操作作为 JSON Blob 后返回实例的预期最终状态。
stateAndDiff - 指示资源返回实例的预期最终状态和资源修改的属性名称数组。

默认值为 state。

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

通过