en-US/ExecutionSteps-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-ExecutionSteps</command:name> <command:verb>Invoke</command:verb> <command:noun>ExecutionSteps</command:noun> <maml:description> <maml:para>Executes a list of ExecutionSteps, outputting human-readable progress (unless asked to be silent)</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Executes a list of ExecutionSteps. The "run" scriptblock of each ExecutionStep will be executed in order until one of them throws an error, or there are no more ExecutionSteps.</maml:para> <maml:para>If an ExecutionStep throws an error, no further steps will be executed, and cleanup will instead commence. This happens by executing the "cleanup" scriptblock of each step, in reverse order, starting from the step that threw an error. If an error should occur during the cleanup stage, cleanup will end prematurely. Otherwise it will continue until all executed steps have been cleaned up.</maml:para> <maml:para>Regardless of whether an error occured or not, the "finally" scriptblock of each executed step will be ran once every other stage is done. This will happen in reverse order, just like "cleanup", and offers each step the opportunity to clean up any resources that should be removed even if execution succeeds.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-ExecutionSteps</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>steps</maml:name> <maml:Description> <maml:para>the list of steps to execute</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ExecutionStep[]</command:parameterValue> <dev:type> <maml:name>ExecutionStep[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>silent</maml:name> <maml:Description> <maml:para>if set, don't write human-readable output to host</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>steps</maml:name> <maml:Description> <maml:para>the list of steps to execute</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ExecutionStep[]</command:parameterValue> <dev:type> <maml:name>ExecutionStep[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>silent</maml:name> <maml:Description> <maml:para>if set, don't write human-readable output to host</maml:para> </maml:Description> <command:parameterValue required="false" variableLength="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:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Invoke-ExecutionSteps @( New-ExecutionStep 'Test 1' { Write-Host "Something's happening in test 1" } New-ExecutionStep 'Test 2' { Write-Host "And now in test 2!" } New-ExecutionStep 'Test 3' { Write-Host "And lastly in step 3." } )</dev:code> <dev:remarks> <maml:para>Running Test 1 Something's happening in test 1 Running Test 2 And now in test 2! Running Test 3 And lastly in step 3. Finalizing Test 3 Finalizing Test 2 Finalizing Test 1</maml:para> <maml:para></maml:para> <maml:para>The script was successfully executed</maml:para> </dev:remarks> </command:example> </command:examples> <command: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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ExecutionStep</command:name> <command:verb>New</command:verb> <command:noun>ExecutionStep</command:noun> <maml:description> <maml:para>Creates a new ExecutionStep instance using the given name and execution script block (and optionally cleanup script blocks)</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a new ExecutionStep. An ExecutionStep represents a single step of a script execution, and can be executed using Invoke-ExecutionSteps. An ExecutionStep consists of: - A "run" scriptblock, which will be executed when the step should do its thing</maml:para> <maml:para>- Optionally a "cleanup" scriptblock, which will be executed if a later step (or the step itself) throws an error</maml:para> <maml:para>- Optionally a "finally" scriptblock, which will be executed when script execution ends, regardless of whether it succeeded</maml:para> <maml:para>See Invoke-ExecutionSteps for more information</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ExecutionStep</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>name</maml:name> <maml:Description> <maml:para>The human-readable name that represents this step</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>run</maml:name> <maml:Description> <maml:para>The scriptblock that will be executed when the step should do its thing</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>cleanup</maml:name> <maml:Description> <maml:para>An optional scriptblock which will be executed if a later step (or the step itself) throws an error</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>final</maml:name> <maml:Description> <maml:para>An optional scriptblock which will be executed when script execution ends, regardless of whether it succeeded. Useful for cleaning up stuff that's needed by later steps.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>name</maml:name> <maml:Description> <maml:para>The human-readable name that represents this step</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>run</maml:name> <maml:Description> <maml:para>The scriptblock that will be executed when the step should do its thing</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>cleanup</maml:name> <maml:Description> <maml:para>An optional scriptblock which will be executed if a later step (or the step itself) throws an error</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>final</maml:name> <maml:Description> <maml:para>An optional scriptblock which will be executed when script execution ends, regardless of whether it succeeded. Useful for cleaning up stuff that's needed by later steps.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$psVersionStep = New-ExecutionStep 'Check PowerShell version >= 7' { if ($PSVersionTable.PSVersion -lt 7) { throw "PowerShell 7 is required to run this script, current version is $($PSVersionTable.PSVersion)" } }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |