使用 Import-DSCResource

2024-01-11

适用于：PowerShell 7，Azure Automanage 的计算机配置功能

Import-DSCResource是动态关键字 (keyword) ，只能在块内Configuration用于导入 DSC 配置中所需的任何资源。下的 $PSHOME DSC 资源会自动导入，但最佳做法是显式导入 DSC 配置中使用的所有 DSC 资源。

Import-DSCResource 的语法如下所示。按名称指定模块时，需要在新行中列出每个模块。

Import-DscResource [-Name <ResourceName(s)>]
 [-ModuleName <ModuleName>]
 [-ModuleVersion <ModuleVersion>]

参数

名称 - 必须导入的资源。如果指定了模块名称，该命令将在该模块中搜索这些 DSC 资源;否则，命令将搜索所有模块中的 DSC 资源。支持通配符。
ModuleName - 模块名称或模块规范。如果指定要从模块导入的 DSC 资源，该命令将尝试仅导入这些 DSC 资源。如果仅指定模块，该命令将导入模块中的所有 DSC 资源。
ModuleVersion - 可以指定配置应与此参数一起使用的模块的版本。默认情况下，导入 DSC 资源的最新可用版本。

Import-DSCResource -ModuleName xActiveDirectory

示例：在 DSC 配置中使用 Import-DSCResource

Configuration MSDSCConfiguration {
    # Search for and imports two DSC Resources from the PSDscResources module.
    Import-DSCResource -ModuleName PSDscResources -Name Service, Registry

    # Search for and import Resource1 from the module that defines it. If only
    # the -Name parameter is used then resources can belong to different
    # PowerShell modules as well. TimeZone resource is from the
    # ComputerManagementDSC module which is not installed by default. As a best
    # practice, list each requirement on a different line if possible.  This
    # makes reviewing  multiple changes in source control a bit easier.
    Import-DSCResource -Name Service
    Import-DSCResource -Name TimeZone

    # Search for and import all DSC resources inside the PSDscResources module.
    # When specifying the ModuleName parameter, it is a requirement to list each
    # on a new line.
    Import-DSCResource -ModuleName PSDscResources
    # You can specify a ModuleVersion parameter
    Import-DSCResource -ModuleName ComputerManagementDsc -ModuleVersion 6.0.0.0
...

注意

不支持在同一命令中为 DSC 资源名称和模块名称指定多个值。如果多个模块中存在同一 DSC 资源，则它可能具有从哪个模块加载哪个 DSC 资源的不确定行为。以下命令在编译期间返回错误。

Import-DSCResource -Name Service, TimeZone -ModuleName PSDscResources, xPSDesiredStateConfiguration

仅使用 Name 参数时要考虑的事项：

这是一项资源密集型操作，具体取决于计算机上安装的模块数。
它加载找到的第一个具有给定名称的 DSC 资源。如果安装了多个同名的 DSC 资源，则可能会加载错误的 DSC 资源。

建议的用法是使用 Name 参数指定 ModuleName，如下所述。

这种用法具有以下优势：

它通过限制指定 DSC 资源的搜索范围来降低性能影响。
它显式定义提供 DSC 资源的模块，确保加载正确的 DSC 资源。

注意

DSC 资源可以有多个版本，并且版本可以并行安装在计算机上。这是通过具有多个版本的 DSC 资源模块（包含在同一模块文件夹中）来实现的。

使用 Import-DSCResource 的 IntelliSense

在 VS Code 中创作 DSC 配置时，PowerShell 为 DSC 资源和 DSC 资源属性提供 IntelliSense。 $PSHOME 模块路径下的资源定义将自动加载。使用 Import-DSCResource 关键字 (keyword) 导入 DSC 资源时，将添加指定的 DSC 资源定义，并扩展 IntelliSense 以包括导入的 DSC 资源的架构。

DSC 资源的 VS Code 中的 IntelliSense

编译 DSC 配置时，PowerShell 使用导入的 DSC 资源定义来验证块中的 Configuration DSC 资源块。每个 DSC 资源块都由 DSC 资源的架构定义根据以下规则进行验证：

仅指定在架构中定义的属性。
每个属性的数据类型均正确无误。
指定键属性。
未指定只读属性。

请考虑以下 DSC 配置：

Configuration SchemaValidationInCorrectEnumValue {
    Import-DSCResource -Name User -Module PSDscResources

    User ExampleUser {
        UserName = 'ExampleDscUser'
        Ensure   = 'Invalid'
    }
}

编译此 DSC 配置会导致错误。

Write-Error: C:\code\dsc\sample.ps1:4:5
Line |
   4 |      User ExampleUser {
     |      ~~~~
     | At least one of the values 'Invalid' is not supported or   
     | valid for property 'Ensure' on class 'User'. Please specify
     | only supported values: Present, Absent.

InvalidOperation: Errors occurred while processing configuration
'SchemaValidationInCorrectEnumValue'.

借助 IntelliSense 和架构验证，可以在分析和编译期间捕获更多错误，从而避免将来出现复杂情况。

注意

每个 DSC 资源都可以具有由 DSC 资源的架构定义的 名称和 FriendlyName 。下面是的前两行 MSFT_UserResource.schema.mof。

[ClassVersion("1.0.0"), FriendlyName("User")]
class MSFT_UserResource : OMI_BaseResource

在块中 Configuration 使用此 DSC 资源时，可以指定 MSFT_UserResource 或 User。

另请参阅

资源

通过

使用 Import-DSCResource

示例：在 DSC 配置中使用 Import-DSCResource

使用 Import-DSCResource 的 IntelliSense

另请参阅

其他资源