Internals of a Desired State Configuration (DSC) Resource

By: Shawn Melton | Comments | Related: More > Database Administration

Problem

Now that I have started learning about Desired State Configuration (DSC) I need to learn more about Resources. I understand these are used to apply the desired configuration I want, but how do I use them to build my configuration?

Solution

In the previous tip on DSC we provided a very brief overview of DSC and how you get started. In this tip, I want to go over in a bit more detail what makes up a resource. In addition to that, you need to know how to utilize them in your desired configuration. A resource exposes certain properties that allow you to code your configuration for SQL Server or many other areas of the operating system from both Microsoft and other products. In this tip we are only going to work on one specific module to keep it simple. However, understand that the process you learn in this tip works for any resource you come across.

Internals of a Resource

A resource can model many things, from unpacking an archive file to configuring a service, and many things in between. It helps to know what a resource is made up of to better understand them. It will also help when you need to troubleshoot issues around use of a resource. We mentioned in the previous tip that resources are grouped into modules. As modules we can expect to find them installed on a server or local machine under the $env:PSModulePath path. In PowerShell 4.0 and higher, this path will generally fall under C:\Program Files\WindowsPowerShell\Modules.

I am going to work with the following module: PSDscResources to start out with as a small example of how you discover the details. This module contains resources that are used for more common task in Windows. It is also worth noting that this module as stated on the GitHub repository: “is the new home of the in-box resources from PSDesiredStateConfiguration”. It does not contain all of the same ones that are built-in, but most of the more popular ones used.

You need to run the following command to install the module. [Note I am working with module version 2.8.0.0 as of this tip’s writing.]

Install-Module PSDscResources
# or if you are a safety conscience
Save-Module PSDscResources -Path <path to save module>

After you pull the module down you can do a list directory or Get-ChildItem on that path to see what files are involved:

Figure 1 - Directory listing of PSDscResources

If you open up this directory in something like Visual Studio Code it can make discovery a bit easier. I will use this to simply show a few things on how a resource is generally structured.

1. DscResources

This directory will contain the code itself for each resource grouped into the module. If you browse into the “DscResources\MSFT_Archive”:

Figure 2 - MSFT_Archive.psm1 Module

In this folder you can find the module file “MSFT_Archive.psm1”, this contains the code that “gets it done”. This will be what the LCM utilizes to making your desired configuration come true.

One thing I want to point out in the above screenshot is something you will see every resource contain. The first three functions any resource will have will be Get-TargetResource, Set-TargetResource and Test-TargetResource. You can read the help information to understand what each one is for, and reading through this will help you see how the resource works in the event you need to debug any issues with your configuration.

2. Examples

My favorite folder that you should always see with Microsoft resources. This folder is filled with various use cases for each resource, and is a great resource to see how you can build your configuration code. Majority of the examples in this resource show working with one node, the localhost.

3. Tests

Figure 3 - Expanded view of Tests directory

Every DSC resource must have a test included, if it is maintained by Microsoft. (The resources you find on the PowerShell Team’s GitHub will all have tests included.) These utilize Pester and will have a unit and integration test. I can tell you this is where you need to review the most as it will be the most common issue to debug with resource. When you build a configuration part of the process will be for the LCM to run the test to validate your configuration and make sure the properties and values you have are valid. If any of the test fail it will immediately throw an error and stop processing that configuration.

Resource Properties

A resource models a certain desired configuration so we first need to discover the properties that are available and how to use them. You will utilize Get-DscResource for this discovery. You can identify all the resources in a module by using the `-Module` parameter. In our PSDscResource module we have output like the following:

Figure 4 - Get-DscResource output of PSDscResources module

Now you may notice that the ImplementedAs column shows “PowerShell” and “Composite”. A composite resource is simply a configuration that accepts parameters.

The main thing we need to discover with a resource is what properties are available and the syntax. You can get the list of properties by simply expanding that property using the Select-Object:

# Since there is a built-in resource named Archive, make sure you specify the module name
Get-DscResource -Name Archive -Module PSDscResources | select -ExpandProperty Properties

Figure 5 - Expanding the Properties from Get-DscResource

If you have worked with functions before you likely recognize a few of the items showing in figure 5:

Destination and Path properties show as mandator/required.
Both mandatory properties accept a string input.
The Checksum and Ensure properties show set of values that are allowed, like using ValidateSet() attribute in advanced functions.
The DependsOn property accepts multiple string values.

Since we are working with an archive, it would be expected that we must provide the path to the archive file and then where we want to extract it (destination path). The other properties are all optional and would be used in various use cases based on the need.

You can view the syntax of this resource by using the -Syntax parameter as shown below:

Get-DscResource -Name Archive -Module PSDscResources -Syntax

Figure 6 - Syntax output of Archive resource

In this view, you must pay a bit more attention to find similar points as the properties view. You can see right off that “Destination” and “Path” are not wrapped in brackets. In the syntax display that is the indicator they are mandatory or required properties. The properties wrapped completely in brackets are optional.

Summary

In this tip, I wanted to provide more focus on resources. In DSC, resources are what you will work with the most in building your desired configuration code. It helps to understand and know how you find them, what files make up a resource and how to discover what can be done with it (syntax and properties). Look for future tips on using resources with your configurations and how you go about running them against target servers.

Next Steps

About the author

Shawn Melton started his IT career in 2002 and has experience working with SQL Server 2000, 2005, 2008, and 2008 R2.

This author pledges the content of this article is based on professional experience and not AI generated.

View all my tips