Write your own DSC Modules

This topic explains how to create DSC Modules and Resources for Windows with the help of Plaster.

Getting Started

PowerShell modules allow you to combine multiple scripts to simplify code management, accessibility and sharing. In simplest terms, a module is just a grouping of functions and code. Plaster is a scaffolding engine for PowerShell. It can be used to create a single file such as a DSC resource script file. Or it can be used to scaffold a set of related files and directories such as the files required for a PowerShell module with Pester tests.

Prerequisites

Open your PowerShell and enter the following command:

Install-Module Plaster -Scope CurrentUser

Installing DSC

PowerShell Desired State Configuration is included in Windows and updated through Windows Management Framework. The latest version is Windows Management Framework 5.1. https://www.microsoft.com/en-us/download/details.aspx?id=54616

With the release of PowerShell 7.0 the PSDesiredStateConfiguration module is not longer included in the PowerShell package. To install PSDesiredStateConfiguration 2.0.5 from the PowerShell Gallery run:

Install-Module -Name PSDesiredStateConfiguration -Repository PSGallery -MaximumVersion 2.99
Possible notifications in PowerShell:
> Nuget provider is required to continue
> PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories. The Nuget provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or 'C:\Users\$env:UserName\Appdata\Local\PackageMangaement\ProviderAssemblies'. You can also install the NuGet provider by running 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install and import the NuGet provider now?
> [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"):
>> Press "Y" and move on.
> Untrusted repository
> You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running he Set-PSRepository cmdlet. Are you sure you want to install the modules from 'PSGallery'?
> [Y] Yes    [A] Yes to All    [N] No    [L] No to All    [S] Suspend    [?] Help (default is "N"):
>> Press "A" and move on.

Software dependencies

A custom Plaster template later referred to as “XOAP-Plaster-Template”

Downloadable from here

Build and Test

Either open the “XOAP-Plaster-Template”, press “File” in your File Explorer and run “Open Windows PowerShell” or start your PowerShell yourself and navigate into the “XOAP-Plaster-Template”.

Creating new modules

Strictly advised Guidelines:

  • Only alphanumeric characters a-z, A-Z and numbers
  • Pascal case (first letter capitalized next combined word letter in capital) i.e. Get-Item would be GetItem,etc. Bad: test_Function Good: TestFunction
  • Small module configuration packages, if the package gets too big - separate it!
  • New Modules will begin with version 0.1.0, since they are pre beta and haven`t been approved by coding standards

Creating new composite resources

Composite resources can easily be deployed via the invocation of:

 .\New-CompositeRessource.ps1

The script will ask for the module name, the version and the resource name.

Prompt after invocation without parameters

Module: TestModule
Version: 0.1.0
Ressource: TestResource
You can also invoke the script with parameters
 .\New-CompositeRessource.ps1 -Module TestModule -Version 1.0.0 -Ressource TestResource

The script will continue with:

Checking if module XOAPTestModuleDSC with version 0.1.0 exists under C:\Users\$env:Username\XOAPTestModuleDSC\0.1.0

In case there is no module

WARNING: Module XOAPTestModuleDSC with version does not exist. Creating new module. Please provide missing data.
  ____  _           _
 |  _ \| | __ _ ___| |_ ___ _ __
 | |_) | |/ _` / __| __/ _ \ '__|
 |  __/| | (_| \__ \ ||  __/ |
 |_|   |_|\__,_|___/\__\___|_|
                                            v1.1.3
==================================================

The script will ask for the author name and a description for the module.

Enter your name: TestUser
Enter a name for the module (XOAPTestModuleDSC\0.1.0): TestModuleDescription
Destination path: C:\Users\$env:Username\XOAPTestModuleDSC\0.1.0
            Scaffold a PowerShell Module with the files required to run Pester tests.
   Create XOAPTestModuleDSC.psd1
   Create Examples\dsc_configuration.ps1
   Create test\integration\default\XOAPTestModuleDSC.Tests.ps1
   Create .gitignore
   Create README.md
   Create DSCResources\.dummy

In case there is an existing module with that name the script will prompt

Module XOAPTestModuleDSC with version 0.1.0 already exists. Continuing.

Afterwards the script will continue with the creation of the resource.

Going to check if ressource TestResource exists under C:\Users\$env:UserName\XOAPTestModuleDSC\0.1.0\DSCResources\TestResource

In case there is no resource

Creating new ressource TestResource for module XOAPTestModuleDSC
  ____  _           _
 |  _ \| | __ _ ___| |_ ___ _ __
 | |_) | |/ _` / __| __/ _ \ '__|
 |  __/| | (_| \__ \ ||  __/ |
 |_|   |_|\__,_|___/\__\___|_|
                                            v1.1.3
==================================================

The script will ask for the authorname and a description for the resource.

Enter your name: TestUser
Enter a description for the module (TestResource): TestResourceDesc
Destination path: C:\Users\$env:Username\XOAPTestModuleDSC\0.1.0\DSCResources\TestResource
Creating new module manifest for TestResource
   Create TestResource.psd1
Copying schema template
   Create TestResource.schema.psm1

In case there is an existing resource the script will throw an error.

Polishing

Every resource gets a PowerShell header template but you still have to adjust the content of it so it fits your resource.


The parameter list is as followed:

Parameter Description Note Example
Module Name of the outer module part Only one underscore is allowed and it has to be between module name and version MyDscModule_1.0.0
Version Target version of the module Using SemVer Format for versioning in Modules MyDSCModule_MAJOR.MINOR.PATCH
Resource The name of the resource /config part -