Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/theplatformer/powershell-module-template
My PowerShell module project template for use with Plaster.
https://github.com/theplatformer/powershell-module-template
plaster plaster-template powershell powershell-module
Last synced: 3 months ago
JSON representation
My PowerShell module project template for use with Plaster.
- Host: GitHub
- URL: https://github.com/theplatformer/powershell-module-template
- Owner: theplatformer
- License: mit
- Created: 2019-04-24T02:23:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-12-08T23:18:16.000Z (11 months ago)
- Last Synced: 2024-05-28T02:20:55.645Z (5 months ago)
- Topics: plaster, plaster-template, powershell, powershell-module
- Language: PowerShell
- Homepage:
- Size: 13.7 KB
- Stars: 5
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - theplatformer/powershell-module-template - My PowerShell module project template for use with Plaster. (PowerShell)
README
# PowerShell Module Template
My PowerShell module project template, for use with [Plaster](https://github.com/PowerShell/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...
```powershell
Invoke-Plaster -TemplatePath -DestinationPath
```
You will then have a newly scaffolded PowerShell module project to start work on.
## Dependencies
- [Plaster](https://github.com/PowerShell/Plaster), for scaffolding the new module project.
- [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer), for linting and styling of PowerShell code.
- [Pester](https://github.com/pester/Pester), for unit testing.
- [platyPS](https://github.com/PowerShell/platyPS), for generating external help files.
- [Invoke-Build](https://github.com/nightroman/Invoke-Build), for build automation.
- [New-VSCodeTask](https://www.powershellgallery.com/packages/New-VSCodeTask), for automatically generating VS Code tasks from Invoke-Build tasks.
## 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](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](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/about_Plaster_CreatingAManifest.help.md).
## 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!