Creating a DSC Configuration Template

During the recent TechEd in Houston, there was a lot of talk and excitement about Desired State Configuration, or DSC. I'm not going to cover DSC itself here but rather address a minor issue for those of you just getting started. When you build a configuration, how can your figure out what resource settings to use?

To start with, you can look use the Get-DSCResource cmdlet which will list all resources in the default locations.

The properties for each resource are also there, although you have to dig a little.

get-dscresource registry | Select -expand properties

From the screen shot you can see which properties are mandatory and the possible values for the rest. The Get-DSCResource cmdlet will even take this a step further and show you the complete syntax on how to use a particular resource.

get-dscresource registry -Syntax

To build a configuration, you can copy, paste and edit. But I wanted more, as I often do when it comes to things PowerShell. So I wrote a function called New-DSCConfigurationTemplate that will generate a complete configuration with as many resources as you have available.

#requires -version 4.0
#requires -module PSDesiredStateConfiguration

Function New-DSCConfigurationTemplate {

<#
.SYNOPSIS
Create a DSC configuration template
.DESCRIPTION
This command will create a DSC configuration template using any of the available DSC resources on the local computer. By default, it will create a configuration for all resources. The template will show all possible values for each set of resource properties. Mandatory property names are prefaced with a * , which you must delete.

If you don't specify a file path or to use the ISE, then the configuration will be written to the pipeline.
.PARAMETER Name
The name of the DSC resource
.PARAMETER UseISE
Open the template in the PowerShell ISE. You must be running this command in ISE or specify a path.
.PARAMETER Path
Save the file to the specified path. You can also opt to open the file in the ISE after creating it.
.EXAMPLE
PS C:\> New-DSCConfigurationTemplate File,Service,Registry -path d:\configs\template1.ps1 -useIse

Create a DSC configuration template for resources File, Service and Registry. The example code will save it to a file and then open the file in the PowerShell ISE.
.EXAMPLE
PS C:\> New-DSCConfigurationTemplate -useISE

Assuming this command is run in the ISE, it will create a configuration template using all DSC resources on the local computer and open it in the ISE as an untitled and unsaved file.
.LINK
Get-DSSResource
.LINK
https://jdhitsolutions.com/blog/2014/05/creating-a-dsc-configuration-template
.NOTES
Last Updated: May 17, 2014
Version     : 0.9
Author      : @JeffHicks

Learn more:
 PowerShell in Depth: An Administrator's Guide (http://www.manning.com/jones2/)
 PowerShell Deep Dives (http://manning.com/hicks/)
 Learn PowerShell in a Month of Lunches (http://manning.com/jones3/)
 Learn PowerShell Toolmaking in a Month of Lunches (http://manning.com/jones4/)
 
"Those who forget to script are doomed to repeat their work."

  ****************************************************************
  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
  ****************************************************************
#>

[cmdletbinding()]
Param(
[parameter(Position=0,ValueFromPipeline=$True)]
[ValidateNotNullorEmpty()]
[string[]]$Name="*",
[switch]$UseISE,
[string]$Path
)

Begin {
    Write-Verbose -Message "Starting $($MyInvocation.Mycommand)"  
    $template=@"
#requires -version 4.0

Configuration MyDSCTemplate {

#Settings with a * are mandatory. Delete the *.
#edit and delete resource properties as necessary

Node COMPUTERNAME {

"@

} #begin

Process {


foreach ($item in $name) {
Write-Verbose "Getting resource $item "
$resources = Get-DscResource -Name $item

    foreach ($resource in $resources) {
[string[]]$entry = "`n$($resource.name) <ResourceID> {`n"

    Write-Verbose "Creating resource entry for $($resource.name)"
    $entry+=  foreach ($item in $resource.Properties) {
     if ($item.IsMandatory) {
       $name="*$($item.name)"
     }
     else {
     $name = $item.name
     }

     if ($item.PropertyType -eq '[bool]') {
       $possibleValues = "`$True | `$False"
     }
    elseif ($item.values) {
      $possibleValues = "'$($item.Values -join "' | '")'"
     }
    else {
      $possibleValues=$item.PropertyType
    } 
    "$name = $($possibleValues)`n"

    } #foreach
 $entry+="} #end $($resource.name) resource`n`n"
 #add the resource listing to the template
 $template+=$entry
}
} #foreach item in $name

} #process

End {

Write-Verbose "closing template"
$template+=@"
 } #close node

} #close configuration

"@

if ($path) {
Write-Verbose "Saving template to $path"
  Try {
    $template | Out-File -FilePath $path -ErrorAction Stop
    if ($UseISE) {
        Write-Verbose "Opening $path in the ISE"
        ise $path
    }
  }
  Catch {
    Throw $_
  }
}
elseif ($UseISE -And ($host.name -match "PowerShell ISE")) {
    Write-Verbose "Creating a new ISE PowerShell tab"
    $new = $psise.CurrentPowerShellTab.Files.Add()
    Write-Verbose "Inserting template into a new tab"
    $new.Editor.InsertText($template)
}
elseif ($UseISE -And ($host.name -notmatch "PowerShell ISE")) {    
        Write-Warning "Could not open template in the ISE. Are you in it? Otherwise, specify a path or run this in the ISE."
  }
else {
    Write-Verbose "Writing template to the pipeline"
    $template
}

    #All finished
    Write-Verbose -Message "Ending $($MyInvocation.Mycommand)"
} #end

} #end function

The function will create a configuration template with whatever resources you specify.

By default the function writes to the pipeline, but you can specify a file name and even open the file in the ISE. Here's how to create a single template for all DSC resources on your computer.

New-DSCConfigurationTemplate -Path c:\scripts\DSCConfigTemplate.ps1 -UseISE

Mandatory properties are preceded by a *, which you need to delete. Properties have all of the possible values or at the very least what type of value you need to enter. Simply delete what you don't want and in no time you have a complete DSC configuration! Don't forget to substitute a name in for without the <>.

I wrote this with the assumption that I could run this once to create a template, then copy and paste what I need into a new configuration. Another option would be to create ISE snippets for these resources.

Personally, anything that saves me typing is a great help. I hope you'll let me know what you think.

---

---