en-US/TaskHost.dll-help.xml
|
<?xml version="1.0" encoding="utf-8" ?> <helpItems schema="maml" xmlns="http://msh" 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"> <!-- Copyright 2023 Subatomix Research Inc. SPDX-License-Identifier: ISC Documentation: https://docs.microsoft.com/en-us/powershell/developer/help/how-to-create-the-cmdlet-help-file --> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Use-TaskHost --> <command:command> <command:details> <command:name>Use-TaskHost</command:name> <maml:description> <maml:para>Runs commands while augmenting their output to add clarity to long-running and/or parallel tasks.</maml:para> </maml:description> <maml:copyright><maml:para/></maml:copyright> <command:verb>Use</command:verb> <command:noun>TaskHost</command:noun> <dev:version/> </command:details> <maml:description> <maml:para> The Use-TaskHost cmdlet executes the statements of a script block while temporarily overriding the current PowerShell host ($Host). The new host modifies its output streams to add clarity to long-running, potentially parallel tasks. A companion cmdlet, Invoke-Task, defines the tasks. </maml:para> <maml:para> Used together, the Use-TaskHost and Invoke-Task cmdlets modify output streams as follows: </maml:para> <maml:list> <maml:listItem> <maml:para>(1) Success wrapped in object with ElapsedTime, Task, and Object properties</maml:para> </maml:listItem> <maml:listItem> <maml:para>(2) Error prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(3) Warning prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(4) Verbose prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(5) Debug prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(6) Information prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>n/a Progress not modified</maml:para> </maml:listItem> </maml:list> <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para> <maml:para> The -WithElapsed switch of Use-TaskHost enables the capture of elapsed time (since the invocation of Use-TaskHost) in output. This behavior populates the ElapsedTime property in TaskOutput objects and adds a '[+hh:mm:ss]' line header to textual output streams. </maml:para> <maml:para><!-- HACK: Get-Help does not put a blank line between <para> --></maml:para> <maml:para> The Invoke-Task cmdlet defines a task and enables the association of the task and its output. This behavior wraps each object emitted from the task's success stream in a TaskOutput object with ElapsedTime, Task, and Object properties. Combined with Use-TaskHost, this behavior also adds a '[task]' line header to textual output streams, containing the full name of the producing task. </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Use-TaskHost</maml:name> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>WithElapsed</maml:name> <maml:description/> </command:parameter> <command:parameter required="true" position="0" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>ScriptBlock</maml:name> <maml:description/> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="0" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>ScriptBlock</maml:name> <maml:description> <maml:para>The commands to run.</maml:para> <maml:para>Specifies the commands to run. Enclose the commands in braces { } to create a script block.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>WithElapsed</maml:name> <maml:description> <maml:para>Enables the capture of elapsed time in output.</maml:para> </maml:description> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri /> </dev:type> <maml:description> <maml:para>This cmdlet does not accept pipeline input.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri></maml:uri> </dev:type> <maml:description> <maml:para>This cmdlet returns the objects that are produced by the script block.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors/> <command:nonTerminatingErrors/> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Invoke-Task</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>GitHub repository:</maml:linkText> <maml:uri>https://github.com/sharpjs/Subatomix.PowerShell.TaskHost</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <!-- Invoke-Task --> <command:command> <command:details> <command:name>Invoke-Task</command:name> <maml:description> <maml:para>Runs commands as a task. For use with Use-TaskHost.</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> The Invoke-Task cmdlet executes the statements of a script block as a task. A companion cmdlet, Use-TaskHost, modifies its output streams to add clarity to long-running, potentially parallel tasks. </maml:para> <maml:para> Used together, the Use-TaskHost and Invoke-Task cmdlets modify output streams as follows: </maml:para> <maml:list> <maml:listItem> <maml:para>(1) Success wrapped in object with ElapsedTime, Task, and Object properties</maml:para> </maml:listItem> <maml:listItem> <maml:para>(2) Error prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(3) Warning prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(4) Verbose prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(5) Debug prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>(6) Information prefixed with "[+hh:mm:ss] [task]: "</maml:para> </maml:listItem> <maml:listItem> <maml:para>n/a Progress not modified</maml:para> </maml:listItem> </maml:list> <maml:para><!-- HACK: Get-Help does not put a blank line after the <list> --></maml:para> <maml:para> The Invoke-Task cmdlet defines a task and enables the association of the task and its output. This behavior wraps each object emitted from the task's success stream in a TaskOutput object with ElapsedTime, Task, and Object properties. Combined with Use-TaskHost, this behavior also adds a '[task]' line header to textual output streams, containing the full name of the producing task. </maml:para> <maml:para><!-- HACK: Get-Help does not put a blank line between <para> --></maml:para> <maml:para> The -WithElapsed switch of Use-TaskHost enables the capture of elapsed time (since the invocation of Use-TaskHost) in output. This behavior populates the ElapsedTime property in TaskOutput objects and adds a '[+hh:mm:ss]' line header to textual output streams. </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Task</maml:name> <command:parameter required="true" position="0" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>Name</maml:name> <maml:description/> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" position="1" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>ScriptBlock</maml:name> <maml:description/> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="0" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>Name</maml:name> <maml:description> <maml:para>Sets the initial name of the task. Pass "" to use an unnamed task. Pass $null to autogenerate a name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" position="1" pipelineInput="False" globbing="false" variableLength="false"> <maml:name>ScriptBlock</maml:name> <maml:description> <maml:para>The commands to run.</maml:para> <maml:para>Specifies the commands to run. Enclose the commands in braces { } to create a script block.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri /> </dev:type> <maml:description> <maml:para>This cmdlet does not accept pipeline input.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Subatomix.PowerShell.TaskHost.TaskOutput</maml:name> <maml:uri></maml:uri> </dev:type> <maml:description> <maml:para>Output of the script block, wrapped in an object with the following properties:</maml:para> <maml:list> <maml:listItem> <maml:para>Task Task that produced the output</maml:para> </maml:listItem> <maml:listItem> <maml:para>ElapsedTime Elapsed time since invocation of Use-TaskHost -WithElapsed</maml:para> </maml:listItem> <maml:listItem> <maml:para>Object Output object of the script block</maml:para> </maml:listItem> </maml:list> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors/> <command:nonTerminatingErrors/> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Use-TaskHost</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>GitHub repository:</maml:linkText> <maml:uri>https://github.com/sharpjs/Subatomix.PowerShell.TaskHost</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |