DSC 资源

在 Microsoft 的所需状态配置 （DSC） 平台中，DSC 资源表示用于管理系统设置的标准化接口。 资源可以对组件进行建模，如文件等通用组件，也可以像 IIS 服务器设置一样特定。 资源使用声明性语法而不是命令式语法。 使用 DSC 无需指定如何将系统设置为所需状态，而是指定所需状态。 资源为您处理“如何”。

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

DSC 支持多种资源：

• 使用资源清单定义的资源是 命令 资源。 DSC 使用清单来确定如何调用资源以及如何验证资源实例属性。
• 组资源是一种命令资源，其属性采用resources资源实例数组并处理它们。 组资源可以对其嵌套资源实例应用特殊处理，例如更改资源运行为的用户。
• 适配器资源是一种组资源，它允许将非命令资源与 DSC 一起使用。 例如， Microsoft.DSC/PowerShell 和 Microsoft.Windows/WindowsPowerShell 适配器资源允许在 DSC 中使用 PowerShell DSC （PSDSC） 资源，分别调用 PowerShell 和 Windows PowerShell 中的资源。

资源类型名称

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

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

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

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

有关类型名称以及 DSC 如何验证它们的详细信息，请参阅 DSC 资源完全限定的类型名称架构参考。

资源属性

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

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

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

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

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

资源可以将其属性定义为只读或只写：

• 只读资源属性定义有关资源可以检索但用户无法直接设置的实例的元数据。 您无法为实例指定所需状态的只读属性。 只读属性的示例包括上次修改文件的时间或已安装软件包的作者。
• 只写资源属性定义资源在资源作期间使用的值，但对于实例的当前状态，该值无法返回。 只写属性的示例包括用于在资源作期间进行身份验证的凭据，以及检索和解压缩远程存档时使用的临时目录。

DSC 定义一组 规范资源属性 ，这些属性指示资源参与 DSC 引擎提供的共享语义。 例如，在其实例架构中包含 _exist 规范属性的任何资源都指示该资源管理可以创建和删除的实例。 如果资源具有 _exist 规范属性和 delete 功能，则当所需状态指示实例不应存在时，DSC 可以处理调用 Delete 作而不是 Set 。 有关可用规范属性的详细信息，请参阅 DSC 规范属性。

列出资源

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

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

dsc resource list

Type                                        Kind      Version  Capabilities  RequireAdapter  Description
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Microsoft.DSC.Debug/Echo                    Resource  1.0.0    gs--t---
Microsoft.DSC.Transitional/RunCommandOnSet  Resource  0.1.0    gs------                      Takes a single-command line to execute on DSC set operation
Microsoft.DSC/Assertion                     Group     0.1.0    gs--t---                      `test` will be invoked for all resources in the supplied configuration.
Microsoft.DSC/Group                         Group     0.1.0    gs--t---                      All resources in the supplied configuration is treated as a group.
Microsoft.DSC/Include                       Importer  0.1.0    gs--t---                      Allows including a configuration file with optional parameter file.
Microsoft.DSC/PowerShell                    Adapter   0.1.0    gs--t-e-                      Resource adapter to classic DSC Powershell resources.
Microsoft.Windows/RebootPending             Resource  0.1.0    g-------                      Returns info about pending reboot.
Microsoft.Windows/Registry                  Resource  0.1.0    gs-w-d--                      Manage Windows Registry keys and values
Microsoft.Windows/WMI                       Adapter   0.1.0    g-------                      Resource adapter to WMI resources.
Microsoft.Windows/WindowsPowerShell         Adapter   0.1.0    gs--t---                      Resource adapter to classic DSC Powershell resources in Windows PowerShell.
Microsoft/OSInfo                            Resource  0.1.0    g-----e-                      Returns information about the operating system.
Microsoft/Process                           Resource  0.1.0    gs--t-e-                      Returns information about running processes.

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

调用资源

可以使用命令 dsc resource * 直接调用资源，通过三个主要 DSC作管理单个实例： Get、 Test、 Set。 如果资源具有该功能，您还可以调用 导出 或 删除 作。

获取作

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

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

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

actualState:
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

测试作

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

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

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

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

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

desiredState:
  keyPath: HKCU\key\that\does\not\exist
  _exist: true
actualState:
  keyPath: HKCU\key\that\does\not\exist
  _exist: false
inDesiredState: false
differingProperties:
- _exist

设置运算

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

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

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

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

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

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

beforeState:
  keyPath: HKCU\example\key
  _exist: false
afterState:
  keyPath: HKCU\example\key
  valueName: Example
  valueData:
    String: This is an example.
changedProperties:
- valueName
- valueData
- _exist

删除操作

为了方便起见，某些资源实现 了删除 作。 通过此作，可以调用资源以从系统中删除实例。

使用该 dsc resource delete 命令调用作。 调用 Delete 作时，除非出现错误，否则 DSC 不会返回任何输出。

例如，可以删除 在“设置 ”作示例中创建的注册表：

dsc resource delete --resource Microsoft.Windows/Registry --input '{
    "keyPath":   "HKCU\\example\\key"
}'

导出作

某些资源实现 Export 作，该作返回系统上资源的每个实例。 此作可以帮助您发现计算机当前的配置方式。

使用该 dsc resource export 命令调用作。 调用 导出 作时，DSC 将返回资源实例定义数组，您可以将其复制到配置文档中。

声明资源实例

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 配置文档 ，了解如何在配置文档中使用资源。
• 'dsc resource' 命令的命令行引用