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

概要

定义如何强制执行 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.set.json
Type:          object

Description

若要使用 DSC 管理实例，DSC 资源必须在其清单中定义属性 set 。 此属性定义 DSC 如何强制执行实例的当前状态。

如果未定义此属性，则 DSC 只能获取实例的当前状态并测试它们是否处于所需状态。 DSC 无法为资源强制实施所需的状态。

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

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

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

您必须定义 input 属性、属性数组中的 args 一个 JSON 输入参数或两者。

例子

示例 1 - 完整定义

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

"set": {
  "executable": "registry",
  "args": [
    "config",
    "set"
  ],
  "input":            "stdin",
  "implementsPretest": true,
  "return":           "state"
}

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

清单定义了两个参数， config 以及 set. 该 input 属性的值指示命令 set 将其输入期望为来自 stdin的 JSON blob。

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

{ ... } | registry config set

由于清单定义implementsPretest为 true，因此 DSC 不会在调用 set之前调用test资源的方法。 此设置表示资源本身在强制执行实例所需状态之前测试实例。

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

必需属性

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

• 可执行

属性

可执行

该 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 输入对象作为字符串传递给定义的参数。
• 如果将 as stdin 和 JSON 输入参数定义input，则 DSC 会通过 stdin 将 JSON 输入传递给定义的参数。
• 如果定义 JSON 输入参数而不定义属性 input ，则 DSC 仅将 JSON 输入作为字符串传递给定义的参数。

如果未定义 input 属性且未定义 JSON 输入参数，则 DSC 无法将输入 JSON 传递给资源。 这会使清单无效。 必须定义 input 属性、属性数组中的 args JSON 输入参数或两者兼而有之。

Type:                object
RequiredProperties: [jsonInputArg]

输入

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

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

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

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

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

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

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

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

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

实现预测试

该 implementsPretest 属性定义资源是否在强制实施所需状态之前在内部测试实例是否处于所需状态。 将此属性 true 设置为资源在作过程中 set 测试实例时。 将此属性 false 设置为不启用时。

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

默认值为 false。

Type:     boolean
Required: false
Default:  false

handles存在

该handlesExist属性定义资源是否具有作中set_exist属性的内置处理。 默认值为 false。

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

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

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

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

返回

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

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

默认值为 state。

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