{"id":1941,"date":"2013-12-05T00:57:00","date_gmt":"2013-12-05T00:57:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2013\/12\/05\/how-to-deploy-and-discover-windows-powershell-desired-state-configuration-resources\/"},"modified":"2019-02-18T13:05:27","modified_gmt":"2019-02-18T20:05:27","slug":"how-to-deploy-and-discover-windows-powershell-desired-state-configuration-resources","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/how-to-deploy-and-discover-windows-powershell-desired-state-configuration-resources\/","title":{"rendered":"How to Deploy and Discover Windows PowerShell Desired State Configuration Resources"},"content":{"rendered":"

A Windows PowerShell Desired State Configuration (DSC) resource contains a module file (*.psm1), an optional data file (*.psd1),and a *.schema.mof file. Details about what each of those files should look like, and how you can create those files using a DSC Resource Designer Tool, are discussed in <\/span>an earlier blog post<\/span><\/a>.  In this blog post, we will explore the following.<\/span><\/p>\n

\n
    \n
  1. \n
    How to deploy DSC resources to the local computer<\/span><\/div>\n<\/li>\n
  2. \n
    How to discover the resources deployed, while authoring a new configuration<\/span><\/div>\n<\/li>\n
  3. \n
    How to deploy resources to the pull server, and how the local configuration manager (LCM) locates the required resources on the pull server.<\/span><\/div>\n<\/li>\n<\/ol>\n<\/div>\n

    Deploying DSC resources to the local computer<\/span><\/h2>\n

    All DSC resources should be deployed in the following folder hierarchy:-<\/span><\/p>\n

                $env: psmodulepath<\/strong> (folder)<\/em><\/span><\/p>\n

                            |- <ModuleName> (folder)<\/em><\/span><\/em><\/span><\/p>\n

                                        |-  <ModuleName.psd1> (file,required)<\/em><\/span><\/em><\/span><\/em><\/span><\/p>\n

                                        |- DSCResources<\/strong> (folder)<\/em><\/span><\/p>\n

                                                    |- <DSCResourceName1> (folder)<\/em><\/span><\/p>\n

                                                                |- <DSCResourceName1.psd1> (file, optional)<\/em><\/span><\/p>\n

                                                                |- <DSCResourceName1.psm1> (file, required)<\/em><\/span><\/p>\n

                                                                |- <DSCResourceName1.schema.mof> (file, required)<\/em><\/span><\/p>\n

                                                    |- <DSCResourceName2>(folder)<\/em><\/span><\/p>\n

                                                                 |- <DSCResourceName2.psd1> (file, optional)<\/em><\/span><\/p>\n

                                                                 |- <DSCResourceName2.psm1> (file, required)<\/em><\/span><\/p>\n

                                                                 |- <DSCResourceName2.schema.mof> (file, required)<\/span>  <\/span><\/em>        <\/span><\/p>\n

                           <\/span><\/p>\n

    Example:  Suppose the Hyper-V team decided to add a resource named VM<\/strong> in to their existing PowerShell module under $pshome, Then the folder structure of their DSC resource would look like the following. <\/span><\/p>\n

     <\/p>\n

    C:\\Windows\\system32\\WindowsPowerShell\\v1.0\\Modules\\Hyper-V\\DSCResources\\VM\\                           <\/span>                                                          -VM.psd1(optional)                                                                                                 <\/span>                                                           -VM.psm1                                                                                                        <\/span>                                                           -VM.Schema.mof<\/span><\/p>\n

     <\/p>\n

    Usually, the environment variable $env:psmodulePath<\/strong> contains more than one path, and you can deploy DSC resources in any one of the paths. But there are some subtle differences during authoring or applying configuration to the system. Because LCM runs in System context<\/strong>, applying a configuration fails if your resources module are not in the $pshome<\/strong> or $env:ProgramFiles <\/strong>folder. The differences in the authoring experience are discussed in this post, in the Import-DSCResources section.<\/span><\/p>\n

    How to use and discover DSC resources<\/span><\/h2>\n

    The number of PowerShell modules and cmdlets are increasing in every PowerShell release, hence increasing the number of results returned by Get-Module and Get-Command.  To keep those cmdlets useful, DSC resources have been stored in a subfolder of a main PowerShell module folder. <\/span><\/p>\n

     <\/p>\n

    Because DSC Resources are not deployed directly under $env: psmodulepath<\/strong>, they cannot be discovered by running the Get-Module -List Available<\/strong> cmdlet. Get-Command for the GET\/SET\/TEST method of the resources will fail. Also, you can’t import the DSC resource with a partial name, as shown in the following examples. <\/span><\/p>\n

    Let us try to find MSFT_EnvironmentResource<\/strong>, one of the DSC resources which is shipped with PowerShell 4.0.<\/span><\/p>\n

     <\/p>\n

    Get-Module<\/span> MSFT_EnvironmentResource<\/span> –ListAvailable<\/span>   # Empty result (module not found)<\/span><\/span><\/p>\n

    Get-Command Get-TargetResource <\/span># Error: Command not found exception. <\/span><\/span><\/p>\n

    Import-Module<\/span> MSFT_EnvironmentResource<\/span> # Error: ModuleNotFound <\/span><\/span><\/p>\n

     <\/p>\n

    You can, however, import the module by using its full path, like any PowerShell module, and call its GET\/SET\/TEST methods.<\/span><\/p>\n

    Import-Module<\/span> C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\Modules\\PSDesiredStateConfiguration\\DSCResources\\MSFT_EnvironmentResource<\/span> # Works <\/span><\/span><\/p>\n

     <\/p>\n

    There are two new cmdlets that are added in PowerShell 4.0 to help discover DSC resources.<\/span><\/p>\n

     <\/p>\n

    Get-DscResource<\/span><\/strong>:<\/span><\/span><\/span> Gets all the DSC resources. You can pass a resource name list to filter the result.<\/span><\/p>\n

                        Example:-<\/span>Get-DscResource Env*ment, Windows*, Log<\/span>   <\/span>ß<\/span> Returns all the resources that match the specified criteria.<\/span><\/p>\n

    So one way to test if your resources are deployed correctly is to see if they are being discovered by Get-DscResource.<\/span><\/p>\n

     <\/p>\n

    Import-DscResource<\/span><\/strong>:<\/span><\/span>  Import-DScResource is a dynamic keyword which can only be used inside a Configuration script block. When you are authoring a new configuration, you must import the resources needed by your configuration using this cmdlet. But if your DSC resources are stored in $pshome<\/strong>, you don’t need to explicitly import them. They are automatically loaded by PowerShell.<\/span><\/p>\n

    The signature of the cmdlet is shown below. <\/span><\/p>\n

    Import-DscResource [-Name <ResourceName(s)>] [-ModuleName <ModuleName(s)>] <\/span><\/em><\/p>\n

    Name<\/strong>:  This is the DSC resource name(s) that you must import. If the module name is specified, the command searches for these DSC resources within this module; otherwise the command searches the DSC resources in all DSC resource paths. <\/span><\/p>\n

    ModuleName<\/strong>:  This is the container module name(s), or module specification(s).  If the DSC resources that are required are specified, the command will try to import only those resources from the module(s).; Otherwise, the command imports all  the DSC resources in this module.<\/span><\/p>\n

    You can specify either one or both Name and ModuleName parameters in the cmdlet. But you must explicitly pass pairs of the parameter name and its value. Positional parameters are not supported.<\/span><\/p>\n

                Import-DscResource is a second way to make sure your resources are deployed correctly.<\/span><\/p>\n

    Example:-<\/span><\/p>\n

    Configuration <\/span>MSDSCConfiguration <\/span> <\/span>{<\/span><\/p>\n

                                           <\/p>\n

    Import-DSCResource<\/span> -ModuleName<\/span> MS_DSC1<\/span> -name<\/span> Resource1, Resource2, Resource3<\/span><\/span><\/p>\n

    # Search for and imports Resource1 Resource2, and Resource3 inside the modules <\/span>MS_DSC1<\/span><\/span><\/p>\n

    Import-DSCResource<\/span> -Name<\/span> Resource1  <\/span><\/span><\/p>\n

    # Search DSC resources for Resource1 under all valid DSC resource paths, and import <\/span>the <\/span><\/p>\n

    # resource. Note that this will run slower because it has to search the resource in all the<\/span><\/p>\n

    # valid DSC resource folders.<\/span> <\/span><\/p>\n

    Import-DSCResource<\/span> -ModuleName<\/span> MS_DSC1<\/span><\/span><\/p>\n

    # Search for and import all DSC resources inside the module MS_DSC1.<\/span> <\/p>\n

      …<\/p>\n

    }<\/p>\n

    Deploying DSC resources to the pull server<\/span><\/strong><\/span><\/h2>\n

    After you configure your pull server [For details about how to configure a pull server, and how a pull client works, see <\/span>this blog post<\/span><\/a>]. DSC resources can be packaged and placed in the pull server resource repository for pull clients to download it. The folder hierarchy of the pull server DSC Resource repository should be the following.<\/span> <\/span><\/em><\/p>\n

    $env:ProgramFiles\\WindowsPowerShell\\DscService\\Modules\\  (folder)                                                                                        <\/em>ModuleName_Version.zip                                                                                                             ModuleName_Version.zip.checksum<\/strong><\/span> <\/span><\/p>\n

    When it’s unzipped, ModuleName_Version.zip<\/strong> should have the same folder structure as the local computer deployment hierarchy shown at the beginning of this blog post.<\/span><\/p>\n