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 some 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 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. Make sure it is the full path.
    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 ...

---

$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 the task script blocks defined by parameters If, Inputs, Outputs, Jobs and the event functions Enter|Exit-BuildTask and Enter|Exit-BuildJob.

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.

---