Glossary

A comprehensive glossary of terms and concepts used throughout psake documentation.

Build Terms

Build Script

A PowerShell script containing psake task definitions, typically named psakefile.ps1 or default.ps1. The build script defines all tasks, properties, and build logic for your project.

# Example build script
Properties {
    $BuildDir = './build'
}

Task Default -depends Build

Task Build {
    exec { dotnet build }
}

Build File

Another term for a build script. The file that contains your psake build definitions.

Build Artifacts

Output files generated by the build process, such as compiled binaries, packages, documentation, or deployment files. Typically stored in a dedicated directory like build/, dist/, or artifacts/.

Core Concepts

Task

A named unit of work in a psake build script. Tasks are the building blocks of your build automation. Each task can have dependencies, preconditions, postconditions, and actions to perform.

Task Build {
    # Task action
    Write-Host "Building project..."
    exec { dotnet build }
}

Key characteristics:

Has a unique name
Contains PowerShell code to execute
Can depend on other tasks
Runs exactly once per build (unless called via Invoke-Task)

Task Dependency

A relationship between tasks where one task requires another task to run first. Dependencies are declared using the -depends parameter.

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

In this example, the Build task must complete successfully before Test runs.

Dependency resolution:

Dependencies run before the dependent task
Each dependency runs only once per build
Circular dependencies cause build failure
Dependencies can be chained (transitive)

Default Task

The task that runs when you invoke psake without specifying a task name. Typically used to run the most common build workflow.

Task Default -depends Clean, Build, Test

# These are equivalent:
Invoke-psake
Invoke-psake -taskList Default

Best practices:

Always define a Default task
Make it run your standard build workflow
Use it for the most common developer scenario

Property

A variable defined in the Properties block of a build script. Properties hold configuration values that can be overridden via parameters.

Properties {
    $Configuration = 'Release'
    $OutputPath = './build'
    $Version = '1.0.0'
}

Properties are available throughout the build script and can be referenced in any task.

Parameter

A value passed to the build script at invocation time. Parameters override default property values.

# In psakefile.ps1
Properties {
    $Configuration = 'Debug'  # Default value
}

# Invoke with parameter
Invoke-psake -parameters @{
    Configuration = 'Release'  # Override default
}

Common uses:

Environment selection (Dev, Staging, Production)
Build configuration (Debug, Release)
Version numbers
Feature flags

Properties Block

A special block in the build script where properties are defined and initialized. Can appear multiple times in a script, and properties can be defined in any order.

Properties {
    $BuildDir = Split-Path $psake.build_script_file
    $Configuration = 'Release'
}

Properties {
    $ArtifactsDir = Join-Path $BuildDir 'artifacts'
}

Execution Control

Precondition

A test that must pass before a task executes. If the precondition fails, the task is skipped (not executed, not failed).

Task Deploy -precondition { $Environment -eq 'Production' } {
    # Only runs if Environment is Production
    exec { ./deploy.ps1 }
}

Use cases:

Environment-specific tasks
Conditional execution based on configuration
Skip tasks when prerequisites aren't met

Postcondition

A test that must pass after a task completes. If the postcondition fails, the build fails.

Task Build -postcondition { Test-Path './build/app.dll' } {
    exec { dotnet build -o ./build }
}

Use cases:

Verify task produced expected output
Validate build artifacts exist
Ensure task side effects occurred

Exec

A psake function that executes an external command and automatically fails the build if the command exits with a non-zero exit code.

Task Build {
    exec { dotnet build }  # Fails build if dotnet returns error
}

Without exec, you'd need to manually check $LASTEXITCODE:

Task Build {
    dotnet build
    if ($LASTEXITCODE -ne 0) {
        throw "Build failed"
    }
}

Key features:

Automatic error detection
Custom error messages
Retry support with -retry parameter
Working directory control

Assert

A psake function that tests a condition and fails the build if the condition is false.

Task Validate {
    Assert (Test-Path './src') "Source directory not found"
    Assert ($Version -match '^\d+\.\d+\.\d+$') "Invalid version format"
}

Use cases:

Validate prerequisites
Check configuration values
Verify file existence
Test build assumptions

Include

A psake directive that includes tasks and functions from another PowerShell file into your build script.

# In psakefile.ps1
Include ./tasks/common-tasks.ps1
Include ./tasks/deploy-tasks.ps1

Task Build -depends CommonClean {
    # Can use tasks from included files
}

Use cases:

Share tasks across multiple projects
Organize large build scripts
Reuse common build logic
Team-wide build standards

Nested Build

Invoking one psake build script from within another. Used to build multi-project solutions or orchestrate complex builds.

Task BuildSubprojects {
    Invoke-psake ./projectA/psakefile.ps1 -taskList Build
    Invoke-psake ./projectB/psakefile.ps1 -taskList Build
}

When to use:

Multi-project solutions
Monorepo builds
Independent but related projects
Coordinated build orchestration

Context and State

$psake Variable

A special variable available in all build scripts that contains psake context information and configuration.

Common properties:

$psake.build_script_file - Full path to current build script
$psake.build_script_dir - Directory containing build script
$psake.version - psake version number
$psake.context - Build execution context

Properties {
    $ProjectRoot = Split-Path $psake.build_script_file
    $BuildNumber = $psake.build_number
}

Task Info {
    Write-Host "psake version: $($psake.version)"
    Write-Host "Build script: $($psake.build_script_file)"
}

Build Context

The execution environment and state of a psake build, including:

Current task being executed
Task call stack
Properties and their values
Build success/failure state

Accessible via $psake.context.

Build Script File

The currently executing psake build file. Accessible via $psake.build_script_file.

Properties {
    $ScriptDir = Split-Path $psake.build_script_file
    $ProjectRoot = Split-Path $ScriptDir
}

Output and Formatting

FormatTaskName

A configuration function that customizes how task names are displayed during build execution.

FormatTaskName {
    param($taskName)
    Write-Host "===== $taskName =====" -ForegroundColor Cyan
}

Use cases:

Custom task headers
Visual separation of tasks
Branding/styling build output
Integration with logging systems

Task Documentation

The -description parameter on tasks that provides help text. Displayed when running Invoke-psake -docs.

Task Build -description "Compiles the solution" {
    exec { dotnet build }
}

# View documentation
Invoke-psake -docs

# Output:
# Build         Compiles the solution
# Test          Runs all unit tests
# Deploy        Deploys to production

Error Handling

Exit Code

A numeric value returned by a program indicating success (0) or failure (non-zero). The exec function automatically checks exit codes.

Task Build {
    exec { dotnet build }  # Checks $LASTEXITCODE automatically
}

Common exit codes:

0 - Success
1 - General error
Other values - Application-specific errors

ContinueOnError

A parameter for the exec function that allows build to continue even if a command fails.

Task Test {
    # Continue even if tests fail
    exec { dotnet test } -continueOnError

    Write-Host "Tests completed (may have failures)"
}

Use cases:

Optional operations
Best-effort tasks
Collecting multiple errors before failing

MaxRetries

A parameter for the exec function that automatically retries failed commands.

Task Deploy {
    # Retry up to 3 times on failure
    exec { ./deploy.ps1 } -maxRetries 3 -retryTriggerErrorPattern "timeout"
}

Use cases:

Network operations
Flaky external services
Deployment to cloud resources
Package publishing

Build Framework

Framework

The .NET Framework version to target. Specified via the -framework parameter when invoking psake.

Invoke-psake -framework '4.8'
Invoke-psake -framework 'net6.0'

Note: This is primarily for legacy compatibility. Modern builds typically handle framework targeting via project files.

psake Module

The PowerShell module that provides the psake build automation functionality. Installed from the PowerShell Gallery.

# Install the module
Install-Module -Name psake -Scope CurrentUser

# Import the module
Import-Module psake

# Check version
Get-Module psake | Select-Object Version

Invoke-psake

The main command that executes a psake build script.

# Basic usage
Invoke-psake

# Specify build file and task
Invoke-psake -buildFile ./build.ps1 -taskList Build, Test

# Pass parameters
Invoke-psake -parameters @{ Configuration = 'Release' }

# Verbose output
Invoke-psake -Verbose

# Documentation mode
Invoke-psake -docs

Key parameters:

-buildFile - Path to build script (default: psakefile.ps1)
-taskList - Tasks to execute (default: Default)
-parameters - Hashtable of parameters
-properties - Alternative way to pass parameters
-framework - .NET Framework version
-docs - Show task documentation
-detailedDocs - Show detailed task information

CI/CD Terms

Continuous Integration (CI)

The practice of automatically building and testing code changes. psake is commonly used as the build engine in CI pipelines.

CI platforms that work with psake:

GitHub Actions
Azure Pipelines
GitLab CI
Jenkins
TeamCity

Build Agent

A machine (physical or virtual) that executes CI/CD builds. Build agents run your psake scripts in automated fashion.

Considerations for psake on build agents:

PowerShell availability
psake module installation
Environment variables
Authentication/secrets

Build Artifact

See Build Artifacts

Environment Variable

Operating system variables used to pass configuration to build scripts. Commonly used in CI/CD to provide secrets and environment-specific values.

Properties {
    $ApiKey = $env:API_KEY
    $Environment = $env:BUILD_ENVIRONMENT ?? 'Development'
}

Task Deploy {
    if ([string]::IsNullOrEmpty($ApiKey)) {
        throw "API_KEY environment variable is required"
    }

    exec { ./deploy.ps1 -ApiKey $ApiKey }
}

Best practices:

Never hardcode secrets in build scripts
Use environment variables for sensitive data
Provide sensible defaults for local development
Document required environment variables

Advanced Concepts

Task Alias

An alternative name for a task, created by defining a task that depends on another task without additional logic.

Task Build {
    exec { dotnet build }
}

# Create alias
Task Compile -depends Build {
    # No additional logic - just an alias
}

Task Hook

Using preconditions and postconditions to hook into task execution lifecycle.

Task Build `
    -precondition { Write-Host "About to build..." } `
    -postcondition { Write-Host "Build complete!" } `
{
    exec { dotnet build }
}

Shared Task Library

A collection of reusable tasks that can be included in multiple build scripts.

# In shared-tasks.ps1
Task CommonClean {
    Remove-Item ./build -Recurse -Force -ErrorAction SilentlyContinue
}

Task CommonRestore {
    exec { dotnet restore }
}

# In psakefile.ps1
Include ./shared-tasks.ps1

Task Build -depends CommonClean, CommonRestore {
    exec { dotnet build }
}

Build Configuration

A set of build settings, typically Debug or Release, but can be any custom configuration name.

Properties {
    $Configuration = 'Release'
}

Task Build {
    exec { dotnet build --configuration $Configuration }
}

# Invoke with different configuration
Invoke-psake -parameters @{ Configuration = 'Debug' }

Task Graph

The directed acyclic graph (DAG) of task dependencies. psake resolves this graph to determine task execution order.

Task Default -depends Test
Task Test -depends Build
Task Build -depends Clean, Restore

# Task graph: Clean, Restore → Build → Test → Default
# Execution order: Clean → Restore → Build → Test

Key properties:

Must be acyclic (no circular dependencies)
Determines execution order
Each node executes at most once
Respects declared dependencies

Common Patterns

Clean Build

Removing all build artifacts before building, ensuring a fresh build from source.

Task Clean {
    Remove-Item ./build -Recurse -Force -ErrorAction SilentlyContinue
}

Task Build -depends Clean {
    exec { dotnet build }
}

Incremental Build

Building only what has changed since the last build. Faster than clean builds but requires careful change detection.

Task IncrementalBuild {
    # Only rebuild if source is newer than output
    if ((Get-Item ./src).LastWriteTime -gt (Get-Item ./build).LastWriteTime) {
        exec { dotnet build --no-restore }
    }
}

Build Pipeline

A series of tasks that represent the complete build workflow from clean to deploy.

Task Default -depends Clean, Restore, Build, Test, Package, Deploy

Conditional Task

A task that only runs when certain conditions are met, using preconditions.

Properties {
    $Environment = 'Development'
}

Task DeployProd -precondition { $Environment -eq 'Production' } {
    exec { ./deploy-production.ps1 }
}

Build Terms​

Build Script​

Build File​

Build Artifacts​

Core Concepts​

Task​

Task Dependency​

Default Task​

Property​

Parameter​

Properties Block​

Execution Control​

Precondition​

Postcondition​

Exec​

Assert​

Include​

Nested Build​

Context and State​

$psake Variable​

Build Context​

Build Script File​

Output and Formatting​

FormatTaskName​

Task Documentation​

Error Handling​

Exit Code​

ContinueOnError​

MaxRetries​

Build Framework​

Framework​

psake Module​

Invoke-psake​

CI/CD Terms​

Continuous Integration (CI)​

Build Agent​

Build Artifact​

Environment Variable​

Advanced Concepts​

Task Alias​

Task Hook​

Shared Task Library​

Build Configuration​

Task Graph​

Common Patterns​

Clean Build​

Incremental Build​

Build Pipeline​

Conditional Task​

See Also​

Build Terms

Build Script

Build File

Build Artifacts

Core Concepts

Task

Task Dependency

Default Task

Property

Parameter

Properties Block

Execution Control

Precondition

Postcondition

Exec

Assert

Include

Nested Build

Context and State

$psake Variable

Build Context

Build Script File

Output and Formatting

FormatTaskName

Task Documentation

Error Handling

Exit Code

ContinueOnError

MaxRetries

Build Framework

Framework

psake Module

Invoke-psake

CI/CD Terms

Continuous Integration (CI)

Build Agent

Build Artifact

Environment Variable

Advanced Concepts

Task Alias

Task Hook

Shared Task Library

Build Configuration

Task Graph

Common Patterns

Clean Build

Incremental Build

Build Pipeline

Conditional Task

See Also