基于命令的 DSC 资源清单架构参考

项目
08/08/2024

概要

定义基于命令的 DSC 资源的数据文件。

元数据

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
Type:          object

描述

每个基于命令的 DSC 资源都必须有一个清单。清单文件必须：

可在 PATH 环境变量中发现。
格式为 JSON 或 YAML。
遵循命名约定 <name>.dsc.resource.<extension>。有效的扩展包括 json、yml和 yaml。
对本文档中所述的架构有效。

本文档的其余部分描述了清单的架构。

必需属性

清单必须包含以下属性：

$schema
类型
版本
获取

性能

$schema

$schema 属性指示清单验证的此架构的规范 URI。此属性是必需的。 DSC 使用此值根据正确的 JSON 架构验证清单。

对于架构的每个版本，都有三个有效的 URL：

.../resource/manifest.json

规范非捆绑架构的 URL。用于验证时，验证客户端需要检索此架构及其引用的每个架构。
.../bundled/resource/manifest.json

捆绑架构的 URL。当它用于验证时，验证客户端只需要检索此架构。

此架构使用为 JSON 架构 2020-12 引入的捆绑模型。尽管 DSC 在使用此架构时仍可以验证文档，但其他工具可能会出错或行为意外。
.../bundled/resource/manifest.vscode.json

增强创作架构的 URL。此架构比其他架构大得多，因为它包括其他架构，这些定义提供其他架构不包含的上下文帮助和代码片段。

此架构使用仅由 VS Code 识别的关键字。尽管 DSC 在使用此架构时仍可以验证文档，但其他工具可能会出错或行为意外。

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

类型

type 属性表示资源的完全限定类型名称。它用于在配置文档中指定资源，并在使用 dsc resource * 命令时指定 --resource 标志的值。有关资源类型名称的详细信息，请参阅 DSC 资源完全限定的类型名称架构参考。

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

版本

version 属性必须是当前版本的资源作为有效的语义版本（semver）字符串。版本适用于资源，不适用于它管理的软件。

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

描述

description 属性定义资源用途的摘要。此属性的值必须是短字符串。

Type:     string
Required: false

类

kind 属性定义 DSC 如何处理资源。 DSC 支持三种类型的基于命令的 DSC 资源：Resource、Group和 Adapter。

在资源清单中未定义 kind 时，DSC 将推断该属性的值。如果在资源清单中定义了 adapter 属性，DSC 会将 kind 的值推断为 Adapter。如果未定义 adapter 属性，DSC 会将 kind 的值推断为 Resource。 DSC 无法推断清单是否适用于组资源。

定义组资源时，始终将清单中的 kind 属性显式定义为 Group。

有关详细信息，请参阅 DSC 资源类型架构参考。

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

出口

export 属性定义如何调用资源以获取每个实例的当前状态。定义此属性后，用户可以：

在输入配置中为 dsc 配置导出命令指定资源实例，以生成可用配置文档。
使用 dsc 资源导出命令指定资源，以生成定义资源的每个实例的配置文档。
使用 dsc 资源获取命令和 --all 选项指定资源，以返回每个资源实例的当前状态。

此属性的值必须是对象。对象的 executable 属性（定义要调用的命令的名称）是必需的。 args 属性是可选的。有关详细信息，请参阅 DSC 资源清单导出属性架构参考。

Type:     object
Required: true

获取

get 属性定义如何调用资源以获取实例的当前状态。对于所有资源，此属性是必需的。

此属性的值必须是对象。对象的 executable 属性（定义要调用的命令的名称）是必需的。 args 和 input 属性是可选的。有关详细信息，请参阅 DSC 资源清单获取属性架构参考。

Type:     object
Required: true

设置

set 属性定义如何调用资源以设置实例的所需状态。它还定义如何处理此方法的资源输出。如果未定义此属性，DSC 将无法管理资源的实例。它只能获取其当前状态并测试实例是否处于所需状态。

此属性的值必须是对象。 executable 属性（定义要调用的命令的名称）是必需的。 args input、implementsPretest和 returns 属性是可选的。有关详细信息，请参阅 DSC 资源清单集属性架构参考。

Type:     object
Required: false

whatIf

定义 DSC 如何调用 DSC 资源来指示设置命令是否会修改实例以及如何处理 DSC 资源的输出。如果资源未在清单中定义此方法，DSC 通过将资源的测试操作结果转换为设置结果来合成此行为。

此属性的值必须是对象。 executable 属性（定义要调用的命令的名称）是必需的。 args input、implementsPretest和 returns 属性是可选的。有关详细信息，请参阅 DSC 资源清单 whatIf 属性架构参考。

测试

test 属性定义如何调用资源以测试实例是否处于所需状态。它还定义如何处理此方法的资源输出。如果未定义此属性，DSC 将为 DSC 资源的实例执行基本综合测试。

此属性的值必须是对象。对象的 executable 属性（定义要调用的命令的名称）是必需的。 args input和 returns 属性是可选的。有关详细信息，请参阅 DSC 资源清单测试属性架构参考。

Type:     object
Required: false

驗證

validate 属性定义如何调用 DSC 组资源来验证其实例。对于 DSC 组资源，此属性是必需的。 DSC 将忽略所有其他资源的此属性。

此属性的值必须是对象。对象的 executable 属性（定义要调用的命令的名称）是必需的。 args 属性是可选的。有关详细信息，请参阅 DSC 资源清单验证属性架构参考。

Type:     object
Required: false

供应商

指定后，provider 属性将资源定义为 DSC 资源提供程序。

此属性的值必须是对象。对象的 list 和 config 属性是必需的。 list 属性定义如何调用提供程序以返回提供程序可以管理的资源。 config 属性定义提供程序期望输入的方式。有关详细信息，请参阅 DSC 资源清单提供程序属性架构参考。

exitCodes

exitCodes 属性定义资源的一组有效退出代码及其含义。将此属性定义为一组键值对，其中：

该键是一个字符串，其中包含映射到资源的已知退出代码的带符号整数。退出代码必须是文本带符号整数。不能对退出代码使用备用格式。例如，将退出代码指定为 -2147024891，而不是“拒绝访问”的十六进制值 0x80070005。
该值是描述人类读取器的退出代码的语义含义的字符串。

DSC 将退出代码 0 解释为成功操作，将任何其他退出代码解释为错误。

提示

如果要在 yaml 中创作资源清单，请务必将退出代码包装在单引号中，以确保可以正确分析 YAML 文件。例如：

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

图式

schema 属性定义如何获取用于验证资源实例的 JSON 架构。此属性必须始终是定义以下属性之一的对象：

command - 指定 command 属性时，DSC 会调用定义的命令来获取 JSON 架构。
embedded - 指定 embedded 属性时，DSC 使用定义的值作为 JSON 架构。

有关详细信息，请参阅 DSC 资源清单架构属性引用。

Type:     object
Required: true

通过

基于命令的 DSC 资源清单架构参考

概要

元数据

描述

必需属性

性能

$schema

类型

版本

描述

类

标签

出口

获取

设置

whatIf

测试

驗證

供应商

exitCodes

图式

其他资源