Cmdlet

Invoke-ConsoleRun

Module ConsoleMonster

Inputs

System.Management.Automation.PSObject

Runs a script block for every input item, optionally in parallel, with a live view of the run.

Syntax

Invoke-ConsoleRun [-InputObject <PSObject>] [-Name <Object>] [-Parallel] [-ScriptBlock] <ScriptBlock> [-ThrottleLimit <Int32>] [-TimeoutSeconds <Double>] [-Title <Object>] [-Unordered] [<CommonParameters>]

Parameter set: All Parameter Sets

Description

Runs a script block for every input item, optionally in parallel, with a live view of the run.

ForEach-ConsoleItem is its alias. $_ is the item, as in ForEach-Object. While it runs, a live view shows a summary line (done of total, percentage, time left, counts), one cell per item, the running items with their elapsed time and the failures; without an interactive console (redirected output, CI, a job) it prints one line per finished item and a summary instead. The output is the script block's ordinary output, in input order (or as each item finishes with -Unordered); an item's errors are written as error records and mark it as failed. While the live view is showing, output, errors and warnings are written when it ends, so nothing prints inside the view, and progress bars from the script block are hidden. Without -Parallel the items run one at a time in the caller's scope, as with ForEach-Object, so variables set in the script block stay. -Parallel runs up to -ThrottleLimit items at a time in their own runspaces on Windows PowerShell 5.1 and PowerShell 7: variables of the caller are passed with $using:name, and -TimeoutSeconds stops an item that runs too long. -Name (or -Label) sets each item's label: a property name or a script block. Ctrl+C stops the run: running items are stopped and the rest are counted as skipped.

Examples

Authored help example

EXAMPLE 1

$port = 443; $servers | ForEach-ConsoleItem -Parallel -ThrottleLimit 8 -Name Name { Test-NetConnection $_.Name -Port $using:port -InformationLevel Quiet }

Check servers in parallel

EXAMPLE 2

Get-ChildItem *.log | ForEach-ConsoleItem { Compress-Archive $_ "$($_.BaseName).zip" -Force }

One at a time, in the current scope

EXAMPLE 3

1..40 | Invoke-ConsoleRun -Parallel -ThrottleLimit 8 -TimeoutSeconds 10 -Title 'Patching web farm' -Name { "web$('{0:d2}' -f $_)" } {
    Start-Sleep -Milliseconds (Get-Random -Minimum 200 -Maximum 1500)
    if ($_ % 13 -eq 0) { throw "web$_ did not come back after the reboot" }
}

Forty items in parallel with a title and a time limit: items that throw or run past 10 seconds are failures, listed when the run ends

Parameters

-InputObject PSObject optionalpipeline: True (ByValue): The items (pipeline input).
-Name Object optionalaliases: Label: Each item's label in the view: a property name or a script block ($_ is the item). Default a name-like property, or the item's text.
-Parallel SwitchParameter optional: Runs items at the same time, each in its own runspace (pass caller variables with $using:name).
-ScriptBlock ScriptBlock requiredposition: 0: The script block run for each item ($_ is the item).
-ThrottleLimit Int32 optional: How many items run at the same time with -Parallel (default 5).
-TimeoutSeconds Double optional: Seconds an item may run with -Parallel before it is stopped and counted as failed (default no limit; ignored with a warning without -Parallel).
-Title Object optional: A title above the live view (markup).
-Unordered SwitchParameter optional: Writes each item's output as soon as it finishes instead of in input order (when the live view is not showing).

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.