Special Variables

The following variable names are reserved by the build engine: $WhatIf, $BuildRoot, $BuildFile, $BuildTask, $Task, and variables ${*...}. Scripts should not create such variables (including script parameters) and should not change existing, except $BuildRoot in special cases.

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 is used by scripts in order to skip some actions. It is not used in tasks and other user code, because they are not invoked when 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 ? or ??.

---

$BuildRoot

By default it is the full path of the build script directory. Build scripts are allowed to alter it on loading 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, still the original $BuildRoot by default.
    $BuildRoot = $BuildRoot
)

# Alter the build root.
if (<something>) {
    $BuildRoot = ...
}

# Tasks are called with the current location set to $BuildRoot,
# either the default, or set by the parameter, or the altered.

task ...

It is fine to specify a path relative to the current location, the original or changed by the script. Immediately after loading, $BuildRoot is resolved to the full path with respect to the current location, tested, and made constant. The latter means that $BuildRoot cannot be changed during the build, i.e. from tasks of other build blocks.

Example:

# change the location to the parent directory and adjust the build root
Set-Location ..
$BuildRoot = '.'

# tasks work with the new root resolved to full and maintained current
task ShowRoot {
    # these two should be the same:
    $BuildRoot
    (Get-Location).Path
}

---

$BuildFile

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

---

$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 only.

---

$Task

It is the current task being processed. It is available for script blocks defined by parameters If, Inputs, Outputs, Jobs and by blocks Enter|Exit-BuildTask, Enter|Exit-BuildJob, Set-BuildHeader.

The following properties are available for reading:

• Name - task name, [string]
• Started - start time, [DateTime]
• In Exit-BuildTask only:
  • Error - an error stopped the task
  • Elapsed - task duration, [TimeSpan]

---

Variables and functions *...

Function and variable names starting with * are reserved for the engine. For technical reasons they cannot be completely hidden from scripts. Scripts should not use functions and variables with such names. It is unlikely that they ever do this but this is possible and should be avoided.