Search code examples
powershelldsc

How to import an external DSC module into PowerShell environment?

I have Windows 10 / Windows 2016 TP5 (PowerShell 5.1). I want to use a PowerShell DSC module from GitHub in my configuration, for example xTimeZone.

What shall I do to be able to reference it with Import-DSCResource?

It's the first time I try to add a module other than from an installer-based product and maybe I am missing something obvious. Isn't there a git clone-based procedure like pip or gem utilise?

I verified the value of $env:PSModulePath and it has two directories defined: C:\Users\techraf\Documents\WindowsPowerShell\Modules;C:\Windows\system32\W indowsPowerShell\v1.0\Modules.

I copied the contents of xTimeZone directory to C:\Users\techraf\Documents\WindowsPowerShell\Modules.

PowerShell does not see it. Tried to copy on different levels of the repository - all failed.

When running the example script I get:

At line:12 char:4
+    Import-DSCResource -ModuleName xTimeZone
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Could not find the module 'xTimeZone'.
At line:16 char:9
+         xTimeZone TimeZoneExample
+         ~~~~~~~~~
Undefined DSC resource 'xTimeZone'. Use Import-DSCResource to import the resource.
    + CategoryInfo          : ParserError: (:) [], ParseException
    + FullyQualifiedErrorId : ModuleNotFoundDuringParse

Per advice from the answer, after moving the module from C:\Users\techraf\Documents\WindowsPowerShell\Modules to C:\Windows\system32\W indowsPowerShell\v1.0\Modules the first error disappeared and I get only:

At line:16 char:9
+         xTimeZone TimeZoneExample
+         ~~~~~~~~~
Undefined DSC resource 'xTimeZone'. Use Import-DSCResource to import the resource.
    + CategoryInfo          : ParserError: (:) [], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : ResourceNotDefined
Solution

  • About DSC resources

    DSC resources are, in essence, specialised PowerShell modules. The resource module must export Get, Set and Test-TargetResource commands (another option is available with PowerShell 5, but out of scope in the context of xTimeZone).

    Resources are always deployed in the following structure:

    <Modules>\<ModuleName>\DSCResources\<ResourceName>

    Get-DscResource looks for "modules" inside the DSCResources folder, as a sub-folder of an existing module. If it can't see the resource you cannot use it.

    xTimeZone

    xTimeZone consists of:

    1. A PowerShell module which contains little more than a manifest and some examples.
    2. A DSC resource named xTimeZone.

    Windows PowerShell cannot find the resource unless it's correctly deployed. These instructions apply for downloading the module.

    1. Select the master branch and download the zip of the repository from: https://github.com/PowerShell/xTimeZone/tree/master
    2. Extract the zip file to a folder.
    3. Rename xTimeZone-master to xTimeZone.
    4. Copy xTimeZone to C:\Program Files\WindowsPowerShell\Modules

    5. Verify you can discover the DSCResource:

      Get-DscResource

    If, for some reason, you're having problems with Program Files\Modules, you might use:

    C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\

    However, as this area is part of the operating systems files it's a lower preference.

    Configuration

    Once you can discover the resource, you need to import it into each Configuration element in which you wish to use it.

    Configuration SomeConfiguration {
    Import-DscResource -ModuleName xTimeZone

    # Nodes statement follows
}