Write a DSC Module

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 around a central theme. Our theme is DSC which stands for Desired State Configuration. It is a declarative platform used for configuration, deployment, and management of systems. 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

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 tool later refered to as “XOSS-Plaster-Directory”

Downloadable from here

Build and Test

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

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 by version 0.1.0, since they are pre beta and havent been approved by coding standards

Modules will be automatically created once you are creating a new composite ressource.

Creating new composite ressources

Composite ressources can easily be deployed via the invocation of
 .\New-CompositeRessource.ps1

The script will ask for the modulename, the version and the resourcename.

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 XOSSTestModuleDSC with version 0.1.0 exists under C:\Users\$env:Username\XOSSTestModuleDSC\0.1.0

In case there is no module

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

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

Enter your name: TestUser
Enter a name for the module (XOSSTestModuleDSC\0.1.0): TestModuleDescription
Destination path: C:\Users\$env:Username\XOSSTestModuleDSC\0.1.0
            Scaffold a PowerShell Module with the files required to run Pester tests.
   Create XOSSTestModuleDSC.psd1
   Create Examples\dsc_configuration.ps1
   Create test\integration\default\XOSSTestModuleDSC.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 XOSSTestModuleDSC 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\XOSSTestModuleDSC\0.1.0\DSCResources\TestResource

In case there is no resource

Creating new ressource TestResource for module XOSSTestModuleDSC
  ____  _           _
 |  _ \| | __ _ ___| |_ ___ _ __
 | |_) | |/ _` / __| __/ _ \ '__|
 |  __/| | (_| \__ \ ||  __/ |
 |_|   |_|\__,_|___/\__\___|_|
                                            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\XOSSTestModuleDSC\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 modulename and version MyDscModule_1.0.0
Version Target version of the module Using SemVer Format for versioning in Modules MyDSCModule_MAJOR.MINOR.PATCH
Ressource The name of the ressource /config part -