DSC 资源类型架构参考

2025-08-21

Synopsis

标识资源是适配器资源、组资源、导入器资源、导出器资源还是普通资源。

Metadata

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json
Type:          string
ValidValues:  [resource, adapter, group, importer, exporter]

Description

DSC 支持多种命令资源：

resource - 指示清单适用于典型资源。
group - 指示清单用于组资源。
adapter - 指示清单用于适配器资源。
importer - 指示清单用于导入程序资源。
exporter - 指示清单用于导出器资源。

如果未在命令资源的资源清单中定义，则 kind DSC 会推断属性的值。如果在资源清单中定义了该adapter属性，则 DSC 会推断 as kind的值adapter。如果未定义该adapter属性，DSC 将推断 as kind的值resource。 DSC 无法推断清单是用于组、导入器还是导出器资源。

使用资源清单定义组、导入器或导出器资源时，请始终显式定义 kind。

适配器资源

适配器资源使非命令资源可用于 DSC。它们始终具有 resources 一个采用嵌套资源实例数组的属性。适配器可以进一步控制调整的资源的处理方式。

适配器资源必须始终定义适配器并验证资源清单中的属性。

例如，适配器 Microsoft.DSC/PowerShell 允许您在 DSC 中使用 PowerShell Desired State Configuration （PSDSC）资源。 PSDSC 资源作为 PowerShell 模块的组件发布。它们不定义资源清单。

集团资源

组资源始终在嵌套 DSC 资源实例上运行。组资源可以更改嵌套实例的处理方式，就像组资源一样 Microsoft.DSC/Assertion 。

组资源必须始终在资源清单中定义 kind 属性。

组资源还可用于将资源组捆绑在一起进行处理，就像资源一样 Microsoft.DSC/Group 。您可以使用配置中资源实例的 dependsOn 属性来指向组资源，而不是枚举列表中的每个资源。

进口商资源

导入程序资源将外部源解析为一组嵌套的 DSC 资源实例。导入程序资源的属性定义如何查找和解析外部源。

导入程序资源必须始终在资源清单中定义 kind 和 resolve 属性。

例如， Microsoft.DSC/Import importer 资源从外部配置文档解析实例，使您能够从多个文件编写配置。

出口商资源

导出器资源实现 Export 作，以返回 DSC 以递归方式导出的完整资源实例。这允许导出器资源帮助用户快速导出系统的当前配置，而无需了解每个可用资源。

例如，导出器资源可能会发现是否安装了 Apache，然后为每个支持的资源返回一个实例，以完全导出 Apache 的配置。

导出器资源必须始终在资源清单中定义 kind 和 export 属性。

嵌套资源实例

在 adapter 和 group 资源中声明的或由 importer 资源解析的资源实例称为 嵌套资源实例。

对于嵌套实例，如果满足以下条件，则资源实例相邻：

它在同一组或适配器实例中声明。
它由同一导入程序实例解析。

如果满足以下条件，则资源实例位于嵌套实例的外部：

它在组或适配器实例外部声明
它由其他导入程序实例解析
它嵌套在相邻的组、适配器或导入程序实例内。

对于顶级实例，顶层的其他实例相邻。所有其他实例都是外部实例。

请考虑以下配置代码片段。它定义七个资源实例：

在顶层，配置定义 TopLevelEcho、 TopLevelOSInfo和 TopLevelGroup 实例。
该 TopLevelGroup 实例定义嵌套实例 NestedEcho 和 NestedGroup.
该 NestedGroup 实例定义嵌套实例 DeeplyNestedEcho 和 DeeplyNestedOSInfo.

resources:
- name: TopLevelEcho
  type: Microsoft.DSC.Debug/Echo
  properties: { output: 'top level instance' }
- name: TopLevelOSInfo
  type: Microsoft/OSInfo
  properties: { }
- name: TopLevelGroup
  type: Microsoft.DSC/Group
  properties:
    $schema:
    resources:
    - name: NestedEcho
      type: Microsoft.DSC.Debug/Echo
      properties: { output: 'nested instance' }
    - name: NestedGroup
      type: Microsoft.DSC/Group
      properties:
        $schema:
        resources:
        - name: DeeplyNestedEcho
          type: Microsoft.DSC.Debug/Echo
          properties: { output: 'deeply nested instance' }
        - name: DeeplyNestedOSInfo
          type: Microsoft/OSInfo
          properties: { }

以下矩阵定义配置中每个实例的关系：

	TopLevelEcho	TopLevelOSInfo	TopLevelGroup	NestedEcho	NestedGroup	DeeplyNestedEcho	DeeplyNestedOSInfo
TopLevelEcho	Self	Adjacent	Adjacent	External	External	External	External
TopLevelOSInfo	Adjacent	Self	Adjacent	External	External	External	External
TopLevelGroup	Adjacent	Adjacent	Self	External	External	External	External
NestedEcho	External	External	External	Self	Adjacent	External	External
NestedGroup	External	External	External	Adjacent	Self	External	External
DeeplyNestedEcho	External	External	External	External	External	Self	Adjacent
DeeplyNestedOSInfo	External	External	External	External	External	Adjacent	Self

引用嵌套实例

嵌套资源实例对 dependsOn 属性和 reference（）配置函数有限制。

只能引用相邻实例。不能从声明或解析它的实例外部引用嵌套实例。不能对嵌套实例的组、适配器或导入程序资源之外的资源使用引用。
您只能将该 dependsOn 属性用于相邻实例。必须添加组、适配器或导入程序实例的依赖项，而不是嵌套实例。嵌套实例不能依赖于外部实例。

以下示例显示了有效引用和无效的引用和依赖项。这些示例使用资源 Microsoft.DSC/Group ，但 adapter 和 import 资源的功能相同。

示例 1 - 有效的引用和依赖项

此示例配置定义了多个有效的引用和依赖项。它还定义了资源的两个 Microsoft.DSC/Group 实例，一个实例嵌套在另一个实例中。

资源的顶级实例 Microsoft.DSC.Debug/Echo 引用并依赖于资源的顶级实例 Microsoft/OSInfo 。和 Microsoft.DSC.Debug/Echo 资源的顶级实例Microsoft/OSInfo都依赖于资源的顶级实例Microsoft.DSC/Group。

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
resources:
# The top level echo references and depends on the top-level OSInfo.
# It also depends on the top-level Group.
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties: # snipped for brevity

的顶级实例 Microsoft.DSC/Group 定义了三个嵌套资源实例： Microsoft.DSC.Debug/Echo、 Microsoft/OSInfo和 Microsoft.DSC/Group。与顶层一样， Microsoft.DSC.Debug/Echo 实例引用并依赖于相邻的嵌套Microsoft/OSInfo 实例，并且该实例依赖于相邻的嵌套 Microsoft.DSC/Group 实例。

# Other top-level instances snipped for brevity
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties: # snipped for brevity

最后，的 Microsoft.DSC/Group 嵌套实例定义了两个嵌套实例。引用的 Microsoft.DSC.Debug/Echo 深度嵌套实例和依赖于深度嵌套的 Microsoft/OSInfo实例。

- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # Snipped the Microsoft.DSC.Debug/Echo and Microsoft/OSInfo instances for brevity
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Microsoft.DSC.Debug/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

在每种情况下，引用和依赖项都位于配置中的相邻实例。顶级实例仅依赖于或引用顶层的其他实例。嵌套在顶级组中的实例仅依赖于或引用同一组中的其他嵌套实例。嵌套组中定义的深度嵌套实例仅依赖于或引用同一组中的其他深度嵌套实例。

将配置组合在一起，可获取此完整文档：

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
# The top level echo references and depends on the top-level OSInfo.
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Microsoft.DSC.Debug/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

示例 2 - 对嵌套实例的引用和依赖项无效

此示例配置无效，因为资源的顶级实例 Microsoft.DSC.Debug/Echo 引用并依赖于嵌套 Microsoft/OSInfo 实例。嵌套实例位于顶层实例外部，而不是相邻实例。

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Nested OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}

示例 3 - 对外部实例的引用和依赖项无效

此示例配置无效，因为资源的嵌套实例 Microsoft.DSC.Debug/Echo 引用并依赖于顶级 Microsoft/OSInfo 实例。顶级实例位于嵌套实例外部，而不是相邻实例。

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Top level OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"

反馈

此页面是否有帮助？