frstlvl/writingmodules

Material accompanying PowerShell + DevOps Summit session

Writing PowerShell Modules

Materials

• Modules PowerPoint
• Plaster template
• Use the Plaster template

An important note: The content of this session made implicit assumptions, for better or worse. For example, It should be available on the PowerShell Gallery (or an internal repository) requires that you use a proper module manifest

References

These references were directly mentioned or used in coming up with the Writing PowerShell Modules: Tips, Tools, and Best Practices session at the 2017 PowerShell + DevOps Global Summit, or just related to the topic : )

Interesting Community Module Designs

• SampleModule - Still in development, but watch for a Plaster template
• PoshBot
• Posh-Teamviewer
• PSDeploy

And many more. Poke around other community modules to see what folks are doing!

Module Building Tools

• Plaster - Microsoft's module - I'd recommend this module building tool over any others going forward
• PSModuleBuild
• ConvertTo-Module

Tools and References

Getting and publishing modules:

• PowerShellGet, PackageManagement
• NuGet
• PSDepend
• PSDeploy

Package repositories:

• PSPrivateGallery - Internal PowerShell Gallery. Not production ready...
• ProGet
• Artifactory
• Chocolatey.Server - link includes other examples

Source control and related tooling:

• GitHub - Recommended for public projects. Many folks have auth, many tools integrate, PowerShell team uses it
• GitLab - Community edition is fantastic, enables CI
• VSTS - If you already paid for it. Personally not a fan of build systems that aren't defined in code

Example tools that integrate with GitHub:

• Gitter - chat specifically for a project, allows GitHub auth
• ZenHub, Waffle.io, etc.
• Octotree

Avoid fun with maml, xml:

• Platyps - Generate documentation from markdown, and vice versa
• EZOut - Simplify writing format files. Alternatively, just poke around other folks' psm1xml

Mentioned during tips on functions, and making it feel PowerShell-y:

• Monad Manifesto - Just read it
• Building PowerShell Functions - Best Practices - Includes a number of references on writing functions

Discussions on module design:

• PowerShellPracticeAndStyle issue #22
• PowerShellPracticeAndStyle issue #59
• Plaster issue #2
• Twitter discussion on dot sourcing

Linting and testing:

• PSScriptAnalyzer - Linting, I guess? Static code checker
• Pester
• Poshspec

CI/CD - Run your tests, among other things:

• AppVeyor - Free, perfect for public PowerShell modules
• GitLab CE CI
• Jenkins
• VSTS - If you already paid for it. Maybe. Personally not a fan of build systems that aren't defined in code
• Invoke-BuildUsed in an example of non-PowerShelly authoring. Awesome for users, harder for contributors
• Psake - Not as much functionality as Invoke-Build, and was dead, but this might change...

On module and function design, among other things:

• Module Design Rules - This is from the 2014 PowerShell Summit, thanks to Kirk Freiheit
• Writing about_help topics
• Further Down the Rabbit Hole: PowerShell Modules and Encapsulation
• How to Write a Module Manifest
• Understanding a Windows PowerShell Module
• about_Modules (swap out 5.1 with 3.0 or up)
• Learn PowerShell Toolmaking in a Month of Lunches
• The PowerShell Scripting and Toolmaking Book
• Free eBook on PowerShell Advanced Functions
• The PowerShell Best Practices and Style Guide - issues like #22 and #59
• Plaster issues, including #2
• Building a PowerShell Module - A practical example

Misc:

• Semantic Versioning
• Choose A License