Cmdlet

New-ConsoleRun

Module: ConsoleMonster
Inputs: None
Outputs: ConsoleMonster.Live.LiveRun

Starts a bounded run dashboard for work scheduled by your script.

Syntax

New-ConsoleRun
[-Group <Object>]
[-HeightPercent <Int32>]
[-InteractiveKeys]
-Items <PSObject[]>
[-Name <Object>]
[-NoLive]
[-ProgressEvery <Int32>]
[-ProgressSeconds <Double>]
[-ReportPath <String>]
[-Target <Object>]
[-Title <String>]
[-Trend]
[<CommonParameters>]

Parameter set: All Parameter Sets

Description

Declares the queued items and returns a LiveRun handle. Use Update-ConsoleRun as workers start or finish and Complete-ConsoleRun in a finally block. Finished items stream above the live dashboard; failures and warnings remain pinned. The dashboard uses at most 40 percent of terminal height by default. CI and redirected hosts use append-only lines with periodic totals. This command does not execute work or change its results or exit code. Name, Target and Group accept property names or script blocks evaluated once, before the session starts. Interactive keys are opt-in: p pauses the log, f filters it to problems, g toggles groups, and ? shows help.

Examples

Example 1

$files = @(Get-ChildItem *.log)
$run = New-ConsoleRun -Items $files -Title 'Archive logs' -Name Name -Target DirectoryName
try {
    for ($i = 0; $i -lt $files.Count; $i++) {
        Update-ConsoleRun $run -Index $i -State Running -Phase 'archiving'
        try { Compress-Archive $files[$i].FullName "$($files[$i].FullName).zip" -ErrorAction Stop; Update-ConsoleRun $run -Index $i -State Pass }
        catch { Update-ConsoleRun $run -Index $i -State Fail -Message $_.Exception.Message }
    }
} finally { Complete-ConsoleRun $run }

Track a script without changing its output

Example 2

$run = New-ConsoleRun -Items $checks -Name Name -Target Server -Group Category -NoLive -ProgressEvery 20

Use append-only output in CI

Parameters

-Group Object optional: An optional group property or script block.
-HeightPercent Int32 optional: Maximum terminal height percentage used by the live dashboard (default 40).
-InteractiveKeys SwitchParameter optional: Enable optional p/f/g/? keys when keyboard input is available.
-Items PSObject[] required: The complete input list. Updates identify each item by zero-based position.
-Name Object optional: A name property or script block ($_ is the item). Default the item's display title.
-NoLive SwitchParameter optional: Force append-only output without cursor movement.
-ProgressEvery Int32 optional: Print CI progress after this many items (default 25). Zero disables the count trigger.
-ProgressSeconds Double optional: Print CI progress at this interval in seconds (default 10). Zero disables the timer.
-ReportPath String optional: Optional report location shown in the final summary.
-Target Object optional: An optional target property or script block.
-Title String optional: The literal run title.
-Trend SwitchParameter optional: Show the throughput trend next to its rate.

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.