PSScaffold – PowerShell module projects and pipelines

Karl WalleniusAzureKommentera

PowerShell Logo

This blog post is not so much about Azure and the Cloud, but more about some fundamentals regarding structuring and deploying your own PowerShell modules.
When working with Azure or a Windows infrastructure, you’ll run into a situation when you realize you’ll need your own set of tools, scripts and modules. You’ll soon also realize that you want to have them easily packaged and distributed within your team and/or to your customers.

For this purpose we have created PSScaffold. It’s a toolkit containing functions to build the necessary directory structure, module manifest
and other files that are needed for a complete PowerShell module (and build pipeline if that is wanted as well).

For some guidance on how to create your own PowerShell module repository to be used with one of the deploy functions, see this blog post I wrote on the subject.

Additional information

Before I go deeper into the module and it’s functon I will highlight a couple of sources that contain good information.

Rambling Cookie Monster (Warren F) has a great blog post about what files and directories a module should contain. His design
is incorporated and scaffolded by our module. A great read to understand more about the ifs, buts and whys. Check it out here.

Michael Willis has a blog post that also covers the same directory structure and files as mentioned above. He also gives a splendid example of how to prepare the build pipeline for a project. He also describes how to run unit tests and deployment with a task runner (for PowerShell a good task runner is Invoke-Build). Check it out here.

Last but not least, powershellmagazine.com has a great article on how to get started with unit testing with Pester. I really recommend this since unit testing your code will let you avoid some common headache inducing manual tests.

PSScaffold

What’s the purpose and why? The purpose of this module is to let you easily get started with a PowerShell module, and not spend time creating directories and help files manually every time you begin a new project.

Just enter a command, and all that is done for you. A quick fix on the projects setting file will prepare the module to be deployed to a PowerShell repository of your choosing.

Getting the module

To get the module:

Install-Module -Name PSScaffold

Or download the project from it’s GitHub repository.

Install the dependencies:
Install-Module InvokeBuild
Install-Module PSScriptAnalyzer

Pester is usually included in newer versions of PowerShell.

Using the module

To use the module:

Import-Module PSScaffold

I will give a short example on how the process of creating a module, publishing it and deploying it might look. For more usage guidance, either use Get-Help <command> or check out the usage instructions here.

  1. New-PSModule -Name AzureToolkit -Author 'Karl' -Description 'A Toolkit for Azure usage and automation' -BuildPipeline
    This creates the entire directory structure and the needed files for the project.
  2. cd AzureToolkit; New-PSFunction -Name Get-AzureVMStatus -Scope Public -PesterTest
    This will create a function within the Public subdirectory. In the Tests\Public folder there will be a prepeared test file for Pester for the function.
  3. Write code, create more functions, test it.
  4. Modify the file AzureToolkit.settings.ps1 to specify the correct build and deploy settings for your module. You’ll need to modify the Publish task in AzureToolkit.build.ps1 to match the target repository type.
  5. Invoke-Build -Task Clean
    This will download PSScriptAnalyzer to analyze your code in future tasks. It also clears out test results files, if any.
  6. Invoke-Build -Task Test
    This will run your Pester test files and report if they pass or fail and how much code you’ve covered.
  7. Invoke-Build
    This will Analyze your code, Run the Pester tests and report code coverage. If the coverage is above the specified amount in the settings file, and the tests pass, it will publish the module to the pre-defined Module Repository.

    Picture of a unit test example.

    Unit testing PSScaffolding source.

Extras:
If want to deploy the module to a specific Azure VM within your build process, use the module’s function Install-PSAzureVMModule.
In the examples below it should be AzureToolkit instead of ModuleName.

Create a new file: ModuleName.deploy.settings.ps1 in the project root:

Modify ModuleName.build.ps1 and add the following below the other dot source includes at the top:
. './ModuleName.deploy.settings.ps1'

Finally add a new task in ModuleName.build.ps1:

To deploy with Invoke-Build:
Invoke-Build -Task Deploy

For more examples check out the GitHub Repository for the module.

Leave a Reply

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