Understanding Import-DscResource Keyword in Desired State Configuration

Understanding Import-DscResource Keyword in Desired State Configuration

Rate This
  • Comments 2

Desired State Configuration resources are used to model and change the state of different components of the system. In an earlier blog post, we discussed details about deploying and discovering those resources and introduced Import-DscResource dynamic keyword. In this post, we will discuss some more details about the usage and internal working of this dynamic keyword.  This keyword is only available inside configuration block. Its syntax looks like PowerShell cmdlet but it’s not a cmdlet and behaves differently. 

 

When authoring the DSC configuration in ISE, the PowerShell parser, provides IntelliSence for resources and resource properties by auto loading the resource definitions from $pshome module path. Moreover, the same resource definitions are used during compilation step (generation of MOF document) to validate the entries of the configuration. E.g. resource schema validation is done for following:

  •           Only properties defined in schema are used
  •           The data types for each property is correct
  •            Keys properties are specified
  •            No read only property is used
  •           Validation on value maps types

 

Consider this configuration:

 

Configuration SchemaValidationInCorrectEnumValue

{

        WindowsFeature ROLE1

        {            

               Name = "Telnet-Client"

               Ensure = "Invalid"

        }           

}

 

Compiling it will result in error:

 

PSDesiredStateConfiguration\WindowsFeature: At least one of the values 'Invalid' is not supported or valid for property 'Ensure' on class 'WindowsFeature'. Please specify only supported values: Present, Absent.

 

This allows catching most of the errors during parse and compilation time instead of delaying it till run time (configuration application).

 

DSC provides a mechanism to add new custom DSC resources. These resources should be deployed outside of $pshome module path, preferably under $env:SystemDrive\Program Files\WindowsPowerShell\Modules path. For configuration that use custom DSC resources, authoring and compilation steps need to know the additional resources that should be loaded for validation – that’s where Import-DscResource comes into play. In absence of an import mechanism, parsing and compilation steps could be very slow because they have to look up entire $PSModulePath entries to find module containing required DSC resource. Also Import-DscResource is used to import both composite and PowerShell DSC resources.

 

Import-DscResource currently supports two non-positional parameters Name and ModuleName.

 

-Name is the name of the resource to import. The name of the resource has to be the class name used when defining schema for the resource and not the friendly name. E.g.

[ClassVersion("1.1.0"),FriendlyName("Website")]

class WebsiteResource : OMI_BaseResource

{

}

In above example resource name is WebsiteResource and not the friendly name “Website”.  

 

Name can contain any numbers of resources to be imported.  If only –Name parameter is used then resources can belong to different PowerShell modules as well. e.g.

 Import-DSCResource –Name MSFT_xADDomain , MSFT_xSmbShare   

The above command will loop through all modules installed in all paths in $env:PSModulePath to find the ones containing resources whose names are specified as value for –Name parameter. Things to consider when using only the Name parameter:  

1-   It has performance implications because it is resource intensive operation. It can use lots of memory on machine depending on how many modules are installed on machine.  

2-   It will load the first resource found with given name so in case there are more than one resource with same name deployed on machine, it can end up loading different resource then the one desired.

 The recommended way is to specify –ModuleName as well as described below.  

-ModuleName is the name of the module that contains the resources to be imported.  This parameter can contain either string array of module names or modules specification object.  e.g.

Import-DSCResource –ModuleName  xActiveDirectory, xSmbShare 

Above command will import all resources defined inside modules xActiveDirectory and xSmbShare unless we specify –Name parameter as well to only load selected resources.

 

Module specification object is just a hash table. The valid members that can be added to it are ModuleName, ModuleVersion and GUID.  

 

Import-DscResource –ModuleName @{ModuleName="xActiveDirectory”},@{ModuleName=" xSmbShare"}

 

The Import-DscResource command only tries to find resources inside specific module when ModuleName parameter is specified, which solves any delays/performance issues during resource discovery. Also its lets user control which exact version of module to load when there are multiple versions of same module installed on machine.

 

 

DSC Resource Versioning 

 

DSC resources have same version as that of container Modules. Version is determined by ModuleVersion property defined in .psd1 of container module. DSC resources can also define their own .psd1 file which might have ModuleVersion defined as well, but version property is used from container module .psd1 to load resources.

 

Any updates in resources should result in update to container module version and configuration author can select which version of Resource/Module to load by using command like:

 

  Import-DscResource -ModuleName @{ModuleName="xActiveDirectory”;GUID="caedd1418493-4af3-bda0-eef11e9ca2be”;ModuleVersion="2.0"},@{ModuleName=" xSmbShare";ModuleVersion="1.0"}

 

Above command will fail if it is not able to find exact module version for each module.

 

The Module version number along with module name is included in each resource instance in output MOF generated during compilation. It looks like this:  

 

instance of MSFT_xADDomain as $MSFT_xADDomain1ref

{

            ResourceID = "[xADDomain]FirstDS";

 

            ModuleName = "xActiveDirectory"; 

 

               ModuleVersion = "2.0";

}

 

This gives the LCM information about which version of resource was used to generate the MOF. That is the version against which we validated resource properties during compilation so LCM attempts to find/load the same version at runtime. Incase same version does not exist on target node, execution behavior is different for Push vs Pull configuration modes. In case of Push mode execution fails and error is returned to user pushing the configuration. For Pull mode LCM attempts to download required module from Pull server and installs it on target node before execution, if it is unable to find that version on pull server execution fails.

 

 

Support for Wild Card operator and Partial Parameter Names

 

Import-DSCResource also supports partial parameter names

 

Import-DscResource -N MSFT_xADDomain -Mod " xActiveDirectory "

 

We can also use wildcard while specifying resource Names

 

Import-DscResource -Name * -ModuleName ="xActiveDirectory”;

 

Import-DscResource -Name MSFT*  -ModuleName ="xActiveDirectory”;

 

Wildcards are not supported for –ModuleName parameter because value can map to multiple module names and is error prone. Below command will result in error during configuration compilation.

 

Import-DscResource -Name * -ModuleName UserConfigPro*

 

Also specifying multiple values for Resource names and modules names in same command are not supported. It can have non-deterministic behavior about which resource to load from which module in case same resource exists in multiple modules. Below command will result in error during compilation as well.

 

Import-DscResource -Name UserConfigProvider*,TestLogger1 -ModuleName UserConfigProv,PsModuleForTestLogger

 

Fayza Sultan  

PowerShell Team

 

Leave a Comment
  • Please add 2 and 4 and type the answer here:
  • Post
  • I have question regarding resource versioning, and updating resources with Pull Server.

    I got to the point, that target nodes download the new version of resource module, even though at first I got some generic error. (see below)

    Nevertheless, the resource is there. However the old module is being cached in the Power Shell session. Why DSC is not reloading it?

    Here is step by step process that I have done:

    I have published my new custom resource, and set configurations. My target nodes successfully pulled their configurations from the PULL server along with DSC resources.

    Now, I try to update one of the resources.

    I modified following:

    - I updated ModuleVersion from 1.0 to 1.1 in cMySampleResource.psd1 file

    - In the configuration I added the ModuleVersion when importing DscResource

    Import-DscResource -ModuleName @{ModuleName="cMySampleResource";ModuleVersion="1.1"}

    (Subquestion: do I have to always specify version? would dsc pull latest if I don't)

    - I changed the class version in resource schema.mof file. I also added new property

    [ClassVersion("1.1.0.0"), FriendlyName("MySampleResource")]

    class MySampleResource : OMI_BaseResource { ...... }

    (Subquestion: do I have to update class version if I don't have new properties?)

    - Then I zipped the module adding 1.1

    cMySampleResource_1.1.zip

    - Generated New-DscChecksum on that file and copied these two files in DscService/Modules

    -----------

    Then I invoked the pull on the target node. Firstly I got the following error.

    Invoke-CimMethod : A generic exception occured during the processing of zip files downloaded by Download Manager WebDownloadManager.

    I invoked Pull again - and error was not there.

    I checked the module directory on the target node, and saw new files unzipped along with old folder with _tmp addition.

    In case I changed some [Write] properties I may get following errors:

    The command Test-TargetResource of the PS module MySampleResource does not implement the write property Context mentioned in the corresponding MOF schema file C:\Program Files\WindowsPowerShell\Modules\cGRFacts\DscResources\MySampleResource\MySampleResource.schema.mof. All write paramenters

    mentioned in the schema file must be implemented by the command Test-TargetResource.

    Essentially Test-DscConfiguaration and Get-DscConfiguration, are still using old module. Until I restarted process hosting DSC Engine. (as described above). DSC should be able to reload that module. I don't have WMF 5.0 yet - so I don't use Debug flag. Nevertheless this is not debug situation. I need to be able to update the resources. This week I will be testing DSC on the larger scale of nodes - about 50-100 nodes. But I am hesitating till I resolve that issue. I would be grateful for assist, and pointing me to the right solution. I can't be restarting manually processes on so many nodes.

  • Any update about my question regarding updating resources from previous post? It is indirectly related to Import-DscResource. If only I could force dsc to always load the latest module, that would be great. The process of updating resources is not well explained anywhere unfortunately - and it is essential if we produce/maintain a lot of new resources. Thanks for any insight

Page 1 of 1 (2 items)