Using Import-DSCResource

Applies To: PowerShell 7, Azure Automanage's machine configuration feature

Import-DSCResource is a dynamic keyword, which can only be used inside a Configuration block to import any resources needed in your DSC Configuration. DSC Resources under $PSHOME are imported automatically, but it's best practice to explicitly import all DSC Resources used in your DSC Configuration.

The syntax for Import-DSCResource is shown below. When specifying modules by name, it's required to list each on a new line.

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

Parameters

• Name - The Resources that you must import. If the module name is specified, the command searches for these DSC Resources within that module; otherwise the command searches the DSC Resources in all modules. Wildcards are supported.
• ModuleName - The module name or module specification. If you specify DSC Resources to import from a module, the command tries to import only those DSC Resources. If you specify the module only, the command imports all the DSC Resources in the module.
• ModuleVersion - You can specify the version of a module a configuration should use with this parameter. By default, the latest available version of the DSC Resource is imported.

Import-DSCResource -ModuleName xActiveDirectory

Example: Use Import-DSCResource within a DSC Configuration

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
...

Note

Specifying multiple values for DSC Resource names and modules names in same command isn't supported. It can have non-deterministic behavior about which DSC Resource to load from which module if the same DSC Resource exists in multiple modules. The command below returns an in error during compilation.

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

Things to consider when using only the Name parameter:

• It's a resource-intensive operation depending on the number of modules installed on the machine.
• It loads the first DSC Resource found with the given name. If there is more than one DSC Resource with same name installed, it could load the wrong DSC Resource.

The recommended usage is to specify ModuleName with the Name parameter, as described below.

This usage has the following benefits:

• It reduces the performance impact by limiting the search scope for the specified DSC Resource.
• It explicitly defines the module providing the DSC Resource, ensuring the correct DSC Resource is loaded.

Note

DSC resources can have multiple versions, and versions can be installed on a computer side-by-side. This is implemented by having multiple versions of a DSC Resource module that are contained in the same module folder.

IntelliSense with Import-DSCResource

When authoring the DSC Configuration in VS Code, PowerShell provides IntelliSense for DSC Resources and DSC Resource properties. Resource definitions under the $PSHOME module path are loaded automatically. When you import DSC Resources using the Import-DSCResource keyword, the specified DSC Resource definitions are added and IntelliSense is expanded to include the imported DSC Resources' schemas.

When compiling the DSC Configuration, PowerShell uses the imported DSC Resource definitions to validate the DSC Resource blocks in the Configuration block. Each DSC Resource block is validated by the DSC Resource's schema definition, for the following rules:

• Only properties defined in schema are specified.
• The data types for each property are correct.
• Keys properties are specified.
• No read-only property is specified.

Consider the following DSC Configuration:

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

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

Compiling this DSC Configuration results in an error.

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 and schema validation allow you to catch more errors during parse and compilation time, avoiding future complications.

Note

Each DSC Resource can have a name and a FriendlyName defined by the DSC Resource's schema. Below are the first two lines of MSFT_UserResource.schema.mof.

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

When using this DSC Resource in a Configuration block, you can specify MSFT_UserResource or User.

See also

• Resources