通过

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

Synopsis

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

Metadata

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

Description

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

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

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

必需的属性

清单必须包含以下属性：

属性

$schema

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

DSC 的 JSON 架构以多个版本和形式发布。 本文档适用于最新版本的架构。 为方便起见，您可以为 GitHub 中托管的架构指定完整的 URI，也可以使用较短 aka.ms 的 URI。 您可以为特定语义版本指定 Schema，为次要版本指定 latest Schema，或者为 DSC 的主要版本指定 latest Schema。 有关架构 URI 和版本控制的更多信息，请参阅 DSC JSON 架构 URI。

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

  • .../resource/manifest.json

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

  • .../bundled/resource/manifest.json

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

    此架构使用为 JSON 架构 2020-12 引入的捆绑模型。 虽然 DSC 在使用此架构时仍可以验证文档，但如果其他工具不完全支持 2020-12 规范，则它们可能会出错或以意外方式运行。

  • .../bundled/resource/manifest.vscode.json

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

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

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.2/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.json
             ]

类型

该 type 属性表示资源的完全限定类型名称。 它用于在配置文档中指定资源，并在使用--resource命令时作为标志的值dsc 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

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

Type:     string
Required: false

kind

该 kind 属性定义 DSC 应如何处理资源。 DSC 支持多种类型的 DSC 资源：resource、group、、 adapterimporterexporter和 。

如果未在资源清单中定义， kind DSC 会推断属性的值。 如果在资源清单中定义了该adapter属性，则 DSC 会推断 as kind的值adapter。 如果未定义该adapter属性，DSC 将推断 as kind的值resource。 DSC 无法推断清单是针对资源 group 还是 importer 资源。

定义组资源时，请始终将清单kind中的属性显式定义为 group 。 定义导入程序资源时，请始终将清单kind中的属性显式定义为 importer 。

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

Type:        string
Required:    false
ValidValues: [resource, adapter, group, importer, exporter]

tags

该 tags 属性定义资源的可搜索词列表。 此属性的值必须是字符串数组。 每个标记必须仅包含字母数字字符和下划线。 不允许使用其他字符。 每个标记必须是唯一的。

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

导出

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

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

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

Type:     object
Required: true

get

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

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

Type:     object
Required: true

set

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

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

Type:     object
Required: false

whatIf

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

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

测试

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

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

Type:     object
Required: false

验证

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

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

Type:     object
Required: false

提供商

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

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

exitCodes

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

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

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

Tip

如果要在 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