Module.Template

Powershell Module Template with GitHub, PowerShellGallery, AppVeyor and Azure DevOps Pipelines integration.
Can be used as a starting point for your open source Module.

CI System	Environment	Master	Beta
AppVeyor	Windows, Core preview, Ubuntu
Azure DevOps	Windows
Azure DevOps	Windows (Core)
Azure DevOps	Ubuntu
Azure DevOps	macOS

Install

From repository (Recommended)

Install-Module -Name Module.Template -Scope CurrentUser

From GitHub Branch (For testing)

$Uri = 'https://raw.githubusercontent.com/ili101/Module.Template/master/Install.ps1'; & ([Scriptblock]::Create((irm $Uri))) -FromGitHub $Uri

Instructions

Setup

1. Create a GitHub Repository (Recommended name is the name of the Module) and clone the repository with VSCode.
2. Clone or download this repository and copy the files to your repository clone.
3. Remove/Replace/Edit/Rename the files Module.Template.psm1, Module.Template.psm1, Invoke-ExampleCommand.ps1, Class.ps1 with your module files.
4. Remove/Replace/Edit/Rename the file Tests\Invoke-ExampleCommand.Tests.ps1 with tests for your Module, you can create multiple test files in the folder ending with .Tests.ps1.
5. Edit README.md, CHANGELOG.md and the Examples folder to provide documentation for the Module.
6. Install.ps1 is used to "build" the module and put it in the PowerShell Modules folder, adjust the $IncludeFiles and $ExcludeFiles variables if needed to configure which files and folders to copy from the source root folder. Can be used locally by executing Install.ps1 or remotely from GitHub by the Install command mentiond in the README.md. (Also used in the CI procedure).
7. To use AppVeyor create an account on https://www.appveyor.com/ and connect it to the GitHub repository, the appveyor.yml file is used for the configuration.
8. To use Azure DevOps Pipelines create an account on https://dev.azure.com and connect it to the GitHub repository, the azure-pipelines.yml file is used for the configuration.

CI Configuration and usage

Triggers - When Pushing a Commit to GitHub AppVeyor and Azure will be triggered unless the Commit contain only changes to the .md files or the skip tags [skip azp] (for Azure) and/or [skip av] (for AppVeyor) are added to the Commit name.
This behavior can be adjusted in the .yml files (azure-pipelines.yml do not support wildcards in the file names under trigger:paths:exclude).
Additionally to run a quick test locally in VSCode click F5 (verify debug is set to "PowerShell Pester Tests" in the debug section, this is set in .vscode\launch.json)

PowerShell Version and OS - AppVeyor set to test on Ubuntu, Windows Framework and Windows Core.
For Windows Core you can control the version by setting it in the line - ps: '& .\CI\InstallPowerShell.ps1 -Version "7.0.0-preview.4"' or comment the line out to use the default version. For Ubuntu you can change or comment out the line with the sudo apt-get install -y powershell-preview.
Azure test on Windows Framework and Ubuntu, add/remove jobs in the .yml file to change it.

Test Results - The Pester test results are published to AppVeyor Tests tab by the .\CI\CI.ps1 -Finalize line, and to the Azure Tests tab by the PublishTestResults@2 task.

Artifacts - Artifacts are Zip files created for later use, Artifact with the Windows Framework Module is uploaded to the AppVeyor Artifacts tab by the .\CI\CI.ps1 -Artifact line, Artifact with the Windows Framework Module and Artifact with the Git Source is uploaded to Azure by the .\CI\CI.ps1 -Artifact segment.

Publish to PowerShell Gallery - You can publish the Module to the PowerShell Gallery in 3 ways:

1. AppVeyor will publish the module automatically if the commit is made in the GitHub master branch and the module version in the .psd file is newer from the version in the gallery.
   For this to work you need to go to AppVeyor > project > settings and under Environment add an "encrypted" environment variable named "NugetApiKey" with your PowerShell Gallery Key.
   To disable this comment out the - ps: '$null = Install-PackageProvider -Name NuGet -Force ; & .\CI\Publish.ps1' line

2. In Azure you can publish the module manually from an Artifacts. For this to work you need to configure a "Releases" in Azure, I didn't find a way to configure it in the .yml, but I exported it to json CI\Azure Publish config.json, import it in Azure > Releases (You may need to create an empty releases, save it, view releases, New > Import and delete the empty release. Microsoft can create the worst interfaces known to man).
   After importing in the Artifacts stage "Artifacts" will point to "Module.Template" delete "Artifacts" and recreate it pointing to your Project, If something show in red fix it (For example in "Publish Job" if the OS is not set select "windows-2019"). Then in the release configuration Variable tab add a "Secret" "Publish Stage" pipeline variable named "NugetApiKey" with your PowerShell Gallery Key.
   To publish click "Create a new release" and select the Build version containing the Artifact to use for the release.
   (You can delete the CI\Azure Publish config.json file)

3. You can also run CI\Publish.ps1 locally with -NugetApiKey <Key>

Publish to Docker Hub - You can also publish the Module to Docker Hub (Can be good for testing new builds). You can optionally modify the Docker build by editing CI\Dockerfile. The steps are the same as the PowerShell Gallery publish. In Azure > Releases import CI\Azure Docker config.json, Recreate "Artifacts" so it point to your Project, If something show in red fix it (Set the OS to Windows or Linux according to the OS configured in CI\Dockerfile), In "Docker Stage" > "buildAndPush" > "Container registry" set your Docker Hub credentials. You can delete the CI\Azure Docker config.json file.

ScriptAnalyzer - A ScriptAnalyzer report is generated and saved in Azure Pipelines > Artifacts > Source > ScriptAnalyzer.xlsx. In a PR the report will include the PR analysis and the target branch analysis.
To disable this comment out the - powershell: './CI/CI.ps1 -Analyzer' section in the Azure yaml.

Changelog

CHANGELOG.md

Contributing

If you fund a bug or added functionality or anything else just fork and send pull requests. Thank you!
Ideas for new functionality and feature requests are welcomed, you can post your ideas in the "Issues" section.

To do

• Noting for now, You can open an Issues if something is needed.

Examples

Invoke-ExampleCommand.Examples.ps1

Invoke-ExampleCommand