通过

基于命令的 DSC 资源的剖析

  • 项目

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

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

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

DSC 资源清单

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

  1. 文件必须在环境变量中 PATH 可发现。
  2. 文件名必须以 .dsc.resource.json结尾。

当 DSC 在本地系统中搜索可用的基于命令的 DSC 资源时，它会在 中的每个 PATH 文件夹中搜索使用 DSC 资源清单命名约定的文件。 然后，DSC 会分析发现的每个文件，并针对 DSC 资源清单 JSON 架构对其进行验证。

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

清单至少必须定义：

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

清单可以选择性地定义：

  • DSC 如何调用 命令来测试实例是否处于所需状态。
  • DSC 如何调用 命令以将实例设置为所需状态。
  • 命令返回的非零退出代码的含义。
  • 当资源是 DSC 组资源或 DSC 提供程序资源时，DSC 如何调用 命令来管理其他 DSC 资源。
  • 有关资源的元数据，例如其作者和简短说明。

如果清单未定义如何测试资源的实例，DSC 会对资源实例执行综合测试。 DSC 的合成测试始终获取实例的实际状态，并将实例的属性与所需状态进行严格区分大小写的比较。 综合测试将忽略任何带有下划线 (_) 或美元符号 ($) 的属性。 如果任何属性与定义的所需状态不完全相同，DSC 会将实例报告为不符合。

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

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

DSC 资源可执行文件

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

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

输入

DSC 将输入作为 stdin 的 JSON 数据 Blob 或一组参数标志和值发送到基于命令的 DSC 资源。 输入处理在 DSC 资源清单中按操作定义。

当 DSC 通过 stdin 将输入作为 JSON 发送时，数据 blob 是实例所需状态的 JSON 表示形式。 这是资源最可靠的选项，因为它使资源能够支持具有嵌套对象的复杂属性。

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

输出

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

对于 DSC 提供程序资源，DSC 要求可执行文件通过它作为单个 JSON 数组或一系列 JSON 行管理的资源的实例状态。

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

  1. 键 message 定义日志条目的可读字符串。
  2. 键 level 定义消息是表示 Error、 Warning、 还是 Information。

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

相关内容