Persistent Builds

Long running or interactive processes with expected interruptions can be automated with persistent builds that can be resumed after interruptions.

Starting Persistent Builds

In order to make a build persistent use the parameter Persist and provide a file path where checkpoints are stored after each completed task. In addition provide at least one of the parameters Task, File, or Parameters even with default values. Otherwise the build resumes instead of starting. For example, this command starts a persistent build with the task ., the default build file, and no parameters:

Invoke-Build . -Persist checkpoint.clixml

Note that the . task is the default but it cannot be omitted in this example because in such a case the build resumes, not starts.

Resuming Persistent Builds

In order to resume an interrupted build use the same parameter Persist with an existing file which was created by a previously interrupted build. Do not use any of Task, File, or Parameters because these data are restored from the specified file. For example, this command resumes the build from the existing checkpoint file:

Invoke-Build -Persist checkpoint.clixml

Preparing Build Scripts For Persistent Builds

Scripts which do not set data used by tasks (script parameters, script scope variables, global variables, etc.) are normally ready for persistent builds. Other scripts have to define two functions Export-Build and Import-Build.

Export-Build is called after each task of a persistent build. It outputs data to be exported to a checkpoint file. Import-Build is called once on resuming of a persistent build. Its single argument contains the original data imported from a checkpoint file. Import-Build restores these data. Note that it is called in the script scope, so that for restoring script scope variables it does not even have to use the variable prefix script.

For example, a script uses two variables Version and Archive which are calculated by the task SetVariables:

task SetVariables {
    $script:Version = ...
    $script:Archive = ...
}

Other tasks depend on this task and use these variables assuming they are set. If a persistent build is interrupted after SetVariables then on resuming the build the variables will not be set. Export-Build and Import-Build solve the problem:

function Export-Build {
    $Version
    $Archive
}

function Import-Build {
    $Version, $Archive = $args[0]
}

Note that script parameters are also variables in the script scope. But they have to be exported and imported only if they are changed during the build or their default values are calculated by not constant expressions, for example, by calling the function Get-BuildProperty (alias property).