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.get.json
Type:          object

描述

每个基于命令的 DSC 资源都必须在其清单中定义 get 属性。此属性定义 DSC 如何获取资源实例的当前状态。

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

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

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

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

示例

示例 1 - 最小定义

此示例来自 Microsoft/OSInfo DSC 资源。

"get": {
  "executable": "osinfo"
}

它仅定义 executable 属性。当清单未定义 args时，DSC 不向命令传递任何参数。如果清单未定义 input，则默认行为是通过将 JSON Blob 发送到命令 stdin。

使用此定义，DSC 通过运行以下命令来调用 get 此资源的方法：

{ ... } | osinfo

示例 2 - 来自 stdin 的输入

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

"get": {
  "executable": "registry",
  "args": [
    "config",
    "get"
  ],
  "input": "stdin"
}

它定义为 executableregistry，而不是 registry.exe。当操作系统将命令识别为可执行文件时，不需要扩展。清单定义两个参数： config 和 get。属性 input 指示 get 命令需要其输入作为来自 stdin的 JSON Blob。结合的值 executable，DSC 通过运行以下命令为此资源调用 get 方法：

{ ... } | registry config get

示例 3 - JSON 输入参数

此示例使用 JSON 输入参数将数据发送到命令。

"get": {
  "executable": "tstoy",
  "args": [
    "config",
    "get",
    { "jsonInputArg": "--input", "mandatory": true }
  ],
}

它将可执行文件 tstoy定义为。它定义两个字符串参数和一个 JSON 输入参数。当 DSC 调用 get 此资源的操作时，它会将 JSON 数据作为压缩的 JSON 字符串传递给 --input 参数。

此操作的组合调用为：

tstoy config get --input "{ ... }"

其中 { ... } 表示资源实例的压缩 JSON。

mandatory由于 JSON 输入参数的选项设置为 true，因此当没有要发送到命令的数据时，DSC 会将空字符串传递给参数。如果未定义属性，或被定义为 false，则当没有要发送的数据时，DSC 将完全省略参数。

必需属性

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

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 输入作为字符串传递给定义的参数。
如果在未定义属性的情况下 input 定义 JSON 输入参数，DSC 仅将 JSON 输入作为字符串传递给定义的参数。

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

Type:                object
RequiredProperties: [jsonInputArg]

input

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

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

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]

通过