基于命令的 DSC 资源剖析

DSC 资源提供了一个标准化的界面，用于管理系统设置。 资源定义了可以管理的属性，并实现获取资源实例所需的代码。

DSC 命令资源至少使用两个文件定义：

1. 告知 DSC 如何与资源交互的 DSC 资源清单。
2. 一个或多个可执行文件及其依赖项，用于管理资源实例。

DSC 资源清单

DSC 资源清单定义为数据文件。 要使 DSC 将数据文件识别为清单，该文件必须满足以下条件：

1. 文件中的数据必须格式为 YAML 或 JSON。

2. 该文件必须使用 UTF-8 编码。

3. 该文件必须在环境变量中 PATH 可发现。

4. 文件名必须以以下后缀之一结尾：

   • .dsc.resource.json
   • .dsc.resource.yaml
   • .dsc.resource.yml

当 DSC 在本地系统中搜索可用的命令资源时，它会搜索 中的 PATH 每个文件夹，以查找使用 DSC 资源清单命名约定的文件。 然后，DSC 分析每个发现的文件，并根据 DSC 资源清单 JSON 架构验证它们。

如果 JSON 文件根据架构进行验证，则 DSC 可以使用 DSC 资源。

清单至少必须定义：

• 与其兼容的 DSC 资源清单 JSON 架构的版本。
• 资源的完全限定名称，例如 Microsoft.Windows/Registry。 完全限定的名称语法是 <owner>[.<group>][.<area>]/<name>。 完全限定名称的组和区域组件允许将资源组织到命名空间中。
• DSC 如何调用命令来获取资源实例的当前状态。
• 一种验证实例的方法。 验证实例的选项包括：
  • 描述实例的 JSON 架构
  • DSC 必须调用命令才能在运行时获取架构
  • 用于验证嵌套 DSC 资源的命令。 最后一个选项仅适用于 DSC 组资源和 DSC 适配器资源。

清单可以定义：

• 清单描述的资源类型： adapter、 group、 importer或 resource。

  如果清单未定义资源类型，则默认为 resource 并被解释为直接管理实例的典型资源。

• DSC 如何调用命令来测试实例是否处于所需状态。

  如果清单未定义如何测试资源的实例，则 DSC 将对资源实例执行综合测试。 DSC 的综合测试始终获取实例的实际状态，并将实例的属性与所需状态进行严格区分大小写的比较。 如果任何属性与定义的所需状态不完全相同，DSC 会将实例报告为不合规。

• DSC 如何调用命令将实例设置为所需状态。

  如果清单未定义如何设置 DSC 资源的实例，则 DSC 无法使用该资源强制实施所需状态。

• 命令返回的非零退出代码的含义。

  如果清单未定义退出代码的含义，则所有非零退出代码都将报告为泛型故障。

• DSC 如何调用命令以导出计算机上该资源的每个实例的列表。

• DSC 如何调用命令来删除资源的特定实例。

• 有关资源的元数据，例如其作者和简短说明。

清单不需要为每个作指定相同的可执行文件。 每个作的定义都是独立的。

DSC 资源可执行文件

命令资源始终需要可执行文件才能运行 DSC。 清单不需要与可执行文件捆绑在一起。 可执行文件可以是任何可执行文件，例如二进制应用程序或 shell 脚本。 资源可以对不同的作使用不同的可执行文件。

要使 DSC 使用可执行文件，它必须在环境变量中 PATH 可发现。 DSC 每个作调用可执行文件一次，使用可执行文件返回的退出代码来确定命令是否成功。 DSC 将退出代码 0 视为成功，将所有其他退出代码视为错误。

输入

DSC 通过以下方式之一将输入发送到命令资源：

• 基于 stdin 的 JSON 数据 blob。

  当 DSC 通过 stdin 将输入作为 JSON 发送时，数据 blob 是实例所需状态的 JSON 表示形式。 此输入选项支持具有嵌套对象的复杂属性。

• JSON 数据 blob 作为特定参数的值。

  当资源定义 JSON 输入参数时，DSC 会使用定义的参数调用命令，并将实例所需状态的 JSON 表示形式传递给该参数。 此输入选项支持具有嵌套对象的复杂属性。

• 一组参数标志和值。

  当 DSC 将输入作为参数发送时，它会为每个指定的属性生成一对参数。 第一个参数是以 为 --前缀的属性名称，例如 --duration。 第二个参数是属性的值。 参数对的顺序不保证。 此输入法不支持复杂属性。

• 环境变量。

  当 DSC 将输入作为环境变量发送时，它会为资源实例的每个属性定义一个环境变量，并将值设置为该属性的字符串表示形式。 这些环境变量仅用于执行该特定作的命令。 环境变量不会影响任何其他进程。

输入处理在资源清单中按作定义。 资源可以为其支持的作定义不同的输入处理。

输出

当 DSC 调用时，命令资源的可执行文件必须将 JSON 数据返回到 stdout。 输出编码必须是 UTF-8。 当资源返回实例的状态时，DSC 会根据资源的实例架构验证 JSON 数据。

对于适配器资源，DSC 希望可执行文件将其管理的资源的实例状态传递为单个 JSON 数组或一系列 JSON 行。

命令资源可以通过向 stderr 发出 JSON 行来向 DSC 报告日志信息。 每个日志条目必须是包含两个键的 JSON 对象：

1. 该 message 键定义日志条目的人类可读字符串。
2. 该level键定义消息是否表示 error、 a 或 warninginformation。

DSC 从资源收集消息，并将其显示在配置作的结果中。 当 DSC 直接在配置外部调用资源时，它不会收集消息。 相反，DSC 将消息发出到 stderr。

相关内容

• DSC 资源清单架构参考
• DSC 资源