Recently I’ve been getting quite a few inquiries about setting up modules for PowerShell. So, I’ve decided to write about it. Below you will read about how I go about creating a new PowerShell module.
Included in this Post:
- Overview of Scaffolding
- Plaster
- My Module Template
- Local testing files
- AsBuiltReport
- Run through an example
What is Scaffolding?
In it’s simplist form, its a common directory and file structure to help you build a PowerShell module. The directory structure helps separate build tools from the actual module/function files. There are two fairly popular scaffolding tools for PowerShell:
Plaster is the tool that I use to create new module scaffolding. I have found it easy to use and when I was first writing modules, there were quite a few blogs that did really well at helping me understand the process and tools. This was probably the most helpful link that I could find using Plaster. -> Kevin Marquette
My Module Template
Of course nothing in the PowerShell world is complete unless you have put your own twist or spin on it! Over time I have created my own Plaster template that I use to generate my own Modules. While the changes are small, it helps me rapidly generate all of the directories I desire to have in a module. My Module template can be found on GitHub.
My additions to the standard Plaster template are the following:
- BuildSettings.ps1
- Separate file to add any additional build settings. It keeps things clean IMO.
- tests\RunPester.ps1
- Allows developer to run Pester Tests on the full module on local box.
- tests\RunPSScriptAnalyzer.ps1
- Allows developer to run PSScriptAnalyzer on the full module on local box.
- tests\RunPSCodeHealth.ps1
- Allows developer to run PSCodeHealth on the full module on local box.
- Example Function and Unit test files
- Disable-SSLValidation.ps1
- Example Function (Located in Public and Private folders)
- Disable-SSLValidation.Tests.ps1
- Example Unit test file (Located in Public and Private folders)
- Disable-SSLValidation.ps1
AsBuiltReport
I’ve been talking with the guys who are working on the core functionality of the AsBuiltReport PowerShell Modules. They’ve asked me to scaffold out two of their repositories to help create an automated build pipeline for their modules. So lets walk through the process to show you how simple it can be.
- Install the Plaster Module
- Download my Plaster FullModule Template
- Run Plaster!
Step 1 – Is fairly easy, open a PowerShell console and run:
Install-Module Plaster<br data-mce-bogus="1">
Step 2 – Visit the link above and either Fork or clone the repository to your local machine.
Step 3 – Run Plaster, update the paths to match your local directories:
Invoke-Plaster -TemplatePath C:\OPEN_PROJECTS\Invoke-Automation\Powershell\Plaster\FullModuleTemplate\ -DestinationPath .\AsBuiltReport\
Then follow the prompts to create your new Module… It’s that simple!
================================================== Name of your module (AsBuiltReport): AsBuiltReport.Cohesity.DataPlatform Brief description on this module: AsBuiltReport.Cohesity.DataPlatform Github repo name for this module (AsBuiltReport.Cohesity.DataPlatform): GitHub username (AsBuiltReport): Module author's' name (AsBuiltReport): Initial module version (0.0.1): Destination path: C:\temp\PLASTERSHIT\AsBuiltReport\ Creating folder structure Create docs\images\ Create tests\ Create spec\ Create .vscode\ Create AsBuiltReport.Cohesity.DataPlatform\public\ Create AsBuiltReport.Cohesity.DataPlatform\private\ Create AsBuiltReport.Cohesity.DataPlatform\classes\ Create AsBuiltReport.Cohesity.DataPlatform\data\ Create tests\public\ Create tests\private\ Deploying files Create appveyor.yml Create build.ps1 Create BuildSettings.ps1 Create deploy.PSDeploy.ps1 Create .gitignore Create .vscode\settings.json Create spec\module.Steps.ps1 Create mkdocs.yml Create PITCHME.md Create readme.md Create LICENSE Create module.build.ps1 Create AsBuiltReport.Cohesity.DataPlatform\public\Disable-SSLValidation.ps1 Create AsBuiltReport.Cohesity.DataPlatform\private\Disable-SSLValidation.ps1 Create docs\about.md Create docs\acknowledgements.md Create docs\index.md Create docs\Quick-Start-Installation-and-Example.md Create tests\Project.Tests.ps1 Create tests\Help.Tests.ps1 Create tests\Feature.Tests.ps1 Create tests\Regression.Tests.ps1 Create tests\Unit.Tests.ps1 Create tests\RunPSCodeHealth.ps1 Create tests\RunPSScriptAnalyzer.ps1 Create tests\RunPester.ps1 Create tests\public\Disable-SSLValidation.Tests.ps1 Create tests\private\Disable-SSLValidation.Tests.ps1 Create spec\module.feature Create AsBuiltReport.Cohesity.DataPlatform\AsBuiltReport.Cohesity.DataPlatform.psm1 Create AsBuiltReport.Cohesity.DataPlatform\AsBuiltReport.Cohesity.DataPlatform.psd1
This will create the entire directory structure as well as replace the new module name in all of the correct places withing each of the new/copied files. See the Repository used in this example on the AsBuiltReport GitHub.
Feel free to fork/update my Plaster template, I’m always interested to see what the community can come up with.
Invoke-Automation 