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
.