Skip to content

Latest commit

 

History

History
124 lines (96 loc) · 5.04 KB

README.md

File metadata and controls

124 lines (96 loc) · 5.04 KB
Raw

PowerShell Module Template

My PowerShell module project template, for use with Plaster.

This template sets up a number of things to make getting started with authoring a new PowerShell module much less time consuming, while following best practices around organising source code, unit testing and documentation. On top of a basic project structure, it also has a number of build tasks setup and some extra things like VS Code tasks already configured.

This is the result of me seeing how a number of other projects and people organise their modules, and then tweaking/simplifying things to my liking.

Using The Template

To create a new PowerShell module project with this template, download/clone this repository into a folder and then run...

Invoke-Plaster -TemplatePath <PathToFolder> -DestinationPath <PathForNewProject>

You will then have a newly scaffolded PowerShell module project to start work on.

Dependencies

How It Works

When invoked, Plaster reads the plasterManifest.xml file to scaffold a new module project. The Plaster manifest XML file declaratively describes the content and creation process for the new project. Take a look at the plasterManifest.xml file to see how it generates the output shown below.

For more information on Plaster manifests and how they work, head over to the Plaster docs.

Output Example

MyNewModule
|
|---.vscode
|       settings.json
|       tasks.json
|
|---docs
|   
|---src
|   |---docs
|   |   |---en-US
|   |   |       about_MyNewModule.md
|   |   |       Add-YourFirstFunction.md
|   |
|   |---private
|   |       Add-PrivateFunction.ps1
|   |
|   |---public
|   |       Add-YourFirstFunction.ps1
|   |
|   |   MyNewModule.psd1
|   |   MyNewModule.psm1
|
|---tests
|   |---private
|   |       Add-PrivateFunction.Tests.ps1
|   |
|   |---public
|   |       Add-YourFirstFunction.Tests.ps1
|   |
|   |   _InitializeTests.ps1
|   |   MyNewModule.Manifest.Tests.ps1
|
|   .gitignore
|   LICENSE
|   MyNewModule.Build.ps1
|   PSScriptAnalyzerSettings.psd1
|   README.md

Output Details

.vscode

Contains Visual Studio Code workspace settings and task definitions.

  • extensions.json - Provides extension recommendations.
  • settings.json - Overrides editor settings for tab indents and whitespace.
  • tasks.json - Generated by New-VSCodeTask script so Invoke-Build tasks are available as VS Code tasks.

docs

Directory for project documentation as per GitHub convention, separate from the module's own documentation.

src

Contains all source code for the PowerShell module.

  • docs\en-US - Contains markdown sources for module documentation.
    • about_MyNewModule.md - platyPS template for PowerShell's 'about' help topic.
    • Add-YourFirstFunction.md - platyPS template for the example public function's help document.
  • private - Contains sources for all private module functions.
    • Add-PrivateFunction.ps1 - Example private module function.
  • public - Contains sources for all public module functions.
    • Add-YourFirstFunction.ps1 - Example public module function.
  • MyNewModule.psd1 - PowerShell module manifest file.
  • MyNewModule.psm1 - PowerShell root module file.

tests

Contains all Pester tests for the module.

  • private - Contains Pester tests for private module functions.
    • Add-PrivateFunction.Tests.ps1 - Example Pester test for example private module function.
  • public - Contains Pester tests for public module functions.
    • Add-YourFirstFunction.Tests.ps1 - Example Pester test for example public module function.
  • _InitializeTests.ps1 - Common initialize script that can be dot sourced into individual Pester test files.
  • MyNewModule.Manifest.Tests.ps1 - Pester test file for the PowerShell module's manifest file.

/

  • .gitignore - Ignore file for Git.
  • LICENSE - MIT license document.
  • MyNewModule.Build.ps1 - Invoke-Build script, containing task definitions.
  • PSScriptAnalyzerSettings.psd1 - Settings file for PSScriptAnalyzer.
  • README.md - Project readme file.

Contributions

Although this template is built to my own preferences, any contributions or suggestions for improvements would be very welcomed!