DSC 资源清单测试属性架构参考

2024-05-11

摘要

定义如何测试 DSC 资源实例是否处于所需状态。

元数据

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

描述

如果 DSC 资源实现自己的逻辑来确定实例是否处于所需状态，则必须在其清单中定义 test 属性。此属性定义 DSC 如何调用资源来测试实例是否处于所需状态。

如果未定义此属性，DSC 会为资源使用综合测试方法。综合测试方法：

使用资源的 get 方法获取实例的实际状态。
将实例所需状态的每个已定义属性与实际状态进行比较。
如果属性的所需状态不等于该属性的实际状态，DSC 将报告实例未处于所需状态。

由于综合测试仅检查等效性，因此无法准确测试具有无法单独使用等效性评估的属性的资源。例如，如果资源管理包版本并允许将版本设置为 latest，DSC 会报告版本 3.1.0 为的实例，即使 3.1.0 是包的最新版本，也是如此。

对于具有无法单独通过等效性评估的属性的资源，请始终在清单中定义 test 属性。

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

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

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

必须定义 input 属性和/或属性数组中的 args 一个 JSON 输入参数。

示例

示例 1 - 完整定义

此示例来自 Microsoft.Windows/Registry DSC 资源。

"test": {
  "executable": "registry",
  "args": [
    "config",
    "test"
  ],
  "input": "stdin",
  "return": "state"
}

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

清单定义两个参数： config 和 test。属性的值 input 指示 test 命令需要其输入作为来自 stdin的 JSON Blob。

结合的值 executable，DSC 通过运行以下 test 方法为此资源调用方法：

{ ... } | registry config test

清单定义为 returnstate，指示它仅在方法运行时返回资源 test 的实际状态。

必需属性

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

executable

属性

可执行文件

属性 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 数据：

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

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

Type:                object
RequiredProperties: [jsonInputArg]

input

属性 input 定义如何将输入传递到资源。如果未定义此属性，则 DSC 在调用 test 操作时不会向资源发送任何输入。

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

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

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

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

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

return

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

state - 指示资源仅返回实例的实际状态。
stateAndDiff - 指示资源返回实例的实际状态和属性名称的数组，这些名称不是所需状态。

默认值为 state。

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

通过