Summary: Guest blogger and Microsoft PFE, Jason Walker, talks about the anatomy of a Windows PowerShell DSC resource.
Microsoft Scripting Guy, Ed Wilson, is here. Today is Part 1 of a two-part series written by Microsoft PFE and Honorary Scripting Guy, Jason Walker.
The majority of my "PowerShelling" lately has been around Desired State Configuration (DSC). However, the gotcha with DSC is if there isn’t a resource for the configuration area that you want to configure, you can’t use DSC for that task.
Now let’s not jump to conclusions and eliminate DSC as a solution. If you can write a Windows PowerShell script, you can write a DSC resource. A DSC resource is a Windows PowerShell module with one addition. A DSC resource has a MOF file that defines each of the configurable properties. It’s that simple.
When designing a resource (see Writing a custom DSC resource with MOF), it should be written to configure one thing—and one thing only. In most cases, a resource should correlate to a cmdlet noun. For example, if you run Get-Command *ADUser you will find the following cmdlets:
PS C:\Windows\system32> Get-Command *ADUser
CommandType Name
----------- ----
Cmdlet Get-ADUser
Cmdlet New-ADUser
Cmdlet Remove-ADUser
Cmdlet Set-ADUser
These cmdlets enable you to create a user (New-ADUser), modify the attributes of a user (Set-ADUser), delete a user (Remove-ADUser), and find a user and return information about that user (Get-ADUser). Now if I wanted to put that user in a specific group, I would have to use a cmdlet that has a different noun (Add-ADGroupMember). Therefore, if I was going to use DSC to create a user and place that user in a specific group, I would need two resources (xADUser and xADGroupMember).
To demonstrate the ease of writing a resource, I will walk you through creating a resource to create a file or a folder. I will call the resource xItem because I will be using the New-Item and Get-Item cmdlets in my resource. In addition, this resource will live in the xFileFolder module.
By reviewing the examples in the New-Item Help file, we can determine that the resource will need the following properties: Name, ItemType, and Path. (I recommend that when you use native cmdlets in your resources, you make the resource parameter names match the parameter names of the cmdlets that are used in your resource. I will expand on this later.) Because I want the resource to be able to remove a file or folder if needed, I will also need the Ensure property.
Now I have everything I need to create the schema (MOF file) for the resource. I will use the xDscResourceDesigner module for this. The xDscResourceDesigner module simplifies creating the foundation for a DSC resource. The module will create the folder structure for the resource, the MOF file, and a template of the psm1 file. For more instructions about using the xDscResourceDesigner module and the details on the MOF file, see the following blog by the Windows PowerShell team: Resource Designer Tool – A walkthrough writing a DSC resource. Here is my code:
In my example, I defined each property by using the New-xDscResourceProperty function. First, I have to define a property that will have the Key attribute. The key must be unique among like resources. Because I can’t have two files with the same name and the same path, I’m going to use the path as the key.
You can also use multiple properties for the key when needed. For example, a resource to create DNS A records would need to have the host name and IP address as key properties because you can have two DNS A records with the same host name (such as in a DNS round-robin scenario), but the IP addresses must be different.
When each property is defined, I pass them to the New-xDscResource function. When the New-xDscResource function is called, I also specify the module name, resource name, and where I want the resource to live. I left out giving the properties a description so the code would fit on one page. The description is optional, but it’s nice if it’s there, and I recommend you always include it.
Now back to the code. When running my example, the xDscResourceDesigner creates the needed folder structure, schema.mof, and MSFT_xItem.psm1 file (which is where the Windows PowerShell lives). This is shown here:
That is enough instruction for one day. Tomorrow I will explain how to write the Get, Set, and Test-Target resource functions.
~Jason
Thank you, Jason. This is great information.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy