• PowerShell Desired State Configuration – Part 1: The Basics
• PowerShell Desired State Configuration – Part 2: LCM and Push Management Model
• PowerShell Desired State Configuration – Part 3: Pull Mode
• PowerShell Desired State Configuration – Part 4: Automating and Monitoring Pull Mode
• PowerShell Desired State Configuration – Part 5: DSC Resources

Desired State Configuration (DSC) allows us to simply define what needs to be configured on one or more machines. To achieve this, DSC is based on the concept of ‘resource’. A DSC ‘resource’ is used in a DSC configuration to perform an action on a DSC node. In effect, a resource corresponds to what can be configured on a node. We mentioned in the first article of this series that there are several resources provided by default with DSC. These built-in resources are called “official” resources and can be listed using the following command:

Official resources are added to each new version of DSC after being tested by the PowerShell team to eliminate possible bugs. However, these resources are likely to be too limited for your mundane requirements. Desired State Configuration has been designed to be extendable, and so there are two other types of resources that can be used. This allows us to create resources that do what we need without having to wait for the next versions of DSC, and we can manually add DSC resources via the ‘Resource Kits’. There are several types of kits.

• Official Resource Kits: We just mentioned them – they are resources that are tested and validated by the PowerShell team and distributed with DSC. Some examples are: Group, Package, Registry, …
• Experimental Resource Kits: As the name suggests, these are experimental resources and therefore are untested and not validated. These resources are mainly obtained via the ‘PowerShell Gallery’ website which is the central repository for PowerShell content or via the ‘PowerShell Git’. So be careful when using them, especially if you use them in a production environment. These resources have a specific naming convention because their name must begin with an “X”. Some examples are: xAzure, xHyper-V, xSQLServer, …
• Community Resource Kits: It is noticeable that the DSC community is growing steadily and more and more content is made available by contributors. Anyone can contribute by creating their own DSC resources. They can be obtained on forums and the Git repository. Perhaps even you or your colleagues could provide them. As we shall see in this chapter, anyone can develop their own resource very easily. These resources also have a specific naming convention in that their name must begin with the letter “C”. Some examples are: cFailoverCluster, cSystemCenterManagement, …

I recommend that you regularly follow the PowerShell team blog in order to stay informed of the release of the latest DSC resources.

What is a DSC Resource?

A DSC resource is similar to a Windows PowerShell module. This type of module regroups one or more resources and contains several elements:

• The scheme: This is the definition of configurable properties, held in a MOF file named ‘.schema.mof’
• The implementation: This is the code that configures the node via the DSC configuration. It is held in a script module with the extension of .psm1. There can also be the .psd1 file which contains the manifest, but it is not mandatory.

An example is worth a thousand words – so let us analyze the “xHyper-V” resource:

Module Name	Version	Sub-Folders or Files	DSCResources	DSC Resource Files
xHyper-V
	3.4.0.0
		DSCResources
			xVHD
				xVHD.psm1
				xVHD.schema.mof

• Module Name: This is the official name of the module from which you can search.
• Version: This is the version of the module. It allows you to identify new versions before using the “Update-Module” cmdlet to install the new version.
• Sub-Folders or Files: This directory contains at least a “DSCResources” subdirectory, but probably more containing such files as examples, the license, the readme file or the documentation
• DSCResources: This directory is the most interesting because it contains the PowerShell scripts that will be used to configure nodes. It is a good idea to indulge your natural curiosity by opening them up to better understand the resource.

Installing a DSC Resource

Now to practice. It requires no special skills to Install a DSC resource. It is very simple. Basically, you just copy and paste files into a folder. To know where to copy the resources, use the following command:

The first step is to search our module, and there are several methods for doing this. WMF 5.0 provides the “Find-Module” cmdlet which is part of the “PowerShellGet” module. This will search directly in the modules available on the site ‘PowerShell Gallery’ site:

You can also list the modules that contain the tag “DSCResourceKit”.

Finally, the “Find-DSCResource” cmdlet can also be used. Don’t confuse this with the ‘Get-DSCResources’ cmdlet that lists the resources that are present locally on the machine.

A manual search on the PowerShell Gallery website will also allow you to search for resources:

Figure 1 – PowerShell Gallery website

To install the module, you will need administrator privileges on your workstation. Run the following command to install, by example, the xSQLServer module:

The module is copied to the $env:ProgramFiles\WindowsPowerShell\Modules. If you do not have administrator account, then you must add the following parameter: “-Scope CurrentUser”. The module will be installed into the following directory: C:\Users\%USERNAME%\Documents\WindowsPowerShell\

If you have a previous version of the module, then you can update it via the “Update-Module” cmdlet.

Remember that, in the case of push mode, the resource must be present on each node that you want to configure. This is in contrast to the pull mode, where the resource must be present only on the Pull Server.

Using a DSC Resource

Before you use a DSC resource, you need to understand how it works and know the available properties. Let us start by the Get-DSCResource cmdlet which will list DSC Resources:

The following configuration use the “Package” resource in the push mode:

• The ensure parameter installs or uninstalls the package.
• The path parameter indicates the location of the 7Zip executable.
• The ProductID allows to detect if the package is installed correctly or not.

To obtain this ProductID, the most common method is to manually install the package and then get the ID in the registry:

As a sysadmin, I use SCCM to manage all my machines. So my tip is to use SCCM to easily get the ProductID from the application deployment tab. This avoids me from unnecessarily installing the software on a machine.

Figure 2 – SCCM Application

Furthermore, I advise you to use shared folders to centralize your packages and so to easily access them from your nodes.

A reboot may be required after installing or uninstalling (Ensure = Absent).

The installation time is extremely fast! Installing 7Zip is done in 2.2 seconds and the uninstallation in 8 seconds.

Now, let’s look at an example of the experimental resource. We will create a VHD file with the xHyper-V resource:

This example allows me to focus on an important line:

Import-DscResource could be mistaken for a PowerShell cmdlet, but it is actually a keyword that can be used only in a DSC configuration. It allows us to load the xHyper-V resources needed to configure the node.

Creating a DSC Resource

For specific needs, you will probably need to create your own resources. Writing a DSC resource is carried out with the aid of the xDscResourceDesigner module that provides several cmdlets in order to simplify the process.

Let us view the available cmdlets in this module:

We will begin by creating our resource properties via the New-xDscResourceProperty cmdlet:

We can now create our resource by integrating the above properties:

We’ll now execute these lines. Below is the output:

The tree view of your module is created automatically by PowerShell and some files are now present.

The most important is the .psm1 file which contains the following three functions that you must implement:

• Function Get-TargetResource { # Gather information about the task }
• Function Set-TargetResource { # Apply what we want to do }
• Function Test-TargetResource { # Test the system }
• Export the module at the end of the file: Export-ModuleMember -Function * -TargetResource

Finally, let us check that our module is available on the machine:

And also the DSC resource:

Now you can run a DSC configuration with your own DSC resource! Don’t forget to load your module:

Conclusion

With this series of articles now completed, I advise you, as usual, to take the examples and adapt them to your network environment to become familiar with this new DSC concept.

We saw in this series the DSC resource that is the backbone of Desired State Configuration. We have imported new resources but also created customs resources to meet specific needs.

Before writing your own resources, I suggest that you first browse the experimental resources as there are many. Keep in mind that the DSC mode you choose will have only one impact on the resources that you use:

• In Push mode, it will be mandatory to deploy the resources on the nodes that must be configured.
• In Pull mode, the resources must only be on the Pull server so that nodes can download them.

DSC is a very powerful tool but requires some practice to use it properly. Thus the verbose mode will allow you to effectively analyze possible configuration deployment errors.