Skip to content

Script Tutorial

Jump to bottom
Roman Kuzmin edited this page Jul 18, 2016 · 61 revisions

Hello World script

    task Hello {
        'Hello, World!'
    }

If the script directory is the current PowerShell location and the script name is .build.ps1 (or *.build.ps1 and it is the only like this there) then it is the default script which can be invoked simply as

    Invoke-Build

If there is no task specified then the default task is invoked which is the "." task if it is defined, otherwise the first added task, Hello in this script.

Build output looks like

Build Hello ...\.build.ps1
Task /Hello
Hello, World!
Done /Hello 00:00:00.01
Build succeeded. 1 tasks, 0 errors, 0 warnings 00:00:00.02

More real script

This script defines three tasks: Build builds a C# project, Clean removes temporary data, and the task "." invokes Build and Clean:

    use 4.0 MSBuild

    # Synopsis: Build the project.
    task Build {
        exec { MSBuild Project.csproj /t:Build /p:Configuration=Release }
    }

    # Synopsis: Remove temp files.
    task Clean {
        Remove-Item bin, obj -Recurse -Force -ErrorAction 0
    }

    # Synopsis: Build and clean.
    task . Build, Clean

Now the command Invoke-Build without parameters invokes the default task "." because it is defined. It builds the project and cleans after that.

Points of interest:

  • use (alias of Use-BuildAlias) is used in order to simplify calls to external tools like MSBuild;
  • exec (alias of Invoke-BuildExec) is used to call an executable and check its exit code;
  • Tasks Build and Clean consist of one script job and do not reference other tasks;
  • The task "." references two other tasks and does not have its own script jobs.
  • The task "." is invoked by default.
  • Help comments # Synopsis: ...

Any combination of defined tasks can be invoked. For example, there is no such a task as RebuildAll in the script. But the equivalent action can be invoked:

    Invoke-Build Clean, Build

Help comments are used for task help shown by the special task ?

PS> Invoke-Build ?

Name  Jobs         Synopsis
----  ----         --------
Build {}           Build the project.
Clean {}           Remove temp files.
.     Build, Clean Build and clean.

Jobs are references and actions

Task jobs are defined by the parameter Jobs with its name often omitted. Jobs are references to other tasks and own script block actions. Jobs are invoked in the specified order.

Unlike in many other task runners, task references do not have to precede own actions. A task may reference tasks that it depends on and also tasks to be invoked after own actions, i.e. continuation tasks.

Examples of tasks with various jobs:

    # Dummy task with no jobs
    task Task1

    # Alias of another task
    task Task2 Task1

    # Combination of tasks
    task Task3 Task1, Task2

    # Simple action task
    task Task4 {
         # action
    }

    # Typical complex task: referenced task(s) and one own action
    task Task5 Task1, Task2, {
         # action after referenced tasks
    }

    # Possible complex task: actions and tasks in any required order
    task Task6 {
         # action before Task1
    },
    Task1, {
         # action after Task1 and before Task2
    },
    Task2, ...

Script parameters for tasks

Build script parameters are standard PowerShell script parameters. They are available for the script code for reading and writing as $var and for all tasks for reading as $var and for writing as $script:var.

Note: script parameters are usual script variables (see later). The only difference is that their values can be specified on invoking a script.

In the previous example the task Build builds the Release configuration. This slightly modified script makes this configurable:

    param(
        $Configuration = 'Release'
    )

    use 4.0 MSBuild

    task Build {
        exec { MSBuild Project.csproj /t:Build /p:Configuration=$Configuration }
    }

The command Invoke-Build Build still builds the Release configuration due to the default script parameter value. But it is now possible to specify and build Debug as well:

    Invoke-Build Build -Configuration Debug

Yes, this is so simple. Script parameters are specified for Invoke-Build, thanks to its dynamic parameters propagated from a build script.

Note that build scripts cannot use parameters reserved for the engine: Task, File, Result, Safe, Summary, Checkpoint, Resume, WhatIf.

Script variables for tasks

Build script variables are standard PowerShell variables in the script scope. Variables are available for the script code for reading and writing as $var and for all tasks for reading as $var and for writing as $script:var.

Example: The variable $Tests is defined in the script scope and available for all tasks, including tasks defined before the variable because tasks are invoked after the whole script is evaluated:

    $Tests = 'SmokeTests.build.ps1', 'MoreTests.build.ps1'

    task Test {
        foreach($_ in $Tests) {
            Invoke-Build * $_
        }
    }

Note: The special task * used in this example invokes all tasks starting from roots of task trees. It is normally used on testing with tests defined as build tasks. Tests are often invoked all together, hence the special task *.

Nested scripts invoked by Invoke-Build have their own script scopes with their own parameters and variables. Parent variables can be accessed, normally for reading. For example, the variable $Tests is available in the parent scope for the nested scripts SmokeTests.build.ps1 and MoreTests.build.ps1.

Tasks may use existing script variables or create new. New script variables are normally created for use in other tasks.

Example: The task Version gets the file version and stores it in the script variable as $script:Version = .... Tasks Zip and NuGet reference this task before their own scripts. Thus, the scripts assume existence of the script variable $Version and use it for package names:

    task Version {
        $script:Version = (Get-Item Project.dll).VersionInfo.FileVersion
    }

    task Zip Version, {
        exec { & 7za a Project.$Version.zip Project.dll }
    }

    task NuGet Version, {
        exec { NuGet pack Project.nuspec -Version $Version }
    }

    task PackAll Zip, NuGet

Tasks are invoked once

This is the main rule of build flows. A task can be referenced by other tasks many times. But as soon as it is invoked, its contribution to a build is over.

When the task PackAll is invoked in the previous example then Version is referenced twice by the tasks scheduled for the build, at first by Zip and then by NuGet. But in fact it is invoked only when Zip calls it.

Build "properties"

Invoke-Build "properties" are usual PowerShell script variables and parameters, like MSBuild properties defined in XML scripts (variables) and properties that come from command lines (parameters), or environment variables.

MSBuild deals with environment variables using the same syntax. In contrast, Invoke-Build scripts do not use environment variables in the same way. They should be referenced explicitly as $env:var or obtained by property. The latter gets a value of session or environment variable or the default. Nulls are treated as not defined, so that property never gets nulls, it fails.

Example: $DevModuleDir or $Configuration may come to the script below in three ways: as script parameters, as variables defined in a parent scope, and as existing environment variables. If nothing is the case then (property DevModuleDir) throws an exception because there is no default value specified. But (property Configuration Release) does not fail, it uses the default value Release.

    param(
        $DevModuleDir = (property DevModuleDir),
        $Configuration = (property Configuration Release)
    )

    task Install {
        Copy-Item Bin/$Configuration/MyModule.dll $DevModuleDir/MyModule
    }

Caution

Build properties should be used sparingly with carefully chosen names which unlikely can exist and be not related to the build. Consider to avoid them in persistent builds because properties rely on external data. On resuming a build these data may be missing or different. Export-Build and Import-Build may be designed to take this into account but it may be easier to avoid properties.

Conditional tasks

The task parameter If specifies a condition, either a value evaluated on creation or a script block evaluated on invocation. If it is present and evaluated to false then the task is not invoked.

In the following example the task MakeHelp is invoked only if the current configuration is Release:

    param(
        $Configuration = 'Release'
    )

    task MakeHelp -If ($Configuration -eq 'Release') {
        ...
    }

    task Build {
        ...
    },
    MakeHelp

Note that the task MakeHelp is still defined even if its condition is not true. Thus, other tasks may refer to it, like the task Build does.

If the variable $Configuration is supposed to change during the build and the task depends on its current value then a script block should be used instead:

    task MakeHelp -If {$Configuration -eq 'Release'} {
        ...
    }

If a condition is a script block and a task is called more than once then it is possible that it is skipped at first due to its condition evaluated to false but still invoked later when its condition gets true.

Safe task references and errors

If a task throws an exception or writes a terminating error then the whole build fails unless the task is referenced as safe (job Task -Safe) by the calling task and all other tasks having a chance to be invoked in this build.

The helper error (alias of Get-BuildError) is used in order to get errors of tasks called safe. Note that error is useless with unsafe references because the whole build stops on failures.

In this example Task2 calls Task1 safe and then analyses its errors:

    task Task1 {
        # code with potential failures
        ...
    }

    task Task2 (job Task1 -Safe), {
        if (error Task1) {
            # Task1 failed
            ...
        }
        else {
            # Task1 succeeded
            ...
        }
    }

Task jobs altered by other tasks

The task parameters After and Before are used in order to alter build task jobs in special cases, for example if a build script is imported (dot-sourced) and its direct changes are not suitable.

    task Build {
        # original Build code
    }

    task BeforeBuild -Before Build {
        # when Build is called this code is invoked before it
    }

    task AfterBuild -After Build {
        # when Build is called this code is invoked after it
    }

When the build engine preprocesses tasks the task Build is transformed into a task which is equivalent to this:

    task Build BeforeBuild, <original task jobs>, AfterBuild

Incremental Tasks

Other task parameters Inputs, Outputs, and the switch Partial are used in order to define incremental and partial incremental tasks. These techniques are described in here:

Helpers

Appendix

Clone this wiki locally