Skip to main content

Introduction to PowerShellBuild

PowerShellBuild is the official companion module to psake. Where psake is a general-purpose build automation engine, PowerShellBuild is a curated library of pre-built psake tasks that handle every step of a PowerShell module's lifecycle — building, testing, analysis, help generation, signing, and publishing — so you don't have to write that scaffolding from scratch.

The Problem It Solves​

Every PowerShell module project needs roughly the same build pipeline:

  1. Clean the output directory
  2. Stage (copy/compile) module files to the output
  3. Run PSScriptAnalyzer for code quality
  4. Run Pester tests
  5. Generate MAML help from PlatyPS markdown
  6. Publish to the PowerShell Gallery

Writing this pipeline from scratch in every project is repetitive. If you discover a better pattern (say, a smarter way to compute code coverage), you'd have to update every project manually. PowerShellBuild solves this by packaging the pipeline as a versioned, distributable module — update the module version and all your projects get the improvement.

How It Relates to psake​

PowerShellBuild lives under the same GitHub organization as psake (psake/PowerShellBuild) and is built on a feature introduced in psake v4.8.0: the ability to reference shared tasks distributed inside a PowerShell module.

┌─────────────────────────────────────┐
│  Your project's psakeFile.ps1       │
│                                     │
│  Task Build -FromModule            │
│      PowerShellBuild               │
│      -RequiredVersion 0.8.2        │
└────────────────┬────────────────────┘
                 │ psake discovers task definitions
┌─────────────────────────────────────┐
│  PowerShellBuild module             │
│  (Init → Clean → StageFiles →       │
│   BuildHelp → Build → ...)          │
└─────────────────────────────────────┘

When psake encounters a task declared with -FromModule, it finds the selected module and dot-sources the module-root psakeFile.ps1 in the current build context. That file registers all its provider tasks; psake later runs only Build and its reachable dependencies. This process does not itself import the module's .psm1.

Also Supports Invoke-Build​

PowerShellBuild is not limited to psake. It ships Invoke-Build task files as well, accessible through the PowerShellBuild.IB.Tasks PowerShell alias. See the PowerShellBuild README for Invoke-Build usage. The rest of this section focuses on the psake integration.

When to Use PowerShellBuild​

Use PowerShellBuild when:

  • You are building a PowerShell module (.psd1 / .psm1) and want a standardized pipeline
  • You want to avoid writing boilerplate psake tasks that every PS module project needs
  • You want your build pipeline versioned and shareable across multiple module projects

Write custom psake tasks instead when:

  • You are building something other than a PowerShell module (a .NET solution, a Node.js app, a Docker image, etc.)
  • You need a workflow that significantly deviates from the standard module structure
  • You are using psake purely for orchestration of external tools

Installation​

Install PowerShellBuild from the PowerShell Gallery:

Install-Module -Name PowerShellBuild -Repository PSGallery

PowerShellBuild 0.8.2 requires psake 5.0.4 or later. Check the current module manifest when selecting a newer version:

Install-Module -Name psake -Repository PSGallery

Or declare both as dependencies in a requirements.psd1 (managed via PSDepend):

@{
    psake            = 'latest'
    PowerShellBuild  = 'latest'
}

See Also​