通过

dsc 资源集

摘要

调用资源的 set 操作。

语法

来自 stdin 的实例属性

<instance-properties> | dsc resource set [Options] --resource <RESOURCE>

输入选项中的实例属性

dsc resource set --input '<instance-properties>' --resource <RESOURCE>

文件中的实例属性

dsc resource set --path <instance-properties-filepath> --resource <RESOURCE>

说明

子 set 命令强制执行资源实例的所需状态，并返回最终状态。

此子命令设置特定 DSC 资源的一个实例。 若要设置多个资源，请使用资源组或 dsc 配置集 命令。

要设置的实例的所需状态必须作为 JSON 或 YAML 对象传递给此命令。 对象属性必须是资源的有效属性。 实例属性可以从 stdin、包含 选项的字符串 --input 或从具有 --path 选项的已保存文件传递给此命令。

只能对定义 set 其资源清单部分的基于命令的 DSC 资源调用此子命令。 如果为未定义设置操作的资源调用此子命令，DSC 将引发错误。

重要

命令 dsc resource set 始终调用 set 资源的 操作。 资源可能（但不是必需的）实现预测试操作实例的 set 逻辑。

这与 dsc 配置集 的工作方式不同，DSC 始终通过综合方式或通过调用 test 资源的操作来测试实例，并且仅在实例未处于所需状态时调用 set 实例。

基于命令的资源通过在其资源清单中定义 set.implementsPretest 属性来指示它们是否实现set操作的预测试。 如果该属性定义为 true，则表示资源实现预测试。 如果 set.implementsPretest 设置为 false 或 未定义，则清单指示资源未实现预测试。

如果资源指示它实现了预测试，则用户应期望该资源仅在操作期间 set 修改实例，前提是预测试显示该实例未处于所需状态。

如果资源未实现预测试，用户应期望资源在操作期间 set 始终修改实例。

对于未实现set操作预测试的资源，Microsoft 建议在调用 dsc resource set之前始终对实例调用 dsc resource test ，以查看它是否处于所需状态。 这有助于避免由未实现完全幂等命令 set 的资源导致的意外错误。

示例

示例 1 - 使用 stdin 中的属性设置资源

命令可确保密钥 Example 存在于当前用户配置单元中。 它将资源实例属性指定为 JSON，并从 stdin 传递这些属性。

'{
    "keyPath": "HKCU\\Example",
    "_exist": true
}' | dsc resource set --resource Microsoft.Windows/Registry

示例 2 - 使用输入选项设置资源

命令可确保密钥 Example 存在于当前用户配置单元中。 它将资源实例属性指定为 JSON，并使用 输入 选项传递它们。

dsc resource set --resource Microsoft.Windows/Registry --input '{
    "keyPath": "HKCU\\Example",
    "_exist": true
}'

示例 3 - 使用 YAML 文件中的属性设置资源

命令可确保密钥 Example 存在于当前用户配置单元中。 它指定 yaml 文件的路径，该文件使用 path 选项定义资源实例属性。

cat ./example.yaml

keyPath: HKCU\\Example
_exist:  true

dsc resource set --resource Microsoft.Windows/Registry --path ./example.yaml

选项

-r、--resource

指定要使用的 DSC 资源的完全限定类型名称，例如 Microsoft.Windows/Registry。

完全限定的类型名称语法为： <owner>[.<group>][.<area>]/<name>，其中：

  • 是 owner 资源的维护作者或组织。
  • group和 area 是可选名称组件，用于为资源启用命名空间。
  • 标识 name 资源管理的组件。
Type:      String
Mandatory: true

-i、 --input

指定 JSON 或 YAML 对象，其属性定义 DSC 资源实例的所需状态。 DSC 根据资源的实例架构验证对象。 如果验证失败，DSC 将引发错误。

此选项不能与 stdin 或 --path 选项上的实例属性一起使用。 选择是将实例属性通过 stdin 传递给命令，还是从具有 --path 选项 --input 的 文件中传递。

Type:      String
Mandatory: false

-p、--path

定义要读取为命令输入的文本文件的路径，而不是从 stdin 传递输入，或者使用 选项将其作为字符串 --input 传递。 指定的文件必须包含表示资源的有效属性的 JSON 或 YAML。 DSC 根据资源的实例架构验证对象。 如果验证失败，或者指定的文件不存在，DSC 将引发错误。

此选项与 --input 选项互斥。 使用此选项时，DSC 会忽略来自 stdin 的任何输入。

Type:      String
Mandatory: false

-f、 --format

选项 --format 控制命令的控制台输出格式。 如果命令输出被重定向或捕获为变量，则输出始终为 JSON。

Type:         String
Mandatory:    false
DefaultValue: yaml
ValidValues:  [json, pretty-json, yaml]

-h、--help

显示当前命令或子命令的帮助。 指定此选项时，应用程序将忽略此选项之后的所有选项和参数。

Type:      Boolean
Mandatory: false

输出

此命令返回 JSON 输出，其中包括设置操作之前和之后实例的实际状态，以及设置操作修改的属性列表。 有关详细信息，请参阅 dsc 资源集结果架构。