Write-MtTestProgress
SYNOPSIS
Shows where a long-running test is (its stage, the items done, what it is working on and its errors) in the Maester console.
SYNTAX
Progress (Default)
Write-MtTestProgress [-Stage <String>] [-StageNumber <Int32>] [-StageCount <Int32>] [-Completed <Int32>]
[-Total <Int32>] [-Failed <Int32>] [-Running <Int32>] [-Current <String[]>] [-Status <String>]
[-Stages <String[]>] [-Items <Object[]>] [-Results <Object>] [-Groups <Object[]>] [-GroupLabel <String>]
[-ErrorMessage <String[]>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
Clear
Write-MtTestProgress [-Clear] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
For a test, or the instance source of a family, that runs a tool for a long time and knows how far the tool has got: the stage it is in, how many of the items of that stage are done, which items it is working on and the errors it reported. Write-MtTestOutput shows the tool's log; this shows the progress that the log is hard to read it from.
In the full-screen dashboard of an interactive run, the progress is a header at the top of the box that Write-MtTestOutput opens: the stage, a bar of the items done with the counts, what the work is on now, and the newest two errors. Each call replaces the progress of the call before, so pass every part you know each time. A call with only -ErrorMessage adds the errors and keeps the progress.
Otherwise (the compact layout, CI and redirected output) a line is written to the host when the stage changes, each error as it comes, and the counts at most every ten seconds.
A tool that runs in another process, in any language, can report its progress without calling this command: a line it writes that Write-MtTestOutput is given, of the form
##maester[progress] {"stage":"Exporting data","stageNumber":1,"stageCount":3,"completed":12,"total":40} ##maester[error] The export of Users failed: Forbidden
is passed to this command instead of being shown in the log. The JSON object takes the names of the parameters of this command (any case); the parts it leaves out are empty.
Maester removes the progress when the test or the instance source finishes, with the box.
EXAMPLES
EXAMPLE 1
Write-MtTestProgress -Stage 'Exporting tenant data' -StageNumber 1 -StageCount 3 -Completed 12 -Total 40 -Running 2 -Current 'Users', 'Groups'
Shows that the work is in the first of three stages, with 12 of its 40 items done and two running.
EXAMPLE 2
Write-MtTestProgress -Stage 'Running tests' -Results @{ Passed = 80; Failed = 12; Total = 300; Running = 4 } -GroupLabel 'Pillars' -Groups @{ Name = 'Identity'; Passed = 50; Failed = 8; Total = 120 }, @{ Name = 'Devices'; Passed = 30; Failed = 4; Total = 90 }
Shows the results of the tool's own tests in the dashboard's Results panel and result blocks, and its pillars where the products are listed.
Each item that finishes with a time (in -Items, in any stage) is also kept: while the box is open the Pace graph next to the logo draws how long each took, and the Slowest panel lists the slowest.
EXAMPLE 3
Write-MtTestProgress -ErrorMessage 'The export of Devices failed: Forbidden'
Adds an error to the box, keeping the progress.
EXAMPLE 4
&1 | Write-MtTestOutput -Title 'Collecting the tenant data'
The script writes lines such as '##maester[progress] {"stage":"Exporting","completed":3,"total":9}' to standard output; they set the progress, and its other lines are shown in the box.
PARAMETERS
-Stage
The name of the stage the work is in, such as "Exporting tenant data".
Type: String
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-StageNumber
The number of the stage, from 1.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-StageCount
How many stages there are.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Completed
The items of the stage that are done and did not fail.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Total
The items of the stage. With a total the header shows a bar of the items done (completed and failed), the percentage, and the time left once there is something to go on.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Failed
The items of the stage that failed.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Running
The items of the stage that are running now.
Type: Int32
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Current
What the work is on now, such as the names of the items running.
Type: String[]
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Status
A line of status that fits no other part, such as "Waiting for the throttling limit".
Type: String
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Stages
The names of all the stages, in order. The header draws them as a track, like the phases of a Maester run: the stages before -StageNumber done, that one running, the others to come.
Type: String[]
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Items
The items running and the ones that finished last (such as the exports or tests of a tool), shown the way the dashboard shows Maester's own tests: the ones running with a spinner and the time they have run, the ones that finished with their result and how long they took. Each is a hashtable or object with Id, and optionally Title, Status (Running, Passed, Failed, TimedOut or Skipped; Running when left out), Detail (what it is doing, or why it failed) and Seconds. Outside the dashboard each item that finished is written once, with its result and time.
Type: Object[]
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Results
The results of the work so far, when it is a tool that runs tests of its own: a hashtable or object with Passed, Failed, Error, Investigate, Skipped, Running and Total, and optionally Name. While the box is open the dashboard shows them in place of Maester's own: in its Results panel, under Name (or the title of the box), and, before Maester's tests start, as a block for each item over the box.
Type: Object
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Groups
The results by group, such as the pillars of an assessment: each a hashtable or object with Name and the counts of -Results. While the box is open the dashboard lists them where it lists the products, with a bar and the counts of each.
Type: Object[]
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-GroupLabel
What the groups are called, such as "Pillars": the title of the box that lists them.
Type: String
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ErrorMessage
Errors the work reported. They are listed under the progress, newest last, and counted on the box.
Type: String[]
Parameter Sets: Progress
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Clear
Removes the progress and the errors from the box.
Type: SwitchParameter
Parameter Sets: Clear
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
Determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider, such as the progress bars generated by Write-Progress.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.