How Build Works

Invoke-Build invokes the build script specified by the parameter File with Parameters and the current location set to the script directory. The script does whatever is coded there but the goal is to define parameters, set script variables, and add at least one build task (task). Note: if the script does anything else then it can check for the build variable $WhatIf and skip some jobs if its value is true.

Then Invoke-Build invokes the tasks and their jobs as follows:

1. Tasks specified by the parameter Task are invoked. If the parameter is not specified or is null or empty then the . task is invoked if it is defined, otherwise the first added task is invoked.

2. The task parameter If is checked. If it is present and evaluates to false then the task is skipped. It still may be invoked later if it is called again and If evaluates to true that time.

3. The task jobs are invoked, that is dependent tasks and own scripts in the specified order. The jobs are the original jobs defined by the parameter Jobs and task references added by other tasks using Before and After. Before tasks are inserted before the first script job. After tasks are inserted after the last script job. If a task has no own script jobs then extra tasks are added to the end.

4. Before the first own script job is invoked, the inputs and outputs from the parameters Incremental or Partial are evaluated and compared. If they are not specified or outputs are out-of-date then all script jobs are invoked. Otherwise all scripts are skipped, only referenced tasks are invoked.

Before any kind of task script is invoked, the current location is set to the build script directory $BuildRoot. Scripts may change it and they do not have to care of restoring it.

As soon as a task gets invoked and succeeds or fails, its contribution to the current build is over, the task itself and its parts are never invoked again.

If a task throws an exception or writes a terminating error then the whole build fails unless the task is referenced as protected (@{Task = 1}) by the calling task and all other tasks having a chance to be invoked in this build.

The default $ErrorActionPreference for each build scripts is set to Stop, otherwise it is too easy to miss actually terminating errors. But scripts can change it at the script level once for all their tasks.