How Do I Create My Own Desired State Configuration (DSC) Resource?

After working with Desired State Configuration (DSC) for a little time, you may get to the point where you consider the steps required to create your very own DSC resource. And given that you have already benefited from the community, you may want to share your work as a small thank you? And you never know, someone might actually find some tweaks that would add just a little extra to your efforts, helping you to learn new tricks and meeting new personalities.

Why Create a Desired State Configuration Resource?

In this post I am going to cover a scenario that I recently had. As I rebuilt my lab, I started to go through a few “what ifs.” What if I could possibly leverage DSC to get all these ever-so-important hotfixs for Hyper-V and clustering (that for some reason never appear in Windows Update) automatically and consistently applied on my hosts?

After a quick look around the web, it did not take long to realize that there were no DSC resources for this job, but I did happen to find quite a lot of different type scripts that set about applying hotfixes with a wide range of approaches. Yet none of them were really “perfect.”

Planning Your First DSC Resource

Before we get into the actual building of our new provider, I first wanted to take a moment and plan what it is I really want to achieve. I started with a little mock-up of what a configuration using my new resource might actually look like.

PowerShell

1

2

3

4

5

6

HotfixShortName

{

Ensure="Present"

Name="KB12312312"

SourcePath=\\Server\Share\Path\Update.msu

}

Attempting to not stray from the standard configuration templates, this turned out to be very simple. I just require an ensure property to validate whether the hotfix is going to be present or not – a unique identifier for the instance, which was very easy, as every update has a unique KB number, and lastly a path to locate the update binary for the scenarios where we will need to install the update!

Getting Creative

To assist in generating our module, we are going to leverage yet another resource, which Microsoft has kindly shared with us on the Technet Gallery called xDSCResourceDesigner. As the name suggests, this PowerShell module offers us an easy method to get started on our custom resource and will create all the necessary files, including the schema .MOF, our module definition, and the template for our actual module.

In a similar manner to our previous work, we will place our new module in our PS Modules path so that it is ready for us to import. Of course, you can also place the module in any path you wish and import the module by providing the full path to the module. For example:

Once the module is loaded, you can use the Get-Commandcommandlet to enumerate the new commands provided by the module.

Defining the Module

First we will use the command New-xDSCResourceProperty to define each of the parameters we will be using in our new module. Following the rules of DSC Resources, one of the parameters must be defined as a unique key; in this example is the Name, or our Hotfix ID.

Next, we are going to use the module to create the actual files that form the template of our new module. As I plan to share this back with the community, and also leverage the features of GIT to help maintain my code versions, I will be creating the resource in my PowerShell.org GIT repo, which we forked in the earlier post.

Starting with GIT, create a new branch in the repository. I am calling this DSCHotfix. This will allow me to track the changes I am applying in the repo, which are specific to this new resource.

PowerShell

1

2

git branch DSCHotfix

git checkout DSCHotfix

Our next step is to combine the parameters we defined earlier; using the module command New-xDSCResource we will define the name for our resource and the path to which the new resource template files will be created. Adhering to the naming conventions I will create a new module to reference all my resource modules under DSC_DamianFlynn.com and the command will also make a sub-folder specifically for this new DSC Resource.

PowerShell

1

2

3

4

5

6

$cHotfix=New-xDscResource-NameHotfix`

-Property$name,$sourcePath,$ensure`

-FriendlyName"Hotfix"`

-ModuleName"DSC_DamianFlynn.com"`

-Path"X:\PowerShell\Repos\PowerShell.org\Resources\"`

-Verbose

The optional –Verbose switch provides some feedback as the command proceeds to create the template for our new module.

Switching back to GIT, I can now add the new files to my repository branch and commit them with a comment explaining what I have just completed with the following commands.

MEMBER LOGIN:

BECOME A PETRI MEMBER:

About the Contributor

Damian is an Infrastructure Architect currently focused on cloud technologies in the converged data-center, with perspective on service management automation for repeatable processes in “Dev/Ops” scenarios, leveraging Software Defined Networks (SDN) and Microsoft’s Azure Pack.

He has a keen interest in cloud computing from both a business strategy and technical viewpoint and has presented sessions on building and managing private/hybrid clouds at a number of industry events. Damian authored the cloud chapters on two books – Microsoft Private Cloud Computing (Sybex), and Windows Server 2012 Hyper-V Installation and Configuration Guide (Sybex) — and is active in many Microsoft programs, is a Microsoft MVP, and has published a number of white papers, technical articles and webinars.