Helper Function to Create a PowerShell DSC Composite Resource

  • Article

 

PowerShell Desired State Configuration (DSC)

Although I have not blogged about PowerShell Desired State Configuration (DSC) very much, it has been my sole focus for the last several months. I have been doing Introduction to PowerShell DSC talks for customers and helping them get started with their DSC needs.

imageComposite Resources

One feature of DSC is something called composite resources. These are reusable configuration scripts that can act like DSC resources.  See the PowerShell Team blog post here for the full explanation:

Reusing Existing Configuration Scripts in PowerShell Desired State Configuration

Like most people I need to try it myself before a new concept sinks in. So I went into my Azure lab and started playing with these. Right away I realized there has to be a faster way to set up a composite resource. Over on the PowerShell.org github you can find a script to do just this. But like most PowerShell enthusiasts I wanted to make my own version with a few extra bells and whistles, and that is what I am sharing with you today.

Composite Resource Structure

After reading the PowerShell team post linked above you will understand there is a specific file and folder structure required for composite resources. On your DSC configuration build server you will end up with something like this:

C:\Program Files\WindowsPowerShell\Modules\

  • contosoCompositeResources
    • contosoCompositeResources.psd1
    • contosoCompositeResources.psm1
    • DSCResources
      • contosoResourceName1
        • contosoResourceName1.psd1
          • RootModule = ‘contosoResourceName1.schema.psm1'
        • contosoResourceName1.schema.psm1
          • Configuration, no Node block
      • contosoResourceName2
        • contosoResourceName2.psd1
          • RootModule = ‘contosoResourceName2.schema.psm1'
        • contosoResourceName2.schema.psm1
          • Configuration, no Node block
      • etc.

PowerShell is really good at creating folders and files, so automating this should be a piece of cake.

Automating the Template

I wanted the following features in my solution.  Yes.  I am lazy.  I want a script to do it all for me.

  • Create the folder structure
  • Create the psd1 and schema.psm1 files
  • Supply template text with the appropriate names filled in
  • List the file structure output as confirmation
  • Open the template files in the ISE

Call the function like this:

 New-DSCCompositeResource `
    -ModuleName contosoCompositeResources `
    -ResourceName contosoBaseBuildCompositeResource

Optionally you can specify a -ModuleRoot parameter. It defaults to $Env:Program Files\WindowsPowerShell\Modules, which should be sufficient in most cases.

Run the script elevated so that it has permissions to write into $Env:Program Files\WindowsPowerShell\.

Your ISE will now show you the template for the composite resource:

 Configuration contosoBaseBuildCompositeResource {            
Param()            
            
    ### Insert composite resource code here            
    ### NOTE: Composite resources do not include a NODE block            
            
}

And your ISE will also show you a template for how to reference the composite resource in a configuration:

 ### Example configuration referencing the new composite resource            
Configuration aaaaaa {            
                
    Import-DscResource -ModuleName contosoCompositeResources            
            
    Node localhost {            
            
        contosoBaseBuildCompositeResource bbbbbb {            
            #property = value            
        }            
            
    }            
}

These files are conveniently stored in the new folder structure where you can edit them in-place.

Pro Tips

When working with composite resources here are a couple tips to keep in mind:

  • Develop a company naming convention and stick with it.
  • The resourcename.schema.psm1 file looks like a typical DSC configuration without a node block. This code should be parameterized for all of the resources it contains.
  • In your parent configuration that calls the composite resource there is no support for the DependsOn property of traditional DSC resources. This might impact your design. You can use DependsOn with your composite configurations as long as you have installed KB3000850 or WMF 5.0.
  • With any other DSC custom resource you would normally zip it up, create a checksum, and publish it to the pull server. In this case, you do not have to publish composite resources. They reference other DSC resources which are the ones that need to be published on the pull server. Composite resources are only used when you generate the configuration MOF.

Knowing these tips will save you some learning curve.

Download today’s script at the TechNet Script Gallery here.

Learn PowerShell DSC Today

Do you remember five years ago when people were telling you to start learning PowerShell? Did you? Don’t you wish you started learning PowerShell earlier? PowerShell DSC is the same way. Start learning it today before you get behind the curve. Here are a few links to get you started:

Share these links with your peers and start learning today!