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.
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”.
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 | - |