Special Variables

The following variable names are reserved by the build engine: WhatIf, BuildRoot, BuildFile, BuildTask, *. Scripts should not create such variables (including script parameters) and normally should not change existing.

The special variable $_ can be defined by the engine and visible. Scripts and tasks can use it as their own, that is assign at first and then use. They must not make any assumptions about its incoming value unless it is a special case.

$WhatIf

It is the parameter WhatIf of Invoke-Build.ps1. It can be used for reading in scripts, not tasks. This makes sense when a build script not just adds tasks but does something else that should be avoided if $WhatIf is true.

$WhatIf is true in the following cases:

• The switch WhatIf is present on Invoke-Build invocation;
• Invoke-Build is invoked with the special task ? (show/get task list without invoking).

$BuildRoot

By default it is the full path of the build script directory. Build scripts are allowed to alter it in special cases, for example:

• It is not suitable to keep a build script in a directory where it works.
• A build script is designed to work for several or variable directories.

Example:

param
(
    # Custom build root. Let it still be $BuildRoot by default.
    $WorkingDirectory = $BuildRoot
)

# Alter the build root. Make sure it is the resolved provider path.
$BuildRoot = Convert-Path (Resolve-Path -LiteralPath $WorkingDirectory)

task ... # It is called with the current location set to the altered root

$BuildFile

It is the full path of the build script. It can be used for reading.

$BuildTask

It is the list of initial tasks being invoked. Normally it is the value of the parameter Task of Invoke-Build.ps1. It can be used for reading.

${*}

This variable is strictly for the build engine. For technical reasons it is not private and therefore it is exposed to scripts. But it should not be used by scripts and tasks, even for reading.

Other Variables

The engine uses more variables. All of them are private and their names start with '-'. Scripts and tasks should not use such variables (${-...}). It is unlikely that they ever do but this is still possible and should be avoided.