Powershellbuild

PowerShellBuild

PowerShellBuild provides standardized build, test, and publish tasks for PowerShell modules. It works with both psake (≥ 4.8.0) and Invoke-Build (≥ 5.8.1).

Decision Tree

Which task runner are you using?

• psake → use task <Name> -FromModule PowerShellBuild pattern
• Invoke-Build → use . PowerShellBuild.IB.Tasks pattern
• Not sure / starting fresh → default to psake (simpler syntax)

What do you need?

• Set up a new module project → See references/complete-example.md
• Override build behavior → Configuration ($PSBPreference)
• Customize task dependencies → Modifying Task Dependencies
• CI/CD setup → See references/ci-cd.md

Quick Start

Install-Module -Name PowerShellBuild -Repository PSGallery -Scope CurrentUser
Install-Module -Name psake -MinimumVersion 4.8.0 -Repository PSGallery -Scope CurrentUser

Minimal psakeFile.ps1

Do NOT Import-Module PowerShellBuild in psakeFile.ps1 — -FromModule loads the module automatically when psake parses the task definitions.

properties {
    $PSBPreference.Test.ScriptAnalysis.Enabled = $true
    $PSBPreference.Test.CodeCoverage.Enabled   = $false
}

task default -depends Test

task Test    -FromModule PowerShellBuild
task Publish -FromModule PowerShellBuild

This gives you: Init → Clean → StageFiles → BuildHelp → Build → Analyze → Pester → Test → Publish

Project Structure

MyModule/
├── build.ps1              # Entry point
├── psakeFile.ps1          # Build tasks (psake)
├── .build.ps1             # Build tasks (Invoke-Build)
├── requirements.psd1      # Dependencies
├── MyModule/              # Source directory
│   ├── MyModule.psd1      # Module manifest
│   ├── MyModule.psm1      # Module root
│   ├── Public/            # Exported functions
│   └── Private/           # Internal functions
├── tests/
│   └── MyModule.Tests.ps1
└── Output/                # Build output (auto-generated)

Available Tasks

Primary Tasks

Secondary Tasks

Configuration ($PSBPreference)

Set these in your properties block before referencing PowerShellBuild tasks.

Build

$PSBPreference.General.ModuleName              = 'MyModule'       # auto-detected from manifest
$PSBPreference.General.SrcRootDir              = './MyModule'     # default: project root
$PSBPreference.Build.OutDir                    = './Output'
$PSBPreference.Build.CompileModule             = $true            # merge into single PSM1
$PSBPreference.Build.CompileDirectories        = @('Enum', 'Classes', 'Private', 'Public')
$PSBPreference.Build.CopyDirectories           = @('Data')        # copy as-is (no compile)
$PSBPreference.Build.Exclude                   = @('*.Tests.ps1')

Test

$PSBPreference.Test.Enabled                                = $true
$PSBPreference.Test.RootDir                               = './tests'
$PSBPreference.Test.OutputFile                            = 'TestResults.xml'
$PSBPreference.Test.OutputFormat                          = 'NUnitXml'
$PSBPreference.Test.ScriptAnalysis.Enabled                = $true
$PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Error'
$PSBPreference.Test.CodeCoverage.Enabled                  = $true
$PSBPreference.Test.CodeCoverage.Threshold                = 0.75   # 0.0–1.0

Help & Docs

$PSBPreference.Help.DefaultLocale             = 'en-US'
$PSBPreference.Help.ConvertReadMeToAboutHelp  = $false
$PSBPreference.Docs.RootDir                   = './docs'

Publish

$PSBPreference.Publish.PSRepository        = 'PSGallery'
$PSBPreference.Publish.PSRepositoryApiKey  = $env:PSGALLERY_API_KEY

Modifying Task Dependencies

Set these variables before the -FromModule references take effect:

$PSBBuildDependency   = 'StageFiles'  # skip help generation
$PSBTestDependency    = 'Pester'      # skip analysis
$PSBPublishDependency = 'Build'       # publish without tests (not recommended)

Invoke-Build Alternative

. PowerShellBuild.IB.Tasks

$PSBPreference.Build.CompileModule         = $true
$PSBPreference.Test.CodeCoverage.Enabled   = $true
$PSBPreference.Test.CodeCoverage.Threshold = 0.75

task . Build

Troubleshooting

References

• references/complete-example.md - Full project scaffold: build.ps1, requirements.psd1, psakeFile.ps1 with all tasks
• references/ci-cd.md - GitHub Actions workflow for test and publish pipelines