en-US/Builder-Help.xml
|
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><helpItems 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>Assert</command:name><maml:description><maml:para>A helper keyword for "Design by Contract" assertion checking.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Assertions helps to make the code less "noisy" by eliminating the need to write nested </maml:para><maml:para>`if` statements that are normally required to verify assumptions in the code.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Assert</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Condition</maml:name><command:parameterValue required="true">Object</command:parameterValue></command:parameter><command:parameter require="true" globbing="false" pipelineInput="false" position="3"><maml:name>ErrorMessage</maml:name><command:parameterValue required="true">Object</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Condition</maml:name><maml:description><maml:para>The boolean condition to evaluate.</maml:para></maml:description><command:parameterValue required="true">Object</command:parameterValue><dev:type><maml:name>Object</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="true" globbing="false" pipelineInput="false" position="3"><maml:name>ErrorMessage</maml:name><maml:description><maml:para>The error message to display if the `Condition` parameter is false.</maml:para></maml:description><command:parameterValue required="true">Object</command:parameterValue><dev:type><maml:name>Object</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name><maml:description><maml:para>Do not trigger any last wills (if defined) when failing.</maml:para></maml:description><command:parameterValue required="false">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples><command:example><maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title><maml:introduction><maml:para>PS C:\> </maml:para></maml:introduction><dev:code>assert $false "This always throws an exception"</dev:code><dev:remarks><maml:para></maml:para><maml:para></maml:para><maml:para></maml:para></dev:remarks><command:commandLines><command:commandLine><command:commandText /></command:commandLine></command:commandLines></command:example><command:example><maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title><maml:introduction><maml:para>PS C:\> </maml:para></maml:introduction><dev:code>assert (($i % 2) -eq 0) "$i is not an even number"</dev:code><dev:remarks><maml:para>DESCRIPTION ----------- This statement may throw an exception if `$i` is not an even number.</maml:para><maml:para>Note: you may need to wrap the condition with paranthesis to prevent a syntax error.</maml:para><maml:para></maml:para><maml:para></maml:para><maml:para></maml:para></dev:remarks><command:commandLines><command:commandLine><command:commandText /></command:commandLine></command:commandLines></command:example></command:examples><maml:relatedLinks></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>Die</command:name><maml:description><maml:para>Terminates the build script with an error message.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use this command in a build script to raise a terminating exception.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Die</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Message</maml:name><command:parameterValue required="true">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="3"><maml:name>ErrorCode</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Message</maml:name><maml:description><maml:para>The error message to display.</maml:para></maml:description><command:parameterValue required="true">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="3"><maml:name>ErrorCode</maml:name><maml:description><maml:para>The error code to return.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type><dev:defaultValue>BuildError</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name><maml:description><maml:para>If one or more `will` block is present in the build script, these script blocks will </maml:para><maml:para>be executed in order before the terminating exception is raised. This parameter </maml:para><maml:para>overrides this behavior and terminates the build script immediately.</maml:para><maml:para>If no `will` block is defined, this parameter does not have any effect.</maml:para></maml:description><command:parameterValue required="false">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>EnvPath</command:name><maml:description><maml:para>Sets the environmental paths you want to use during build.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>This keyword accept a list of directory paths. These paths will be prepended to the existing system paths within the calling context.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>EnvPath</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Path</maml:name><command:parameterValue required="true">String[]</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Path</maml:name><maml:description><maml:para>A list of paths to prepend to the existing system paths.</maml:para></maml:description><command:parameterValue required="true">String[]</command:parameterValue><dev:type><maml:name>String[]</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Exec</command:name><maml:description><maml:para>Helper command for executing command-line programs.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Define the script block to call an external program. This command automatically checks the `$lastexitcode` variable to </maml:para><maml:para>determine whether an error has occcured. </maml:para><maml:para>If an error is detected, the default behavior is to throw an exception and terminate. Alternatively, you may re-execute </maml:para><maml:para>the script block several times until there are no errors.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Exec</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Command</maml:name><command:parameterValue required="true">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>ErrorMessage</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>MaxRetry</maml:name><command:parameterValue required="false">Int32</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>RetryDelay</maml:name><command:parameterValue required="false">Int32</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>RetryTriggerErrorPattern</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Command</maml:name><maml:description><maml:para>The script block to execute. This script block will typically contain the command-line invocation.</maml:para></maml:description><command:parameterValue required="true">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>ErrorMessage</maml:name><maml:description><maml:para>The error message to display if an exception is thrown.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type><dev:defaultValue>($PBLocalizedData.Err_BadCommand -f $Command)</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>MaxRetry</maml:name><maml:description><maml:para>Repeat execution of the script block if an error was encountered, up to the number of times defined by this parameter.</maml:para></maml:description><command:parameterValue required="false">Int32</command:parameterValue><dev:type><maml:name>Int32</maml:name><maml:uri /></dev:type><dev:defaultValue>0</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>RetryDelay</maml:name><maml:description><maml:para>When re-executing the script block, wait for the number of seconds defined by this parameter between each attempt.</maml:para></maml:description><command:parameterValue required="false">Int32</command:parameterValue><dev:type><maml:name>Int32</maml:name><maml:uri /></dev:type><dev:defaultValue>1</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>RetryTriggerErrorPattern</maml:name><maml:description><maml:para>Re-execute the script block only if the last error message matches the regular expression pattern defined by this </maml:para><maml:para>parameter.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>NoWill</maml:name><maml:description><maml:para>Do not trigger any last wills (if defined) when failing.</maml:para></maml:description><command:parameterValue required="false">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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-BuildScriptTasks</command:name><maml:description><maml:para>Returns metadata on tasks.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb>Get</command:verb><command:noun>BuildScriptTasks</command:noun><dev:version /></command:details><maml:description><maml:para>This command parses the build script specified and returns metadata about all the tasks defined.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Get-BuildScriptTasks</command:name><command:parameter require="false" globbing="false" pipelineInput="false" position="2"><maml:name>BuildFile</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="false" globbing="false" pipelineInput="false" position="2"><maml:name>BuildFile</maml:name><maml:description><maml:para>The path to the build script to evaluate tasks metadata.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Include</command:name><maml:description><maml:para>Include the functions or code of another script file into the current build script's scope.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>A build script may declare an "include" keyword which allows you to define a script to be </maml:para><maml:para>included and added to the scope of the currently running build script. Code from such file </maml:para><maml:para>will be executed AFTER code from build script.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Include</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>FilePath</maml:name><command:parameterValue required="true">String</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>FilePath</maml:name><maml:description><maml:para>A string containing the path of the script file to include.</maml:para></maml:description><command:parameterValue required="true">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Invoke-Builder</command:name><maml:description><maml:para /></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb>Invoke</command:verb><command:noun>Builder</command:noun><dev:version /></command:details><maml:description></maml:description><command:syntax><command:syntaxItem><command:name>Invoke-Builder</command:name><command:parameter require="false" globbing="false" pipelineInput="false" position="1"><maml:name>BuildFile</maml:name><command:parameterValue required="false">string</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="2"><maml:name>TaskList</maml:name><command:parameterValue required="false">string[]</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Docs</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Parameters</maml:name><command:parameterValue required="false">hashtable</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Properties</maml:name><command:parameterValue required="false">Object</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Initialization</maml:name><command:parameterValue required="false">scriptblock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>NoLogo</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>DetailDocs</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="Named"><maml:name>TimeReport</maml:name></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="false" globbing="false" pipelineInput="false" position="1"><maml:name>BuildFile</maml:name><maml:description></maml:description><command:parameterValue required="false">string</command:parameterValue><dev:type><maml:name>string</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>DetailDocs</maml:name><maml:description></maml:description><command:parameterValue required="false">switch</command:parameterValue><dev:type><maml:name>switch</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Docs</maml:name><maml:description></maml:description><command:parameterValue required="false">switch</command:parameterValue><dev:type><maml:name>switch</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Initialization</maml:name><maml:description></maml:description><command:parameterValue required="false">scriptblock</command:parameterValue><dev:type><maml:name>scriptblock</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>NoLogo</maml:name><maml:description></maml:description><command:parameterValue required="false">switch</command:parameterValue><dev:type><maml:name>switch</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Parameters</maml:name><maml:description></maml:description><command:parameterValue required="false">hashtable</command:parameterValue><dev:type><maml:name>hashtable</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>Properties</maml:name><maml:description></maml:description><command:parameterValue required="false">Object</command:parameterValue><dev:type><maml:name>Object</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="2"><maml:name>TaskList</maml:name><maml:description></maml:description><command:parameterValue required="false">string[]</command:parameterValue><dev:type><maml:name>string[]</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="Named"><maml:name>TimeReport</maml:name><maml:description></maml:description><command:parameterValue required="false">switch</command:parameterValue><dev:type><maml:name>switch</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>N</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>S</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Invoke-Task</command:name><maml:description><maml:para>Executes another task in the current build script.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb>Invoke</command:verb><command:noun>Task</command:noun><dev:version /></command:details><maml:description><maml:para>This keyword allows you to invoke a task from within another task in the current build script.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Invoke-Task</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>TaskName</maml:name><command:parameterValue required="true">String</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>TaskName</maml:name><maml:description><maml:para>The name of the task to execute.</maml:para></maml:description><command:parameterValue required="true">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>PrintTask</command:name><maml:description><maml:para>Customize how to render the task name during a build.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Accepts either a string which represents a format string (formats using the -f format operator see "help about_operators"), or </maml:para><maml:para>a script block that has a single parameter that is the name of the task that will be executed.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>PrintTask</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Format</maml:name><command:parameterValue required="true">Object</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Format</maml:name><maml:description><maml:para>A format string or a script block to execute.</maml:para></maml:description><command:parameterValue required="true">Object</command:parameterValue><dev:type><maml:name>Object</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples><command:example><maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title><maml:introduction><maml:para>PS C:\> </maml:para></maml:introduction><dev:code>task default -depends TaskA, TaskB, TaskC printTask "-------- {0} --------" task TaskA { "TaskA is executing" } task TaskB { "TaskB is executing" } task TaskC { "TaskC is executing" } # The script above produces the following output: # # -------- TaskA -------- # TaskA is executing # -------- TaskB -------- # TaskB is executing # -------- TaskC -------- # TaskC is executing # # Build Succeeded!</dev:code><dev:remarks><maml:para>DESCRIPTION ----------- Use a format string to customize how the task name is printed.</maml:para><maml:para></maml:para><maml:para></maml:para><maml:para></maml:para></dev:remarks><command:commandLines><command:commandLine><command:commandText /></command:commandLine></command:commandLines></command:example><command:example><maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title><maml:introduction><maml:para>PS C:\> </maml:para></maml:introduction><dev:code>printTask { param($taskName) say "Executing Task: $taskName" -fg blue } task default -depends TaskA, TaskB, TaskC task TaskA { "TaskA is executing" } task TaskB { "TaskB is executing" } task TaskC { "TaskC is executing" }</dev:code><dev:remarks><maml:para>DESCRIPTION ----------- Use a script block to customize how the task name is printed.</maml:para><maml:para>This example uses the script block parameter to the `printTask` keyword to render each </maml:para><maml:para>task name in the color blue.</maml:para><maml:para>Note: the `$taskName` parameter is arbitrary it could be named anything.</maml:para><maml:para></maml:para><maml:para></maml:para><maml:para></maml:para></dev:remarks><command:commandLines><command:commandLine><command:commandText /></command:commandLine></command:commandLines></command:example></command:examples><maml:relatedLinks></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>Properties</command:name><maml:description><maml:para>Define a script block that contains assignments to variables. These variables will be available to all tasks in the build script.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>A build script may use the `properties` keyword to define variables. These variables will be available to all the `tasks` in the build script.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Properties</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><command:parameterValue required="true">ScriptBlock</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><maml:description></maml:description><command:parameterValue required="true">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Say</command:name><maml:description><maml:para>Prints a text output.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use this command within a build script to print a text output.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Say</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Message</maml:name><command:parameterValue required="true">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>VerboseLevel</maml:name><command:parameterValue required="false">Int32</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>ForegroundColor</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Force</maml:name></command:parameter></command:syntaxItem><command:syntaxItem><command:name>Say</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="named"><maml:name>Divider</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Force</maml:name></command:parameter></command:syntaxItem><command:syntaxItem><command:name>Say</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="named"><maml:name>NewLine</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>LineCount</maml:name><command:parameterValue required="false">Int32</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Force</maml:name></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Message</maml:name><maml:description><maml:para>The text to print.</maml:para></maml:description><command:parameterValue required="true">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="true" globbing="false" pipelineInput="false" position="named"><maml:name>Divider</maml:name><maml:description><maml:para>Prints text that represents a dividing line:</maml:para><maml:para>++++++++</maml:para></maml:description><command:parameterValue required="true">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter><command:parameter required="true" globbing="false" pipelineInput="false" position="named"><maml:name>NewLine</maml:name><maml:description><maml:para>Prints an empty line (line break).</maml:para></maml:description><command:parameterValue required="true">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>LineCount</maml:name><maml:description><maml:para>Use together with the `NewLine` parameter to output multiple line breaks.</maml:para></maml:description><command:parameterValue required="false">Int32</command:parameterValue><dev:type><maml:name>Int32</maml:name><maml:uri /></dev:type><dev:defaultValue>1</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>VerboseLevel</maml:name><maml:description><maml:para>Defines the verbose level of the output text. If the verbose level defined is higher than </maml:para><maml:para>the output verbose level setting, the text is ignored (unless the `Force` parameter is used).</maml:para></maml:description><command:parameterValue required="false">Int32</command:parameterValue><dev:type><maml:name>Int32</maml:name><maml:uri /></dev:type><dev:defaultValue>1</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>ForegroundColor</maml:name><maml:description><maml:para>Specifies the color of the output text. This parameter is silently ignored if the output medium </maml:para><maml:para>does not support color output.</maml:para></maml:description><command:parameterValue required="false">ConsoleColor</command:parameterValue><dev:type><maml:name>ConsoleColor</maml:name><maml:uri /></dev:type><dev:defaultValue>Yellow</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Force</maml:name><maml:description><maml:para>Ensures that the text is displayed, regardless of its verbose level.</maml:para></maml:description><command:parameterValue required="false">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Task</command:name><maml:description><maml:para>Defines a build task to be executed by Builder.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use within a build script. This keyword creates a 'task' object that will be used by the Builder engine to execute </maml:para><maml:para>a build task. </maml:para><maml:para>NOTE: You must defined a task called 'default'.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Task</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>Name</maml:name><command:parameterValue required="true">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="3"><maml:name>Action</maml:name><command:parameterValue required="false">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>PreAction</maml:name><command:parameterValue required="false">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>PostAction</maml:name><command:parameterValue required="false">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Precondition</maml:name><command:parameterValue required="false">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Postcondition</maml:name><command:parameterValue required="false">ScriptBlock</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>ContinueOnError</maml:name></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Depends</maml:name><command:parameterValue required="false">String[]</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>RequiredVariables</maml:name><command:parameterValue required="false">String[]</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Description</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter><command:parameter require="false" globbing="false" pipelineInput="false" position="named"><maml:name>Alias</maml:name><command:parameterValue required="false">String</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>Name</maml:name><maml:description><maml:para>The name of the task.</maml:para></maml:description><command:parameterValue required="true">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="3"><maml:name>Action</maml:name><maml:description><maml:para>A script block containing the statements to execute for the task.</maml:para></maml:description><command:parameterValue required="false">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>PreAction</maml:name><maml:description><maml:para>A scriptblock to be executed before the `Action` script block.</maml:para><maml:para>NOTE: This parameter is silently ignored if the `Action` script block is undefined.</maml:para></maml:description><command:parameterValue required="false">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>PostAction</maml:name><maml:description><maml:para>A script block to be executed after the `Action` scriptblock. </maml:para><maml:para>NOTE: This parameter is silently ignored if the `Action` script block is undefined.</maml:para></maml:description><command:parameterValue required="false">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Precondition</maml:name><maml:description><maml:para>A script block that is executed to determine whether the task should be is executed or skipped.</maml:para><maml:para>This script block should return either `$true` or `$false`.</maml:para></maml:description><command:parameterValue required="false">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type><dev:defaultValue>{ $true }</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Postcondition</maml:name><maml:description><maml:para>A script block that is executed to determine if the task completed its job correctly.</maml:para><maml:para>An exception is thrown if the script block returns `$false`.</maml:para></maml:description><command:parameterValue required="false">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type><dev:defaultValue>{ $true }</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>ContinueOnError</maml:name><maml:description><maml:para>If this switch parameter is set then the task will not cause the build to fail when an error occurs while running the task.</maml:para></maml:description><command:parameterValue required="false">SwitchParameter</command:parameterValue><dev:type><maml:name>SwitchParameter</maml:name><maml:uri /></dev:type><dev:defaultValue>False</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Depends</maml:name><maml:description><maml:para>An array of task names that this task depends on. These tasks will be executed before the current task is executed.</maml:para></maml:description><command:parameterValue required="false">String[]</command:parameterValue><dev:type><maml:name>String[]</maml:name><maml:uri /></dev:type><dev:defaultValue>@()</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>RequiredVariables</maml:name><maml:description><maml:para>An array of names of variables that must be set to run this task.</maml:para></maml:description><command:parameterValue required="false">String[]</command:parameterValue><dev:type><maml:name>String[]</maml:name><maml:uri /></dev:type><dev:defaultValue>@()</dev:defaultValue></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Description</maml:name><maml:description><maml:para>A description of the task for documentation purposes.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter><command:parameter required="false" globbing="false" pipelineInput="false" position="named"><maml:name>Alias</maml:name><maml:description><maml:para>An alternative name for the task.</maml:para></maml:description><command:parameterValue required="false">String</command:parameterValue><dev:type><maml:name>String</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>TaskSetup</command:name><maml:description><maml:para>Defines a script block that will be executed before each task.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use this keyword to define a script block that will be executed before each</maml:para><maml:para>task in the build script.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>TaskSetup</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><command:parameterValue required="true">ScriptBlock</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><maml:description><maml:para>A script block to execute.</maml:para></maml:description><command:parameterValue required="true">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>TaskTearDown</command:name><maml:description><maml:para>Runs a script block after each task.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use this keyword to define a script block that will be executed after each</maml:para><maml:para>task in the build script.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>TaskTearDown</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><command:parameterValue required="true">ScriptBlock</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><maml:description><maml:para>A scriptblock to execute.</maml:para></maml:description><command:parameterValue required="true">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></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>Will</command:name><maml:description><maml:para>Execute a script block whenever an exception is encountered.</maml:para></maml:description><maml:copyright><maml:para /></maml:copyright><command:verb></command:verb><command:noun></command:noun><dev:version /></command:details><maml:description><maml:para>Use this keyword to define a last will script block. Last wills are executed </maml:para><maml:para>just before the build script terminates due to an exception.</maml:para></maml:description><command:syntax><command:syntaxItem><command:name>Will</command:name><command:parameter require="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><command:parameterValue required="true">ScriptBlock</command:parameterValue></command:parameter></command:syntaxItem></command:syntax><command:parameters><command:parameter required="true" globbing="false" pipelineInput="false" position="2"><maml:name>ScriptBlock</maml:name><maml:description><maml:para>The last will script block to execute.</maml:para></maml:description><command:parameterValue required="true">ScriptBlock</command:parameterValue><dev:type><maml:name>ScriptBlock</maml:name><maml:uri /></dev:type></command:parameter></command:parameters><command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:inputType></command:inputTypes><command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name><maml:uri /><maml:description><maml:para></maml:para></maml:description></dev:type></command:returnValue></command:returnValues><maml:alertSet><maml:title></maml:title><maml:alert><maml:para>You can define multiple last wills by using the `will` keyword repeatedly. The wills </maml:para><maml:para>will be executed in the order that they are defined.</maml:para></maml:alert></maml:alertSet><command:examples></command:examples><maml:relatedLinks></maml:relatedLinks></command:command></helpItems> |