DSC 配置文档架构参考

2024-05-11

摘要

定义 DSC 配置的 YAML 或 JSON 文件。

元数据

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

描述

DSC 配置使用户可以通过组合不同的 DSC 资源来定义状态。配置文档使用参数和变量传递给一组定义所需状态的一个或多个资源。

可以将配置文档定义为 YAML 或 JSON。为便于创作，Microsoft 建议在 YAML 中起草配置文档。

对于 DSC 的创作工具将文件识别为 DSC 配置文档，文件名必须以 .dsc.config.json、 .dsc.config.yml或 .dsc.config.yaml结尾。

可以使用配置文档函数在运行时动态确定文档中的值。有关详细信息，请参阅 DSC 配置文档函数参考

本文档的其余部分介绍了 DSC 用于验证配置文档的架构。

示例

必需属性

每个配置文档都必须包含以下属性：

[$schema]
[resources]

属性

$schema

属性 $schema 指示文档遵循的此架构版本的规范 URL。 DSC 在任何配置操作之前验证配置文档时使用此属性。

目前有 3 个已发布版本的架构，与不同版本的 DSC 兼容：

2024/04 是架构的最新版本，与 DSC 版本 3.0.0-preview.7 及更高版本兼容。
2023/10 是架构的早期版本，与 DSC 版本 3.0.0-alpha.4 和 3.0.0-alpha.5兼容。
2023/08是架构的第一个版本，通过 3.0.0-alpha.3与 DSC 版本3.0.0-alpha.1兼容。

本文档适用于最新版本的架构。应将配置文档和资源清单更新为架构的最新版本。以前的版本不适用于 DSC 的新版本。架构保持发布状态，但不会获得任何更新。

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

.../config/document.json

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

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

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

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

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

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

metadata

属性 metadata 将一组键值对定义为配置的注释。 DSC 不会验证元数据。配置可以包含此属性中的任何任意信息。

Type:     object
Required: false

parameters

属性 parameters 为配置定义一组运行时选项。每个参数都定义为键值对。每对的键定义参数的名称。每对的值必须是一个对象，该对象定义type关键字 (keyword) 以指示 DSC 应如何处理参数。

可以在运行时重写参数，以便为不同的上下文重复使用同一配置文档。

有关在配置中定义参数的详细信息，请参阅 DSC 配置文档参数架构。

Type:                object
Required:            false
ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json

variables

属性 variables 将文档中资源的一组可重用值定义为键值对。每对的键定义变量的名称。按名称引用变量的资源可以访问变量的值。

这有助于减少配置中资源复制的值和选项的数量，从而使文档更易于阅读和维护。与参数不同，变量只能在配置中定义，不能在运行时重写。

Type:     object
Required: false

resources

属性 resources 定义配置管理的 DSC 资源实例的列表。列表中的每个实例都必须是唯一的，但实例可能共享相同的 DSC 资源类型。

有关在配置中定义有效资源实例的详细信息，请参阅 DSC 配置文档资源架构。

Type:             array
Required:         true
MinimumItemCount: 1
ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json

通过