DSC 资源

项目
03/18/2025

在Microsoft的 Desired State Configuration （DSC）平台中，DSC 资源表示用于管理系统设置的标准化接口。资源可以将组件建模为通用文件或特定于 IIS 服务器设置。资源使用声明性语法，而不是命令性语法。使用 DSC，而不是指定将系统设置为所需状态的方式，而是指定 所需状态。资源会为你处理“作方法”。

资源管理可配置组件的实例。例如，PSDscResources/Environment 资源管理环境变量。每个环境变量都是资源的不同实例。每个资源都定义一个架构，该架构描述如何验证和管理资源的实例。

DSCv3 支持多种资源：

使用资源清单定义的资源是基于命令的资源。 DSC 使用清单来确定如何调用资源以及如何验证资源实例属性。
资源组 是一种基于命令的资源，其 resources 属性采用资源实例数组并对其进行处理。资源组可能会对其嵌套资源实例应用特殊处理，例如更改资源运行方式的用户。
资源提供程序 是一个资源组，可用于通过 DSCv3 使用基于命令的资源。例如，DSC/PowerShellGroup 资源提供程序允许使用 PowerShell 模块中实现的 DSC 资源。

资源类型名称

资源由其完全限定的类型名称标识。类型名称用于在配置文档中指定资源，并在使用 dsc resource * 命令时指定 --resource 标志的值。

资源的完全限定类型名称使用以下语法：

<owner>[.<group>][.<area>]/<name>

每个资源都必须定义 owner 和 name。 group 和 area 组件使资源能够组织到相关命名空间中，例如 Microsoft.SqlServer/Database 和 Microsoft.SqlServer.Database/Role。

有关类型名称及其验证方式的详细信息，请参阅 DSC 资源完全限定的类型名称架构参考。

资源属性

资源的属性是用户可以声明用于管理实例的设置和选项。资源始终至少有一个属性。资源在其架构中定义其属性。

默认情况下，属性是可选的。可以直接调用资源，也可以仅在配置中声明与当前任务或用途相关的属性。无需声明实例的每个属性。属性可能具有其所需状态的默认值。

大多数属性都是基本类型之一：

字符串属性要求属性值为一组字符，如 machine。
整数属性要求属性值为没有小数部分的数字，如 5。
布尔属性要求属性值 true 或 false。
数组属性要求属性值是项列表。通常，数组属性指定这些值必须是特定类型，例如退出代码整数列表或文件路径列表。

复杂属性要求属性值是具有定义的子属性的对象。子属性可以是基本属性或复杂属性，但它们通常是基本类型。

列出资源

可以使用 DSC 通过 dsc resource list 命令列出可用资源。 DSC 在 PATH 中搜索基于命令的资源，并调用可用的资源提供程序来列出其资源。

默认情况下，该命令将返回每个发现的 DSC 资源。

dsc resource list

type                       version tags                        description
----                       ------- ----                        -----------
Test/TestGroup             0.1.0
Microsoft/OSInfo           0.1.0   {os, linux, windows, macos} Returns information about the operating system.
Microsoft.Windows/Registry 0.1.0   {Windows, NT}               Registry configuration provider for the Windows Registry
                                                               This is a test resource.
DSC/PowerShellGroup        0.1.0   {PowerShell}                Resource provider to classic DSC Powershell resources.
DSC/AssertionGroup         0.1.0                               `test` will be invoked for all resources in the supplied configuration.
DSC/ParallelGroup          0.1.0                               All resources in the supplied configuration run concurrently.
                                                               This is a test resource.
DSC/Group                  0.1.0                               All resources in the supplied configuration is treated as a group.

可以按资源的类型名称、说明和标记筛选结果。有关详细信息，请参阅 dsc 资源列表

调用资源

可以使用 dsc resource * 命令直接调用资源，通过三个 DSC作管理单个实例，获取、测试，以及集。

获取作

每个资源实现获取作，该作检索资源实例的实际状态。使用 dsc resource get 命令调用作。

例如，可以使用 Microsoft.Windows/Registry 资源获取注册表项值的实际状态：

'{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

测试作

某些资源实现测试作。对于未实现测试作的资源，DSCv3 可以使用综合测试来验证实例的状态。综合测试是对实例属性所需值和实际值的严格不区分大小写的比较。只有具有高级或复杂验证要求的资源才能自行实现测试作。

使用 dsc resource test 命令调用作。 DSC 返回包括：

实例的所需状态。
实例的实际状态。
实例是否处于所需状态。
不处于所需状态的属性列表。

例如，可以测试是否存在特定的注册表项：

'{
    "keyPath": "HKCU\\key\\that\\does\\not\\exist",
}' | dsc resource test --resource Microsoft.Windows/Registry

desiredState:
  keyPath: HKCU\key\that\does\not\exist
actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
  _inDesiredState: false
inDesiredState: false
differingProperties:
- keyPath

设置作

大多数资源实现集作，该作强制实施实例的所需状态。与 DSCv3 一起使用时，Set作幂等，这意味着资源仅在实例不处于所需状态时调用该作。由于作是幂等的，因此反复调用该作与调用一次相同。幂等模型可防止不必要的执行代码产生副作用。

未实现集作的资源断言资源。可以使用断言资源来检索和验证实例的状态，但不能使用它们来强制实施所需状态。

使用 dsc resource set 命令调用作。 DSC 返回包括：

作前实例的状态。
作后实例的状态。
作更改的属性列表。

例如，可以通过为不存在的密钥设置所需的状态来创建注册表项。

'{
    "keyPath":   "HKCU\\example\\key",
    "valueName": "Example",
    "valueData": { "String": "This is an example." }
}' | dsc resource set --resource Microsoft.Windows/Registry

beforeState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
afterState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKCU\example\key
  valueName: Example
  valueData:
    String: This is an example.
changedProperties:
- keyPath
- valueName
- valueData

声明资源实例

DSC 配置文档允许一次管理多个资源或资源实例。配置文档声明资源实例的集合及其所需状态。这样就可以通过将不同的资源和实例组合在一起来为复杂的所需状态建模，例如为符合性定义安全基线或 Web 场的设置。

资源实例声明始终包括：

name - 文档中唯一的实例的简短、可读名称。此名称用于日志记录，有助于记录文档中实例的用途。
type - 资源的完全限定类型名称，用于标识资源 DSC 应用于管理实例。
properties - 实例的所需状态。 DSC 根据资源的实例架构验证值。

此示例配置文档片段声明 Microsoft.Windows/Registry 资源的实例。

$schema: https://schemas.microsoft.com/dsc/2023/08/configuration.schema.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

另请参阅

基于命令的 DSC 资源剖析，了解如何使用所选语言创作资源。
配置文档了解如何在配置文档中使用资源。
“dsc resource”命令的命令行参考

通过