Invoke-Build Documentation

Invoke-Build provides a suite of specialized PowerShell functions and scripts for build automation. You can use these to define tasks, execute external applications, assert conditions, manage files, and control the build environment.

Key functional areas include:

• Task Management: Add-BuildTask to define tasks, Invoke-Build.ps1 to run them, and Build-Checkpoint.ps1 for persistent builds.
• Execution & Control: Invoke-BuildExec for running applications with exit code checking, Build-Parallel.ps1 for parallel execution, and Confirm-Build for user prompts.
• Assertions & Validation: Assert-Build for general conditions, Assert-BuildEquals for equality checks, and Test-BuildAsset to verify required assets.
• Environment & Properties: Get-BuildProperty to retrieve session/environment variables, Use-BuildEnv to run scripts with temporary environment changes, and Use-BuildAlias for tool aliasing.
• Output & Logging: Write-Build for colored text output and functions for managing task headers/footers (Set-BuildHeader, Set-BuildFooter).
• File & System Utilities: Remove-BuildItem for deletion, Get-BuildVersion for file versioning, and Resolve-MSBuild.ps1 to locate MSBuild.

The Sub tasks technique allows a root build script (e.g., root.build.ps1) to orchestrate child build scripts located in subdirectories.

In this model, the root script contains standard tasks and two special tasks: build and deploy. These special tasks act as entry points to call specific child scripts (such as deploy/deploy.build.ps1 or src/build.build.ps1).

To invoke a task within a child script, you use the following command structure:

1. The first parameter Tasks specifies either a root task or one of the special tasks (build or deploy).
2. If a special task is chosen, the second parameter SubTasks specifies the specific task to run within that child script.

Note: This technique is OBSOLETE. Consider using the New build script inheritance technique instead.

# Syntax pattern
./root.build.ps1 <SpecialTask> <SubTaskName>

# Example: Running 'task1' inside the 'build' child script
./root.build.ps1 build task1

By default, Build-Checkpoint.ps1 saves and restores build tasks, the script path, and all declared script parameters. However, if you need to persist complex script variables or custom data, you can define custom export and import blocks using Set-BuildData.

• Export Block: Set via Set-BuildData Checkpoint.Export. This block is executed during every task completion to determine what data to save.
• Import Block: Set via Set-BuildData Checkpoint.Import. This block is executed once when resuming, before the task to be resumed starts. It receives the exported data as the $data parameter and runs in the script scope.

Note: The data is serialized via Clixml, so ensure your data types are compatible with XML serialization.

# Define what to save
Set-BuildData Checkpoint.Export {
    $script:var1
    $script:var2
}

# Define how to restore it
Set-BuildData Checkpoint.Import {
    param($data)
    $var1, $var2 = $data
}

Invoke-Build follows a specific lifecycle when executing a build script. When you run a build, the following sequence occurs:

1. Task Selection: The tasks specified by the -Task parameter are selected. If -Task is null, empty, or ., Invoke-Build attempts to run the . task. If . is not defined, it runs the first task added to the script.
2. Condition Checking: The -If parameter is evaluated. If it evaluates to $false, the task is skipped (though it may be run later if called again with a condition that evaluates to $true).
3. Job Ordering: Task jobs are organized. This includes the original jobs from the -Jobs parameter and task references added via Before and After modifiers. Before jobs are inserted before the first script job, and After jobs are appended to the end.
4. Input/Output Evaluation: Before executing script blocks, Invoke-Build compares the files/data specified in the -Inputs and -Outputs parameters. If the outputs are missing or out-of-date compared to the inputs, all script blocks are executed. If they are up-to-date, script blocks are skipped, but referenced tasks are still invoked.

Important Note on Task Reusability: Once a task succeeds or fails, its contribution to the build is complete and it will not be invoked again in the same run. If you need code to run multiple times, define it as a function within the script and call that function from various tasks.