基于命令的 DSC 扩展清单架构参考

概要

定义基于命令的 DSC 扩展的数据文件。

元数据

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

DESCRIPTION

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

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

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

必需的属性

清单必须包含以下属性：

• $schema
• 类型
• 版本
• 发现

属性

$schema

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

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

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

• .../extension/manifest.json

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

• .../bundled/extension/manifest.json

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

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

• .../bundled/extension/manifest.vscode.json

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

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

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

类型

该 type 属性表示扩展的完全限定类型名称。 有关扩展类型名称的更多信息，请参阅 DSC 资源完全限定类型名称架构参考。

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,3}\/\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

标签

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

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

发现

该discover属性定义如何调用扩展来发现 or DSC_RESOURCE_PATH 环境变量中不可用的 PATH DSC 资源。 定义此属性后，DSC 将在 discover any dsc config 或 dsc resource 命令的资源发现阶段调用扩展的作。

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

Type:     object
Required: true

退出代码

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

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

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

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