psake

psake Build Automation

psake is a PowerShell build automation tool using a DSL for task-based builds with dependencies. psake v5 introduces a two-phase compile/run model, declarative syntax, file-based caching, and structured output.

Decision Tree

What kind of build are you creating?

1. PowerShell module → Use PowerShellBuild module (see references/powershell-modules.md)
2. .NET/Node.js/Docker → See references/build-types.md
3. Simple custom build → Continue below for core psake patterns

Build complexity?

• Simple (< 5 tasks, single project) → Use patterns in this file
• Complex (CI/CD, multiple environments, dynamic tasks) → See references/advanced.md

Quick Start

# Install
Install-Module -Name psake -Scope CurrentUser -Force

# Run
Invoke-psake                              # Run 'Default' task
Invoke-psake -taskList Build, Test        # Run specific tasks
Invoke-psake -docs                        # Show task documentation
Invoke-psake -OutputFormat JSON           # JSON output for CI

Minimal psakefile.ps1

Version 5

Properties {
    $BuildDir = Join-Path $PSScriptRoot 'build'
}

Task Default -depends Build

Task Clean {
    if (Test-Path $BuildDir) { Remove-Item $BuildDir -Recurse -Force }
    New-Item -ItemType Directory -Path $BuildDir -Force | Out-Null
}

Task Build -depends Clean {
    exec { dotnet build -o $BuildDir }
}

Task Test -depends Build {
    exec { dotnet test }
}

Core Commands

Task

Two equivalent syntaxes — use whichever reads better for your build:

# Classic syntax (works in v4 and v5)
Task Build -depends Clean -description "Compile project" {
    exec { dotnet build }
}

# Declarative syntax (v5 — hashtable with validated keys)
Task 'Build' @{
    DependsOn   = 'Clean'
    Description = 'Compile project'
    Action      = { exec { dotnet build } }
}

The declarative syntax validates keys at parse time — typos like DependOn throw immediately. Valid keys: Action, DependsOn, Inputs, Outputs, PreAction, PostAction, PreCondition, PostCondition, ContinueOnError, Description, Alias, RequiredVariables.

Task with Caching

Tasks with Inputs and Outputs are content-addressed cached in .psake/cache/. If input file hashes haven't changed and output files exist, the task is skipped.

Task 'Build' @{
    DependsOn = 'Clean'
    Inputs    = 'src/**/*.cs', 'src/**/*.csproj'
    Outputs   = 'bin/**/*.dll'
    Action    = { exec { dotnet build -c $Configuration } }
}

Inputs/Outputs also accept scriptblocks for dynamic file resolution:

Task 'Build' @{
    Inputs  = { Get-ChildItem src -Recurse -Include *.cs }
    Outputs = { Get-ChildItem bin -Recurse -Include *.dll -ErrorAction SilentlyContinue }
    Action  = { exec { dotnet build } }
}

Use Clear-PsakeCache to force a full rebuild, or Invoke-psake -NoCache for a single run.

Conditional Execution

Task Deploy -precondition { $env:CI -eq 'true' } -description "Deploy to prod" {
    exec { ./deploy.ps1 }
}

Properties

Variables available to all tasks. Can be overridden via -properties parameter.

# Scriptblock syntax
Properties {
    $Configuration = 'Release'
    $Version = '1.0.0'
}

# Hashtable syntax (v5)
Properties @{
    Configuration = 'Release'
    Version       = '1.0.0'
}

Override: Invoke-psake -properties @{ Configuration = 'Debug' }

Version

Pin your build script to a psake major version. The compile phase rejects version mismatches.

Version 5

exec

Runs external commands, fails build on non-zero exit:

exec { dotnet build }                                    # Basic
exec { npm install } "npm install failed"                # Custom error
exec { nuget restore } -maxRetries 3                     # Retry flaky ops
exec { npm test } -workingDirectory './frontend'         # Different directory
exec { ./slow-build.ps1 } -TimeoutSeconds 600            # Timeout (v5)

Assert

Assert (Test-Path $SrcDir) "Source directory not found"
Assert (-not [string]::IsNullOrEmpty($ApiKey)) "API key required"

Include

Include "./shared/common-tasks.ps1"

FormatTaskName

FormatTaskName "▶ {0}"
# Or with scriptblock:
FormatTaskName { param($taskName) Write-Host "[$taskName]" -ForegroundColor Cyan }

TaskSetup / TaskTearDown

TaskSetup { Write-Host "Starting: $($psake.context.currentTaskName)" }
TaskTearDown { Write-Host "Finished: $($psake.context.currentTaskName)" }

Structured Output

Invoke-psake returns a PsakeBuildResult object:

$result = Invoke-psake -Quiet
$result.Success          # $true / $false
$result.Duration         # TimeSpan
$result.Tasks            # PsakeTaskResult[] with Name, Status, Duration, Cached
$result.ErrorMessage     # Error details if failed

The $psake.build_success variable is still set after each build for backward compatibility.

For CI pipelines, use JSON output:

Invoke-psake -OutputFormat JSON

Invoke-psake Parameters

Parameter	Description
-buildFile	Path to build script (default: psakefile.ps1)
-taskList	Tasks to execute (default: 'Default')
-parameters	Hashtable passed to build script (set before Properties)
-properties	Hashtable to override Properties block (set after Properties)
-docs	Display task documentation
-nologo	Suppress banner
-OutputFormat	Default, JSON, or GitHubActions (v5)
-NoCache	Bypass task caching for this run (v5)
-CompileOnly	Return build plan without executing (v5)
-Quiet	Suppress console output; still returns PsakeBuildResult (v5)

Testability APIs

Inspect the Build Plan

$plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1'
$plan.ExecutionOrder    # ['Clean', 'Build', 'Test', 'Default']
$plan.TaskMap['build'].DependsOn  # ['Clean']
$plan.IsValid           # $true
$plan.ValidationErrors  # @()

The plan can also be piped into Invoke-psake:

Get-PsakeBuildPlan | Invoke-psake

Test a Task in Isolation

$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @{
    Configuration = 'Debug'
}
$result.Status    # 'Executed'
$result.Duration  # TimeSpan

Common Patterns

Environment-Specific

Properties {
    $Env = if ($env:ENVIRONMENT) { $env:ENVIRONMENT } else { 'Development' }
}

Task Deploy {
    switch ($Env) {
        'Production' { exec { ./deploy-prod.ps1 } }
        default      { Write-Host "Skipping deploy for $Env" }
    }
}

Multi-Project

Task BuildAll -depends BuildBackend, BuildFrontend

Task BuildBackend {
    Push-Location ./backend
    try { exec { dotnet build } }
    finally { Pop-Location }
}

Task BuildFrontend {
    Push-Location ./frontend
    try { exec { npm run build } }
    finally { Pop-Location }
}

Variable Scoping Between Tasks

Tasks don't share local variables. Use $script: scope to pass data between dependent tasks:

Task GetFiles {
    $script:Files = Get-ChildItem -Path $SrcDir -Filter *.ps1
}

Task ProcessFiles -depends GetFiles {
    foreach ($file in $script:Files) {
        # Process each file
    }
}

Note: psake tasks don't have return values. $script: scoped variables are the recommended approach for task-to-task data sharing.

Validating a psakefile

Using Get-PsakeBuildPlan (recommended)

The compile phase catches circular dependencies, missing tasks, and version mismatches before any task runs:

$plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1'
if (-not $plan.IsValid) {
    $plan.ValidationErrors | ForEach-Object { Write-Error $_ }
} else {
    Write-Host "✓ Build plan valid — execution order: $($plan.ExecutionOrder -join ' → ')"
}

Syntax Check

$errors = $null
$null = [System.Management.Automation.Language.Parser]::ParseFile(
    (Resolve-Path 'psakefile.ps1'), [ref]$null, [ref]$errors
)
if ($errors) { $errors | ForEach-Object { Write-Error $_.ToString() } }
else { Write-Host "✓ Syntax valid" -ForegroundColor Green }

Troubleshooting

Problem	Solution
Build fails but CI shows success	Use exec { } for all external commands
Cross-platform path issues	Use Join-Path instead of \ or /
Module not found in CI	Install-Module -Name psake -Scope CurrentUser -Force
Properties not overriding	Use -properties (not -parameters) to override Properties block
Variable undefined in dependent task	Use $script:VarName to share data between tasks
Circular dependency error	Check Get-PsakeBuildPlan output for ValidationErrors
Task skipped unexpectedly	May be cached — run with -NoCache or Clear-PsakeCache
default.ps1 not found	v5 removed default.ps1 fallback — rename to psakefile.ps1

References

• references/upgrading-to-v5.md - Migration guide, caching for faster builds, structured output, testability APIs
• references/powershell-modules.md - PowerShellBuild module for PS module development
• references/build-types.md - .NET, Node.js, Docker build patterns
• references/advanced.md - Dynamic tasks, CI/CD integration, $psake reference