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.
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.
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:
Pester is usually included in newer versions of PowerShell.
Using the module
To use the module:
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.
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.
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.
- Write code, create more functions, test it.
- Modify the file
AzureToolkit.settings.ps1to specify the correct build and deploy settings for your module. You’ll need to modify the
AzureToolkit.build.ps1to match the target repository type.
Invoke-Build -Task Clean
This will download
PSScriptAnalyzerto analyze your code in future tasks. It also clears out test results files, if any.
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.
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.
If want to deploy the module to a specific Azure VM within your build process, use the module’s function
In the examples below it should be AzureToolkit instead of ModuleName.
Create a new file:
ModuleName.deploy.settings.ps1 in the project root:
ModuleName.build.ps1 and add the following below the other dot source includes at the top:
Finally add a new task in
To deploy with Invoke-Build:
Invoke-Build -Task Deploy
For more examples check out the GitHub Repository for the module.