Invoke-Build-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns="http://msh" schema="maml">
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Invoke-Build.ps1</command:name>
<maml:description>
<maml:para>Invoke-Build - Build Automation in PowerShell</maml:para>
</maml:description>
</command:details>
<maml:description>
<maml:para>The command invokes specified and referenced tasks defined in a PowerShell
script. The process is called build and the script is called build script.
 
A build script defines parameters, variables, tasks, and events. Any code
is invoked with the current location set to $BuildRoot, the build script
directory. $ErrorActionPreference is set to &apos;Stop&apos;.
 
To get help for commands dot-source Invoke-Build:
 
    PS&gt; . Invoke-Build
    PS&gt; help task -full
 
RESERVED FUNCTION AND VARIABLE NAMES
 
Function and variable names starting with &apos;*&apos; are reserved for the engine.
Scripts should not use functions and variables with such names.
 
EXPOSED FUNCTIONS AND ALIASES
 
Scripts should use available aliases instead of function names.
 
    Add-BuildTask (task)
    Assert-Build (assert)
    Assert-BuildEquals (equals)
    Get-BuildError (error)
    Get-BuildProperty (property)
    Get-BuildVersion
    Invoke-BuildExec (exec)
    New-BuildJob (job)
    Use-BuildAlias (use)
    Write-Build
    Write-Warning [1]
    Get-BuildFile [2]
 
[1] Write-Warning is redefined internally in order to count warnings in
tasks, build, and other scripts. But warnings in modules are not counted.
 
[2] Exists only as a pattern for wrappers.
 
SPECIAL ALIASES
 
    Invoke-Build
    Invoke-Builds
 
These aliases are for the scripts Invoke-Build.ps1 and Invoke-Builds.ps1.
Use them for calling nested builds, i.e. omit script extensions and paths.
With this rule Invoke-Build tools can be kept together with build scripts.
 
EXPOSED VARIABLES
 
Exposed variables designed for build scripts and tasks:
 
    $WhatIf - WhatIf mode, Invoke-Build parameter
    $BuildRoot - build script location
    $BuildFile - build script path
    $BuildTask - initial tasks
    $Task - current task
 
$Task 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.
 
    $Task properties available for reading:
 
    - Name - [string], task name
    - Jobs - [object[]], task jobs
    - Started - [DateTime], task start time
 
    In Exit-BuildTask
    - Error - error which stopped the task
    - Elapsed - [TimeSpan], task duration
 
The variable $_ may be exposed. In special cases it is used as an input.
In other cases build scripts should not assume anything about its value.
 
EVENT FUNCTIONS
 
The build engine defines and calls the following empty functions:
 
    Enter-Build - before all tasks
    Exit-Build - after all tasks
 
    Enter-BuildTask - before each task
    Exit-BuildTask - after each task
 
    Enter-BuildJob - before each task script job
    Exit-BuildJob - after each task script job
 
    Export-Build - on saving persistent build checkpoints
    Import-Build - once on resuming of a persistent build
 
A script can redefine them. Note that nested builds do not inherit events,
the engine always defines new empty functions before invoking a new script.
 
Events are not called on WhatIf. If Enter-* is called then its pair Exit-*
is called, too. Events are suitable for initializing, cleaning, logging.
 
Enter-Build and Exit-Build are invoked in the script scope. Enter-Build is
a good place for heavy initialization, it does not have to care of WhatIf.
Also, unlike the top level script code, Enter-Build can output/log data.
 
Enter-BuildTask, Exit-BuildTask, Enter-BuildJob, and Exit-BuildJob are
invoked in the same scope, the parent of a task. *Job functions take a
single argument, the job number.
 
Export-Build and Import-Build are used with persistent builds. Export-Build
outputs data to be exported to clixml. Import-Build is called with a single
argument containing the original data imported from clixml. It is called in
the script scope and normally restores script scope variables. Note that
this is not needed for script parameters, the engine takes care of them.
Variables may be declared as parameters just in order to be persistent.
 
DOT-SOURCING Invoke-Build
 
Build-like environment can be imported to normal scripts:
 
    . Invoke-Build [&lt;root&gt;]
 
When this command is invoked from a script it
 
- sets $ErrorActionPreference to Stop
- sets $BuildFile to the invoked script path
- sets $BuildRoot to the script directory or &lt;root&gt;
- sets the current PowerShell location to $BuildRoot
- imports utility commands
    - assert
    - equals
    - exec
    - property
    - use
    - Write-Build
 
Some other build commands are also imported. They are available for getting
help and not designed for use in normal scripts.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Invoke-Build.ps1</maml:name>
<command:parameter required="false" position="1" >
<maml:name>Task</maml:name>
<command:parameterValue required="true">String[]</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>File</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="3" >
<maml:name>Parameters</maml:name>
<command:parameterValue required="true">Hashtable</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Checkpoint</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Result</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Resume</maml:name>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Safe</maml:name>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Summary</maml:name>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>WhatIf</maml:name>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>Task</maml:name>
<maml:description>
<maml:para>One or more tasks to be invoked. If it is not specified, null, empty,
or equal to &apos;.&apos; then the task &apos;.&apos; is invoked if it exists, otherwise
the first added task is invoked.
 
Names with wildcard characters are reserved for special tasks.
 
SPECIAL TASKS
 
? - Tells to list the tasks with brief information without invoking. It
also checks tasks and throws errors on missing or cyclic references.
Task synopsis is defined in preceding comments as # Synopsis: ...
 
?? - Tells to collect and get all tasks as an ordered dictionary. It
can be used by external tools for analysis, TabExpansion, and etc.
 
Tasks ? and ?? set $WhatIf to true. Properly designed build scripts
should not perform anything significant if $WhatIf is set to true.
 
* - Tells to invoke all tasks. This is useful when all tasks are tests
or steps in a sequence that can be stopped and resumed, see Checkpoint.
 
** - Invokes * for all files *.test.ps1 found recursively in the
current directory or a directory specified by the parameter File.
Other parameters except Result and Safe are ignored.
 
Tasks ? and ?? can be combined with **
?, ** - To show all test tasks without invoking.
??, ** - To get task dictionaries for all test files.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>File</maml:name>
<maml:description>
<maml:para>A build script which defines tasks by the alias &apos;task&apos; (Add-BuildTask).
 
If it is not specified then Invoke-Build looks for *.build.ps1 files in
the current location. A single file is used as the script. If there are
more files then .build.ps1 is used.
 
If the build file is not found then a script defined by the environment
variable InvokeBuildGetFile is called with the path as an argument. It
may get a non standard build file. The full path should be returned.
 
If the file is still not defined then parent directories are searched.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="3" >
<maml:name>Parameters</maml:name>
<maml:description>
<maml:para>A hashtable of parameters passed in the build script. It is needed only
in special cases. Normally build script parameters may be specified for
Invoke-Build itself, thanks to PowerShell dynamic parameters.
 
Dynamic parameters and the hashtable Parameters are not used together.
If build script parameters conflict with Invoke-Build parameters then
the hashtable Parameters is the only way to pass them in the script.
 
Build scripts define parameters using standard syntax. Parameters are
shared between tasks: for reading as $ParameterName, for writing as
$script:ParameterName.
 
Build script parameters are automatically exported and imported by the
engine on persistent builds, see Checkpoint.
 
NOTE: Dynamic switches must be specified after positional arguments of
Task and File if they are used with omitted parameter names. Otherwise
switches swallow these arguments and make a command incorrect.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Checkpoint</maml:name>
<maml:description>
<maml:para>Specifies the checkpoint file and makes the build persistent. It is
possible to resume an interrupted build starting at the interrupted
task. The checkpoint file is written before processing of each task
and deleted if the build succeeds.
 
In order to resume an interrupted persistent build specify the same
checkpoint file and the switch Resume. Task, File, Parameters are
ignored, their values are restored from the file.
 
Persistent builds must be designed properly. Data shared by tasks are
exported and imported by the functions Export-Build and Import-Build.
 
Note that this is not needed for script parameters, the engine takes
care of them. Some variables may be declared as parameters simply in
order to be persistent and custom export and import may be avoided.
 
Notes
- Think carefully of what the persistent build state is.
- Some data are not suitable for persistence in clixml files.
- Changes in stopped build scripts may cause incorrect resuming.
- Checkpoint files must not be used with different engine versions.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Result</maml:name>
<maml:description>
<maml:para>Tells to output build information using a variable. It is either a name
of variable to be created or any object with the property Value to be
assigned (e.g. [ref] or [hashtable]).
 
Result object properties:
 
    All - all defined tasks
    Error - a terminating build error
    Tasks - invoked tasks including nested
    Errors - error objects including nested
    Warnings - warning messages including nested
 
Tasks is a list of objects:
 
    Name - task name
    Jobs - task jobs
    Error - task error
    Started - start time
    Elapsed - task duration
    InvocationInfo - task location (.ScriptName and .ScriptLineNumber)
 
Errors is a list of objects:
 
    Error - original error record
    File - current $BuildFile
    Task - current $Task or null for non-task errors
 
Warnings is a list of objects:
 
    Message - warning message
    File - current $BuildFile
    Task - current $Task or null for non-task warnings
 
These data should be used for reading only.
Other result and task data should not be used.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Resume</maml:name>
<maml:description>
<maml:para>Tells to resume an interrupted persistent build from a checkpoint file
specified by Checkpoint. Task, File, and Parameters are ignored, their
values are restored from the file.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Safe</maml:name>
<maml:description>
<maml:para>Tells to catch a build failure, store an error as the property Error of
Result and return quietly. A caller should use Result and check Error.
 
Some exceptions are possible even in the safe mode. They show serious
errors, not build failures. For example, a build script is missing.
 
When Safe is used together with the special task ** (invoke *.test.ps1)
then task failures stop current test scripts, not the whole testing.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Summary</maml:name>
<maml:description>
<maml:para>Tells to show summary information after the build. It includes task
durations, names, locations, and error messages.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>WhatIf</maml:name>
<maml:description>
<maml:para>Tells to show preprocessed tasks and their scripts instead of invoking
them. If a script does anything but adding and configuring tasks then
it should check for $WhatIf and skip some significant actions.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Text</maml:name>
</dev:type>
<maml:description>
<maml:para>Build process log which includes task starts, ends with durations,
warnings, errors, and output of tasks and commands that they invoke.
 
Output is expected from tasks and event functions. But build scripts
should not output anything. Unexpected output is shown as a warning,
in the future it may be treated as an error.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code># Invoke the default task (&apos;.&apos; or the first added) in the default script
# (a single file like *.build.ps1 or .build.ps1 if there are two or more)
 
Invoke-Build</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title>
<dev:code># Invoke tasks Build and Test from the default script with parameters.
# The script defines parameters Log and WarningLevel by &apos;param&apos; as usual.
 
Invoke-Build Build, Test -Log log.txt -WarningLevel 4</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title>
<dev:code># Show tasks in the default script and the specified script
 
Invoke-Build ?
Invoke-Build ? Project.build.ps1
 
# Custom formatting is possible, too
 
Invoke-Build ? | Format-Table -AutoSize
Invoke-Build ? | Format-List Name, Synopsis</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title>
<dev:code># Get task names without invoking for listing, TabExpansion, etc.
 
$all = Invoke-Build ??
$all.Keys</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title>
<dev:code># Invoke all in Test1.test.ps1 and all in Tests\...\*.test.ps1
 
Invoke-Build * Test1.test.ps1
Invoke-Build ** Tests</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 6 --------------------------</maml:title>
<dev:code># Invoke a persistent sequence of steps defined as tasks
Invoke-Build * Steps.build.ps1 -Checkpoint temp.clixml
 
# Resume the above steps at the stopped one
Invoke-Build -Checkpoint temp.clixml -Resume</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 7 --------------------------</maml:title>
<dev:code># Using the build results, e.g. for performance analysis
 
# Invoke the build and keep results in the variable Result
Invoke-Build -Result Result
 
# Show invoked tasks ordered by Elapsed with ScriptName included
$Result.Tasks |
Sort-Object Elapsed |
Format-Table -AutoSize Elapsed, @{
    Name = &apos;Task&apos;
    Expression = {$_.Name + &apos; @ &apos; + $_.InvocationInfo.ScriptName}
}</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 8 --------------------------</maml:title>
<dev:code># Using the build results, e.g. for tasks summary
 
try {
    # Invoke the build and keep results in the variable Result
    Invoke-Build -Result Result
}
finally {
    # Show task summary information after the build
    $Result.Tasks | Format-Table Elapsed, Name, Error -AutoSize
}</dev:code>
</command:example>
</command:examples>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Wiki</maml:linkText>
<maml:uri>https://github.com/nightroman/Invoke-Build/wiki</maml:uri>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Project</maml:linkText>
<maml:uri>https://github.com/nightroman/Invoke-Build</maml:uri>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Add-BuildTask (task)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Assert-Build (assert)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Assert-BuildEquals (equals)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-BuildError (error)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-BuildProperty (property)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Invoke-BuildExec (exec)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>New-BuildJob (job)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Use-BuildAlias (use)</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Write-Build</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Add-BuildTask</command:name>
<maml:description>
<maml:para>Defines a build task and adds it to the internal task list.</maml:para>
</maml:description>
<command:verb>Add</command:verb>
<command:noun>BuildTask</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;task&apos;. This is the main feature of build scripts. At
least one task must be added. Normally it is used in the build script scope
but it can be called anywhere, e.g. imported, created dynamically, and etc.
 
In fact, this function is literally all that build scripts really need.
Other build functions are just helpers, scripts do not have to use them.
 
Task help-comments are special comments preceding task definitions
 
    # Synopsis: ...
    task ...
 
Synopsis lines are used in task information returned by the command
 
    Invoke-Build ?</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Add-BuildTask</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Jobs</maml:name>
<command:parameterValue required="true">Object[]</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>After</maml:name>
<command:parameterValue required="true">Object[]</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Before</maml:name>
<command:parameterValue required="true">Object[]</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Data</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Done</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>If</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Inputs</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Outputs</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Source</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Partial</maml:name>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<maml:description>
<maml:para>The task name. Wildcard characters are deprecated. Duplicated names are
allowed, each added task overrides previously added with the same name.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Jobs</maml:name>
<maml:description>
<maml:para>Specifies the task jobs. Jobs are other task references and own
actions. Any number of jobs is allowed. Jobs are invoked in the
specified order.
 
Valid job types are:
 
    [string] - simple reference, an existing task name
    [object] - advanced reference created by &apos;job&apos; (New-BuildJob)
    [scriptblock] - action, a script block invoked for this task</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>After</maml:name>
<maml:description>
<maml:para>Tells to add this task to the end of the specified task job lists.
 
Altered tasks are defined as by their names or by the command &apos;job&apos;.
In the latter case options are applied to the added task reference.
 
Parameters After and Before are used in order to alter task jobs in
special cases when direct changes in task source code are not suitable.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Before</maml:name>
<maml:description>
<maml:para>Tells to add this task to job lists of the specified tasks. It is
inserted before the first script job, if any, or added to the end.
Note that Before tasks are added before After tasks.
 
See After for details.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Data</maml:name>
<maml:description>
<maml:para>Any object attached to the task. It is not used by the engine.
When the task is invoked the object is available as $Task.Data.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Done</maml:name>
<maml:description>
<maml:para>Specifies the command or a script block invoked when the task is done.
It is mostly designed for wrapper functions creating special tasks.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>If</maml:name>
<maml:description>
<maml:para>Specifies the optional condition to be evaluated. If the condition
evaluates to false then the task is not invoked.
 
The value is a script block evaluated on task invocation or an object
treated as Boolean on definition. On WhatIf a script block is treated
as true without invocation.
 
If the task is called several times then it is possible that the task
is skipped at first but invoked later when the script block gets true.</maml:para>
</maml:description>
<dev:defaultValue>$true</dev:defaultValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Inputs</maml:name>
<maml:description>
<maml:para>Specifies the input items, tells to process the task as incremental,
and requires the parameter Outputs with the optional switch Partial.
 
Inputs are file items or paths or a script block which gets them.
Outputs are file paths or a script block which gets them.
 
Automatic variables for incremental task script jobs:
 
    $Inputs - full input paths, array of strings
    $Outputs - result of the evaluated parameter Outputs
 
With the switch Partial the task is processed as partial incremental.
There must be one-to-one correspondence between Inputs and Outputs.
 
Partial Outputs are file paths or a script block which is invoked with
input paths piped to it in order to transform them into output paths.
 
In addition to automatic variables $Inputs and $Outputs, inside
process{} blocks of a partial task two more variables are defined:
 
    $_ - current full input path
    $2 - current output path
 
See also wiki topics about incremental tasks:
https://github.com/nightroman/Invoke-Build/wiki</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Outputs</maml:name>
<maml:description>
<maml:para>Specifies the output paths of the incremental task. It is used together
with Inputs. See Inputs for details.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Partial</maml:name>
<maml:description>
<maml:para>Tells to process the incremental task as partial incremental. It is
used together with Inputs and Outputs. See Inputs for details.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Source</maml:name>
<maml:description>
<maml:para>Specifies the task source. It is used by wrapper functions in order to
provide the actual source for location messages and task help synopsis.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>New-BuildJob</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-BuildError</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:uri>https://github.com/nightroman/Invoke-Build/wiki</maml:uri>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>New-BuildJob</command:name>
<maml:description>
<maml:para>Creates a new task reference with options.</maml:para>
</maml:description>
<command:verb>New</command:verb>
<command:noun>BuildJob</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;job&apos;. It is called on job list creation for a task.
It creates a reference to another task with options. The only used option
is the switch Safe.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>New-BuildJob</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Safe</maml:name>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<maml:description>
<maml:para>The referenced task name.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Safe</maml:name>
<maml:description>
<maml:para>Tells to create a safe task job. If the referenced task fails the build
continues if this task is safe everywhere in the current build. Other
tasks use &apos;error&apos; (Get-BuildError) in order to check for errors.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Object</maml:name>
</dev:type>
<maml:description>
<maml:para>A new job used as an argument on task creation.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Get-BuildError</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Get-BuildError</command:name>
<maml:description>
<maml:para>Gets an error of the specified task if the task has failed.</maml:para>
</maml:description>
<command:verb>Get</command:verb>
<command:noun>BuildError</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;error&apos;. It is used when some tasks are referenced
safe (job Task -Safe) in order to get and analyse their potential errors.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Get-BuildError</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Task</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Task</maml:name>
<maml:description>
<maml:para>Name of the task which error is requested.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Error</maml:name>
</dev:type>
<maml:description>
<maml:para>The error object or null if the task has no errors.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Add-BuildTask</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>New-BuildJob</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Assert-Build</command:name>
<maml:description>
<maml:para>Checks for a condition.</maml:para>
</maml:description>
<command:verb>Assert</command:verb>
<command:noun>Build</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;assert&apos;. This command checks for a condition and if
it is not true throws an error with the default or a specified message.
 
NOTE: Consider to use &apos;equals X Y&apos; instead of &apos;assert (X -eq Y)&apos;. It is
easier to type, it avoids subtle PowerShell conversions, and its error
message is more informative.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Assert-Build</maml:name>
<command:parameter required="false" position="1" >
<maml:name>Condition</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Message</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>Condition</maml:name>
<maml:description>
<maml:para>The condition.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Message</maml:name>
<maml:description>
<maml:para>An optional message describing the assertion condition.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Assert-BuildEquals</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Assert-BuildEquals</command:name>
<maml:description>
<maml:para>Verifies that two specified objects are equal.</maml:para>
</maml:description>
<command:verb>Assert</command:verb>
<command:noun>BuildEquals</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;equals&apos;. This command verifies that two specified
objects are equal using [Object]::Equals(). If objects are not equal the
command fails with a message showing object values and types.
 
NOTE: Comparison of strings is case sensitive. For case insensitive
comparison use &apos;assert (X -eq Y)&apos;.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Assert-BuildEquals</maml:name>
<command:parameter required="false" position="1" >
<maml:name>A</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>B</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>A</maml:name>
<maml:description>
<maml:para>The first object.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>B</maml:name>
<maml:description>
<maml:para>The second object.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Assert-Build</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Get-BuildProperty</command:name>
<maml:description>
<maml:para>Gets the session or environment variable or the default value.</maml:para>
</maml:description>
<command:verb>Get</command:verb>
<command:noun>BuildProperty</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;property&apos;. It gets the first not null value of these
three: session variable, environment variable, optional default value.
Otherwise an error is thrown.
 
CAUTION: Properties should be used sparingly with carefully chosen names
that unlikely can already exist and be not related to the build script.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Get-BuildProperty</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Value</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Name</maml:name>
<maml:description>
<maml:para>Session or environment variable name.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Value</maml:name>
<maml:description>
<maml:para>Specifies the default value to be used if the variable is not found.
Omitted or null values require the variable to exist and be not null.
Otherwise an error is thrown.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Object</maml:name>
</dev:type>
<maml:description>
<maml:para>Requested property value.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code># Inherit an existing value or throw an error
 
$OutputPath = property OutputPath</dev:code>
</command:example>
<command:example>
<maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title>
<dev:code># Get an existing value or use the default
 
$WarningLevel = property WarningLevel 4</dev:code>
</command:example>
</command:examples>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Get-BuildVersion</command:name>
<maml:description>
<maml:para>Gets the current Invoke-Build version.</maml:para>
</maml:description>
<command:verb>Get</command:verb>
<command:noun>BuildVersion</command:noun>
</command:details>
<maml:description>
<maml:para>Gets the current Invoke-Build version.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Get-BuildVersion</maml:name>
</command:syntaxItem>
</command:syntax>
<command:parameters>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>System.Version</maml:name>
</dev:type>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code>assert ((Get-BuildVersion).Major -ge 2)</dev:code>
<dev:remarks>
<maml:para>This command works like `require version`. Use it as the first command in a
build script in order to ensure that the script is being built by a proper
engine (version 2+ in this example).</maml:para>
</dev:remarks>
</command:example>
</command:examples>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Invoke-BuildExec</command:name>
<maml:description>
<maml:para>Invokes an application and checks $LastExitCode.</maml:para>
</maml:description>
<command:verb>Invoke</command:verb>
<command:noun>BuildExec</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;exec&apos;. It invokes the specified script block which
is supposed to call an executable. Then $LastExitCode is checked. If it
does not fit to the specified values (0 by default) an error is thrown.
 
It is often used with .NET tools, e.g. MSBuild. See Use-BuildAlias.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Invoke-BuildExec</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Command</maml:name>
<command:parameterValue required="true">ScriptBlock</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>ExitCode</maml:name>
<command:parameterValue required="true">Int32[]</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Command</maml:name>
<maml:description>
<maml:para>Command that invokes an executable which exit code is checked. It must
invoke an application directly (.exe) or not (.cmd, .bat), otherwise
$LastExitCode is not set or contains an exit code of another command.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>ExitCode</maml:name>
<maml:description>
<maml:para>Valid exit codes (e.g. 0..3 for robocopy).</maml:para>
</maml:description>
<dev:defaultValue>@(0)</dev:defaultValue>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Objects</maml:name>
</dev:type>
<maml:description>
<maml:para>Output of the specified command.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code># Call robocopy (0..3 are valid exit codes)
 
exec { robocopy Source Target /mir } (0..3)</dev:code>
</command:example>
</command:examples>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Use-BuildAlias</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Use-BuildAlias</command:name>
<maml:description>
<maml:para>Sets framework/directory tool aliases.</maml:para>
</maml:description>
<command:verb>Use</command:verb>
<command:noun>BuildAlias</command:noun>
</command:details>
<maml:description>
<maml:para>Scripts use its alias &apos;use&apos;. Invoke-Build does not change the system path
in order to make framework tools available by names. This is not suitable
for using mixed framework tools (in different tasks, scripts, parallel
builds). Instead, this function is used for setting tool aliases in the
scope where it is called from.
 
This function is often called from a build script and all tasks use script
scope aliases. But it can be called from tasks in order to use more tools
including other framework or tool directories.
 
MSBuild is one of frequently used tools. Examples:
 
    use * MSBuild
    use 4.0 MSBuild
    use Framework\v2.0.50727 MSBuild</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Use-BuildAlias</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Name</maml:name>
<command:parameterValue required="true">String[]</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<maml:description>
<maml:para>Specifies the tools directory.
 
If it is * or it starts with digits followed by a dot then the MSBuild
version and the path is taken from the registry. The * is used for the
latest available version.
 
If it is like Framework* then it is assumed to be a path relative to
Microsoft.NET in the Windows directory.
 
Otherwise it is a full or relative literal path of any directory.
 
Examples: *, 4.0, Framework\v4.0.30319, .\Tools</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Name</maml:name>
<maml:description>
<maml:para>Tool names to set aliases for. These names also become aliases and they
should be used later exactly as specified in here.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code># Use .NET 4.0 tools MSBuild, csc, ngen. Then call MSBuild.
 
use 4.0 MSBuild, csc, ngen
exec { MSBuild Some.csproj /t:Build /p:Configuration=Release }</dev:code>
</command:example>
</command:examples>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Invoke-BuildExec</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Write-Build</command:name>
<maml:description>
<maml:para>Writes text using colors if they are supported.</maml:para>
</maml:description>
<command:verb>Write</command:verb>
<command:noun>Build</command:noun>
</command:details>
<maml:description>
<maml:para>This function is used in order to output colored text, e.g. to a console.
Unlike Write-Host it is suitable for redirected output, e.g. to a file.
If the current host does not support colors then just text is written.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Write-Build</maml:name>
<command:parameter required="false" position="1" >
<maml:name>Color</maml:name>
<command:parameterValue required="true">ConsoleColor</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Text</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>Color</maml:name>
<maml:description>
<maml:para>[System.ConsoleColor] value or its string representation.</maml:para>
<maml:para>Values : Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>Text</maml:name>
<maml:description>
<maml:para>Text to be printed using colors if they are supported.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>String</maml:name>
</dev:type>
</command:returnValue>
</command:returnValues>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Get-BuildFile</command:name>
<maml:description>
<maml:para>Gets full path of the default build file in a directory.</maml:para>
</maml:description>
<command:verb>Get</command:verb>
<command:noun>BuildFile</command:noun>
</command:details>
<maml:description>
<maml:para>This function is not designed for build scripts and tasks. It is used
internally and exists only as a pattern to follow for wrapper scripts.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Get-BuildFile</maml:name>
<command:parameter required="false" position="1" >
<maml:name>Path</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>Path</maml:name>
<maml:description>
<maml:para>A full directory path used to get the default build file.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>String</maml:name>
</dev:type>
</command:returnValue>
</command:returnValues>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Invoke-Builds.ps1</command:name>
<maml:description>
<maml:para>Invokes parallel builds by Invoke-Build.ps1</maml:para>
</maml:description>
</command:details>
<maml:description>
<maml:para>This script invokes build scripts simultaneously using Invoke-Build.ps1
which has to be in the same directory. Number of simultaneous builds is
limited by the number of processors by default.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Invoke-Builds.ps1</maml:name>
<command:parameter required="false" position="1" >
<maml:name>Build</maml:name>
<command:parameterValue required="true">Hashtable[]</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>MaximumBuilds</maml:name>
<command:parameterValue required="true">Int32</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Result</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Timeout</maml:name>
<command:parameterValue required="true">Int32</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" position="1" >
<maml:name>Build</maml:name>
<maml:description>
<maml:para>Build parameters defined as hashtables with these keys/data:
 
    Task, File, Parameters - Invoke-Build.ps1 parameters
    Log - Tells to write build output to the specified file
 
Any number of builds is allowed, including 0 and 1. The maximum number
of parallel builds is the number of processors by default. It can be
changed by the parameter MaximumBuilds.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>MaximumBuilds</maml:name>
<maml:description>
<maml:para>Maximum number of builds invoked at the same time.</maml:para>
</maml:description>
<dev:defaultValue>Number of processors.</dev:defaultValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Result</maml:name>
<maml:description>
<maml:para>Tells to output build results using a variable. It is either a name of
variable to be created for results or any object with the property
Value to be assigned ([ref], [hashtable]).
 
Result properties:
 
    Tasks - tasks (*)
    Errors - errors (*)
    Warnings - warnings (*)
    Started - start time
    Elapsed - build duration
 
(*) see: help Invoke-Build -Parameter Result</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Timeout</maml:name>
<maml:description>
<maml:para>Maximum overall build time in milliseconds.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>Text</maml:name>
</dev:type>
<maml:description>
<maml:para>Output of invoked builds and other log messages.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code>Invoke-Builds @(
    @{File=&apos;Project1.build.ps1&apos;}
    @{File=&apos;Project2.build.ps1&apos;; Task=&apos;MakeHelp&apos;}
    @{File=&apos;Project2.build.ps1&apos;; Task=&apos;Build&apos;, &apos;Test&apos;}
    @{File=&apos;Project3.build.ps1&apos;; Log=&apos;C:\TEMP\Project3.log&apos;}
    @{File=&apos;Project4.build.ps1&apos;; Parameters=@{Configuration=&apos;Release&apos;}}
)</dev:code>
<dev:remarks>
<maml:para>Five parallel builds are invoked with various combinations of parameters.
Note that it is fine to invoke the same build script more than once if
build flows specified by different tasks do not conflict.</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Invoke-Build</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
</helpItems>