InvokeBuild-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 blocks. Any code is invoked with the current location set to $BuildRoot, normally the build script directory. $ErrorActionPreference is set to 'Stop'. To get help for commands dot-source Invoke-Build: PS> . Invoke-Build PS> help task -full USING BUILD SCRIPT PARAMETERS Build scripts define parameters using param(). They are used in tasks as $ParameterName for reading and as $script:ParameterName for writing. The following parameter names are reserved for the engine: Task, File, Result, Safe, Summary, WhatIf, Log Script parameters are specified for Invoke-Build as if they are its own. Known issue #4. Script switches should be specified after Task and File. RESERVED FUNCTION AND VARIABLE NAMES Function and variable names starting with '*' 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-BuildSynopsis Invoke-BuildExec (exec) New-BuildJob (job) Resolve-MSBuild Test-BuildAsset (requires) 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 Build-Parallel These aliases are for the scripts Invoke-Build.ps1 and Build-Parallel.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, by default $BuildFile - build script path $BuildTask - initial tasks $Task - current task $BuildRoot may be changed by scripts on loading in order to set a custom build root directory. Other variables should not be changed. $Task is available for script blocks defined by task parameters If, Inputs, Outputs, and Jobs and by blocks Enter|Exit-BuildTask, Enter|Exit-BuildJob, Set-BuildHeader. $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. BUILD BLOCKS Scripts may define the following build blocks. They are invoked: 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 action Exit-BuildJob {} - after each task action Set-BuildHeader {param($path)} - custom task header writer Nested builds do not inherit parent blocks. If Enter-X is called then Exit-X is called. Blocks are not called on WhatIf, except Set-BuildHeader. 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 text. Enter-BuildTask, Exit-BuildTask, Enter-BuildJob, and Exit-BuildJob are invoked in the same scope, the parent of task action blocks. DOT-SOURCING Invoke-Build Build-like environment can be imported to normal scripts: . Invoke-Build [<root>] 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 <root> - sets the current PowerShell location to $BuildRoot - imports utility commands - assert - equals - exec - property - requires - 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">Object</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>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 '.' then the task '.' 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, for example when tasks are tests. ** - 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 'task' (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 it exists, otherwise build fails. If the build file is not found then a script defined by the environment variable InvokeBuildGetFile is called with the path as an argument. For this location it may return the full path of a special build script. If the file is still not found then parent directories are searched. INLINE SCRIPT `File` is a script block which is normally used in order to assemble a build on the fly without creating and using an extra build script file. Script parameters are not supported. Use the parent scope variables instead, either directly or with the helpers `property` and `requires`. $BuildRoot is the calling script root (or the current location). If it is not what the build needs as its root directory, then change this variable in the beginning of the inline script block. $BuildFile is the calling script (it may be null, e.g. in jobs). This variable is rarely used, just keep in mind the difference. Persistent and parallel builds are not supported.</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 available tasks Error - a terminating build error Tasks - invoked tasks including nested Errors - error objects including nested Warnings - warning objects including nested Redefined - list of original redefined tasks 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>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 blocks. But script scope code should not output anything. Unexpected output causes warnings, 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 ('.' 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 Output and WarningLevel by param(). Invoke-Build Build, Test -Output 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># 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 = 'Task' Expression = {$_.Name + ' @ ' + $_.InvocationInfo.ScriptName} }</dev:code> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 7 --------------------------</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>Resolve-MSBuild</maml:linkText> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Test-BuildAsset (requires)</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:navigationLink> <maml:linkText>Build-Checkpoint</maml:linkText> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Build-Parallel</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 'task'. 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 'job' (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 'job'. 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 condition is defined in one of two ways depending on the requirements. Using standard Boolean notation (parenthesis) the condition will only be evaluated when the task is loaded into the build engine. A use case for this notation might be evaluating parameters that are passed into the build. Example: task SomeTask -If ($SomeCondition) {...} Using script block notation (curly braces) the condition will be evaluated dynamically on task invocation. If a task is referenced by several tasks then the condition is evaluated each time until it gets true and the task is invoked. The script block notation is normally used for a condition that may be defined or changed during the build. Example: task SomeTask -If {$SomeCondition} {...} On WhatIf: - Boolean conditions are evaluated and treated accordingly. - Script block conditions are treated as true without invocation.</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. A script block is invoked with input paths piped to it. Automatic variables for incremental task actions: $Inputs - full input paths, array of strings $Outputs - result of the evaluated Outputs With the switch Partial the task is processed as partial incremental. There must be one-to-one correspondence between Inputs and Outputs. Partial task actions often contain "process {}" blocks. Two more automatic variables are available for them: $_ - full path of an input item $2 - corresponding 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, either directly on task creation or as a script block invoked with the task. It is used together with Inputs. See Inputs for more 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> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code># 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</dev:code> <dev:remarks> <maml:para>This example shows various possible combinations of task jobs.</maml:para> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code># Helper for tasks with complex parameters composed as hashtables function taskx($Name, $Param) {task $Name @Param -Source $MyInvocation} # Synopsis: Complex task with parameters as a hashtable. taskx MakeDocs @{ Inputs = {Get-Item *.md} Outputs = {Get-Item *.htm} Partial = $true Jobs = 'Task1', { #... } } # Synopsis: Simple task with usual parameters. task Task1 { #... }</dev:code> <dev:remarks> <maml:para>Tasks with complex parameters are often difficult to compose in a readable way. Use PowerShell splatting or add the above helper `taskx` to a script in order to compose parameters as hashtables.</maml:para> </dev:remarks> </command:example> </command:examples> <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 'job'. 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 'error' (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 'error'. 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 'assert'. 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 'equals X Y' instead of 'assert (X -eq Y)'. 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 'equals'. 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 'assert (X -eq Y)'.</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 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 'property'. The command returns: - session variable value if it is not $null or '' - environment variable if it is not $null or '' - default value if it is not $null - error</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>Specifies the 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. If it is omitted or null then the variable must exist with a not empty value. 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> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Test-BuildAsset</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-BuildSynopsis</command:name> <maml:description> <maml:para>Gets the task synopsis.</maml:para> </maml:description> <command:verb>Get</command:verb> <command:noun>BuildSynopsis</command:noun> </command:details> <maml:description> <maml:para>Gets the specified task synopsis if it is available. Task synopsis is defined in preceding comments as # Synopsis: ...</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-BuildSynopsis</maml:name> <command:parameter required="true" position="1" > <maml:name>Task</maml:name> <command:parameterValue required="true">Object</command:parameterValue> </command:parameter> <command:parameter required="false" position="2" > <maml:name>Hash</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>Task</maml:name> <maml:description> <maml:para>The task object. During the build, the current task is available as the automatic variable $Task.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="2" > <maml:name>Hash</maml:name> <maml:description> <maml:para>Any hashtable to be used as a cache. Build scripts do not have to specify it, it is designed for external tools.</maml:para> </maml:description> </command:parameter> </command:parameters> <command:returnValues> <command:returnValue> <dev:type> <maml:name>String</maml:name> </dev:type> <maml:description> <maml:para>Task synopsis line.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code># Print task path and synopsis Set-BuildHeader { param($Path) Write-Build Cyan "Task $Path : $(Get-BuildSynopsis $Task)" } # Synopsis: Show task data useful for headers task Task1 { $Task.Name $Task.InvocationInfo.ScriptName $Task.InvocationInfo.ScriptLineNumber }</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>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 'exec'. 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>Test-BuildAsset</command:name> <maml:description> <maml:para>Checks for required build assets.</maml:para> </maml:description> <command:verb>Test</command:verb> <command:noun>BuildAsset</command:noun> </command:details> <maml:description> <maml:para>Scripts use its alias 'requires'. This command tests the required build assets. It fails if something is missing or invalid. It is used either in script code (common assets) or in tasks (individual assets).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-BuildAsset</maml:name> <command:parameter required="false" position="1" > <maml:name>Variable</maml:name> <command:parameterValue required="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Environment</maml:name> <command:parameterValue required="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Property</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>Variable</maml:name> <maml:description> <maml:para>Specifies session variable names and tells to fail if a variable is missing or its value is null or an empty string.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Environment</maml:name> <maml:description> <maml:para>Specifies environment variable names and tells to fail if a variable is not defined or its value is an empty string.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies session or environment variable names and tells to fail if a variable is missing or its value is null or an empty string. It makes sense to use `property` later with tested names without defaults.</maml:para> </maml:description> </command:parameter> </command:parameters> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Get-BuildProperty</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 'use'. 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.</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 path is resolved using the package script Resolve-MSBuild.ps1. Build scripts may invoke it directly by the provided alias Resolve-MSBuild. The optional suffix x86 tells to use 32-bit MSBuild. If it is like Framework* then it is assumed to be a path relative to Microsoft.NET in the Windows directory. If it is like VisualStudio\<version> then it is resolved to the specified Visual Studio tools directory (devenv, mstest, tf, ...). NOTE: This way is not supported starting with Visual Studio 2017, use the special Microsoft module VSSetup from PSGallery instead. Otherwise it is a full or relative literal path of any directory. Examples: *, 4.0, Framework\v4.0.30319, VisualStudio\14.0, .\Tools</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="2" > <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the tool names. They become aliases in the current scope. If it is a build script then the aliases are created for all tasks. If it is a task then the aliases are available just for this task.</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:navigationLink> <maml:linkText>Resolve-MSBuild</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.</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 by the engine and exposed for related tools.</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>Build-Parallel.ps1</command:name> <maml:description> <maml:para>Invokes parallel builds by Invoke-Build</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>Build-Parallel.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:parameter required="false" position="named" > <maml:name>FailHard</maml:name> </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, ... - Invoke-Build.ps1 and script 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>FailHard</maml:name> <maml:description> <maml:para>Tells to abort all builds if any build fails.</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>Build-Parallel @( @{File='Project1.build.ps1'} @{File='Project2.build.ps1'; Task='MakeHelp'} @{File='Project2.build.ps1'; Task='Build', 'Test'} @{File='Project3.build.ps1'; Log='C:\TEMP\Project3.log'} @{File='Project4.build.ps1'; Configuration='Release'} )</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> <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>Build-Checkpoint.ps1</command:name> <maml:description> <maml:para>Invokes persistent builds with checkpoints.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This command invokes the build specified by the hashtable Build so that it writes checkpoints to the file specified by Checkpoint. If the build fails then it may be resumed later, use the switch Resume in addition to the original Checkpoint parameter. The build is resumed at the failed task. Not every build may be persistent, right away or at all: - 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. CUSTOM EXPORT AND IMPORT By default, the command saves and restores build tasks, script path, and all parameters declared by the build script, not just specified by Build. Tip: consider to declare some script variables as artificial parameters in order to make them persistent. If this is not enough for saving and restoring the build state then use custom export and import blocks. The export block is called on writing checkpoints, i.e. on each task. The import block is called on resuming once, before the task to be resumed. The export block is defined as Set-BuildData Checkpoint.Export { $script:var1 $script:var2 } The import block is defined as Set-BuildData Checkpoint.Import { param($data) $var1, $var2 = $data } Note that the import block is called in the script scope. In the example, variables $var1, $var2 are the script variables, you may but do not have to use the prefix `$script:`. The parameter $data is the data written by Checkpoint.Export, exported to clixml and then imported from clixml.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Build-Checkpoint.ps1</maml:name> <command:parameter required="true" position="1" > <maml:name>Checkpoint</maml:name> <command:parameterValue required="true">String</command:parameterValue> </command:parameter> <command:parameter required="false" position="2" > <maml:name>Build</maml:name> <command:parameterValue required="true">Hashtable</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Resume</maml:name> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="1" > <maml:name>Checkpoint</maml:name> <maml:description> <maml:para>Specifies the checkpoint file (clixml). The checkpoint file is removed after successful builds. If a build fails and it is not going to be resumed then delete the checkpoint file manually.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="2" > <maml:name>Build</maml:name> <maml:description> <maml:para>Specifies Invoke-Build parameters. If the build is resumed then tasks, script, and script parameters are ignored and restored from the file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" position="named" > <maml:name>Resume</maml:name> <maml:description> <maml:para>Tells to resume the build from the existing checkpoint file.</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 the invoked build.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code># Invoke a persistent sequence of steps defined as tasks. Build-Checkpoint temp.clixml @{Task = '*'; File = 'Steps.build.ps1'} # Given the above failed, resume at the failed step. Build-Checkpoint temp.clixml -Resume</dev:code> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Invoke-Build</maml:linkText> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |