Create a PowerShell DSC resource with the xDSCResourceDesigner module

The xDSCResourceDesigner module helps create your own PowerShell Desired State Configuration (DSC) resource. In this post, I will give an example of how to use xDSCResourceDesigner and show you how to create environment variables with PowerShell DSC.

DSC resources contain the code that keeps the configuration targets in the desired state. There are a lot of different resources included in the PowerShell DSC installation package and even more provided for free by the community. But what if from all this variety you couldn't find the one for your task? In that case, you have to create the resource yourself, which is where the xDSCResourceDesigner module comes in. The module simplifies the creation of your own DSC resources.

Finding the xDSCResourceDesigner module

Finding the xDSCResourceDesigner module

Now let's take a look what cmdlets we have inside that module:

Listing the available cmdlets in the module

Listing the available cmdlets in the module

To create a new resource, we have to define its properties first, which we can do with the New-xDSCResourceProperty cmdlet. In my example, I show you how to manage environment variables with the help of a DSC resource. To define an environment variable, I'll need three properties: name, type and value. To make things a little bit easier, I store these properties in a hash table:

Every property has a name, a type, and an attribute. The key attribute works as the unique identifier for the property. Next, I use the New-xDSCResource cmdlet to create my resource. Let's take a look first at the New-xDSCResource cmdlet:

Displaying help for the New DSCResource cmdlet

Displaying help for the New DSCResource cmdlet

As you can see from the help page, we have to specify the Name, the Property, and the Path to the folder where we are going to save the resource file, as well as a module name because we are essentially creating a new module here. I personally would also add the Friendly name.

As in the first example, I'm using a hash table to put all these together:

And now I'm ready to run the New-DSCResource cmdlet:

Creating a new DSC resource with New DSCResource

Creating a new DSC resource with New DSCResource

As you can see in the screenshot above, a few folders were created. Let's take a look inside. The xEnvarCheck.psd1 file contains the auto generated standard module manifest, which is not interesting and doesn't require any attention.

The module manifest

The module manifest

The other files are a bit more interesting. For example, AC_xEnvVar.psm1 is the skeleton of our future resource. The xDSCResourceDesigner module did a good job and prepared it for us:

The three functions Get, Set, and Test, which are required for any DSC resource, are already prepared for us. The third file, AC_xEnvVar.schema.mof, is the pre-generated Microsoft Operation Framework (MOF) file.

The schema

The schema

At this point, I realize that I forgot to add a crucial parameter in the beginning. I have to specify the Ensure switch, because I need to either add or remove the variable. So, do I need to start from scratch? Fortunately, no, since there is an Update-xDSCResource cmdlet. I just have to add the Ensure property to my hash table and then run the Update-xDSCResource.

This will change the MOF file, but the AC_xEnvVar.psm1 file will remain unchanged. Thus, I have to edit this file myself. However, this is not a big issue because I have to modify the pre-generated functions anyway.

I put a little effort in and wrote functions to add and remove environment variables. This script looks long, but it is really simple. The Get-TargetResource function accepts three parameters which are pretty self-explanatory. Then it just gets the information about the variable using the GetEnvironmentVariable .net function and returns a hash table.

The Set-TargetResource cmdlet firstly validates the desired state and then either removes or adds the environment variable. The Test-TargetResource cmdlet, on the other hand, only checks if the resource is in the desired state and doesn't changing anything.

Let's try to create a configuration using this resource:

Then, we can apply this configuration with the Start-DscConfiguration cmdlet:

Applying the configuration with Start DscConfiguration

Applying the configuration with Start DscConfiguration

And here is our environment variable:

Displaying the environment variable in the Control Panel

Displaying the environment variable in the Control Panel

Creating DCS resources is really easy with the Resource Designer Module, isn't it?

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

1+
avatar
Share
2 Comments
  1. @alex-chaika

    Thanks for your very good article.
    Just useful for me today.

    However I have a question: what is the difference between the different attribute values( Key, Read, Write, Required)?

    0

    • Finally found something:

      At least one parameter in the schema has to be marked as [key]
      [read] property does not coexist together with any of: [required], [key], [write]
      If multiple qualifiers are specified except [read], then [key] takes precedence
      If [write] and [required] are specified, then [required] takes precedence

      https://docs.microsoft.com/en-us/powershell/dsc/resources/resourceauthoringchecklist

      However, it doesn't explain the purpose of the Read attribute.
      I can imagine that Required is also Write at the same time... But why would we want to use the Read attribute?

      0

Leave a reply

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2020

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account