PSModuleUtils

A module with helper functions to build and publish PowerShell modules to the PSGallery.

Setup

Install-Module PSModuleUtils

PowerShell Module Development

Follow The PowerShell Best Practices and Style Guide as much as possible, with the following rules being the most important:

• Use Approved Verbs for commands so that PowerShell's built-in ability to autocomplete un-imported functions works.
• Add help comments to all functions because each module's wiki is auto-generated from them.

Use the following additional guidelines:

• Modules are built with ModuleBuilder via Build-PSModule. There is no source .psm1: ModuleBuilder concatenates every .ps1 under the configured source directories into a single built .psm1.
• The manifest template is hand-authored and treated as a source file, not a generated one. By default, Build-PSModule derives the module name from the manifest filename and uses its ModuleVersion and Prerelease values. Use -Version only for an explicit build override. ModuleBuilder updates FunctionsToExport and AliasesToExport, while PSModuleUtils stamps git-derived fields (Author, CompanyName, Copyright, ProjectUri, ReleaseNotes). Everything else you author (GUID, Description, RequiredModules, PrivateData.PSData.Tags, etc.) is preserved as-is. Pre-declare PrivateData.PSData.Prerelease and PrivateData.PSData.ReleaseNotes in the template (empty strings are fine). Run New-PSModuleManifest to scaffold or migrate a compatible template.
• Ideally, each module and each of its functions should have a set of Pester unit/integration tests. At the least, any new functions or functionality should have an associated test.
• Create all functions as single .ps1 files with the same name and without Export-ModuleMember statements.
  • The files should be in an appropriate nested Public folder that corresponds to its API category.
  • Functions that are used by other functions should be put in either Utils or Private, depending on their usage.
• Tests must live in a top-level tests/ folder, never inside Public/Private. ModuleBuilder inlines every .ps1 it finds in those folders with no exclusion, so a co-located *.Tests.ps1 leaks Describe/It blocks into the built module and its exports.
• Keep packaged assets outside the configured source directories. Build-PSModule copies every other source-root item automatically, preserving directories such as Assemblies, bin, Settings, Schemas, Templates, Resources, and culture names such as en-US. Use -CopyPaths only for additional files or directories outside that automatic set.
• Declare files that PowerShell loads as part of module import in the manifest. Use RequiredAssemblies for prerequisite DLLs, FormatsToProcess for formatting files, and TypesToProcess for type extensions. Use FileList only as package inventory. Other runtime assets can be resolved relative to $PSScriptRoot; see Get-PSModuleAnalyzerSettingsPath for handling source and built layouts.

The folder structure should be maintained like the example below:

\MODULEREPODIRECTORY
├───.github
│   └───workflows
├───.gitignore
├───LICENSE
├───README.md
├───build.ps1
│
├───src
│   ├───ModuleName.psd1
│   │
│   ├───Public
│   │   └───functionalArea
│   │       └───Verb-Noun.ps1
│   │
│   ├───Private
│   │   └───Verb-Noun.ps1
│   │
│   ├───Assemblies
│   │   └───Dependency.dll
│   │
│   └───Resources
│       └───Template.json
│
└───tests
    ├───ModuleName.Module.Tests.ps1
    └───Verb-Noun.Tests.ps1