Write-Progress
SYNOPSIS
Displays a progress bar within a Windows PowerShell command window.
SYNTAX
Write-Progress [-activity] <string> [-status] <string> [[-id] <int>] [-percentComplete <int>] [-secondsRemaining <int>] [-currentOperation <string>] [-parentId <int>] [-completed] [-sourceId <int>] [<CommonParameters>]
DETAILED DESCRIPTION
Displays a progress bar within a Windows PowerShell command window. Whether the progress bar is displayed is controlled by the $ProgressPreference variable. To see the value of that variable, type $ProgressPreference. Valid values for the variable are: SilentlyContinue, Continue, Stop and Inquire. If the value is set to SilentlyContinue, no progress information is displayed in the console. To set the value of variable for the session, type $ProgressPreference = "<value>". Write-Progress can use data about the state of a running command or script to provide a visual indication of progress within the console window.
PARAMETERS
-activity <string>
Specifies a string that describes the activity about which progress is being reported. It appears as the first heading above the progress bar.
Required? |
true |
Position? |
1 |
Default value |
|
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-status <string>
Specifies a string that describes current state of the activity about which progress is being reported. It appears as the second heading above the progress bar.
Required? |
true |
Position? |
2 |
Default value |
|
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-id <int>
Specifies the activity identifier for this progress record.
Required? |
false |
Position? |
3 |
Default value |
|
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-percentComplete <int>
Specifies the percentage of the activity that is completed. Use the value -1 if the percentage complete is unknown or not applicable.
Required? |
false |
Position? |
named |
Default value |
-1 |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-secondsRemaining <int>
Specifies the projected number of seconds remaining until the activity is completed. Use the value -1 if the number of seconds remaining is unknown or not applicable.
Required? |
false |
Position? |
named |
Default value |
-1 |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-currentOperation <string>
Describes the operation that is currently taking place.
Required? |
false |
Position? |
named |
Default value |
-1 |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-parentId <int>
Identifies the parent activity of the current activity. Use the value -1 if the current activity has no parent activity.
Required? |
false |
Position? |
named |
Default value |
-1 |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-completed <SwitchParameter>
Indicates whether the progress bar is visible. If set to false, display progress information.
Required? |
false |
Position? |
named |
Default value |
False |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-sourceId <int>
Identifies the source of the record
Required? |
false |
Position? |
named |
Default value |
|
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".
INPUT TYPE
ProgressRecord objects
RETURN TYPE
No output is sent to the pipeline.
NOTES
For more information, type "Get-Help Write-Progress -detailed". For technical information, type "Get-Help Write-Progress -full".
When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".
The parameters of the cmdlet correspond to the properties of the ProgressRecord class in the Software Development Kit (SDK).
EXAMPLE 1
for($i = 1; $i -lt 101; $i++ )
{for($j=0;$j -lt 10000;$j++) {} write-progress "Search in Progress" "% Complete:" -perc $i;}
This command displays progress of a for loop.
EXAMPLE 2
for($i = 1; $i -lt 101; $i++ ) {write-progress Updating progress-> -perc $i} for($i = 1; $i -lt 101; $i++ )
{ write-progress Updating progress -percentcomplete $i -id 1}
This example displays progress of two nested for loops.
Updating
progress
[oooooooooooooooooo ]
Secondary updating
Secondary Progress
[oooooooooooooooooo ]
EXAMPLE 3
$events = get-eventlog -logname system
$events | foreach-object -begin {clear-host;$i=0;$out=""} `
-process {if($_.message -like "*bios*") {$out=$out + $_.Message};
$i = $i+1;`
write-progress -activity "Searching Events" `
-status "Progress:" -percentcomplete ($i/$events.count*100)} `
-end {$out}
This command displays progress while searching for the string "bios" in system event log messages. In the first line of the command, the Get-EventLogcmdlet is used to retrieve and store the events from the system log in the $events variable. In the second line, the events are piped to the ForEach-Objectcmdlet. Before processing begins, the Clear-Host function is used to clear the screen, a counter variable, $i, is set to zero and an output variable, $out, is set to the empty string. In the Process script block of the ForEach-Object cmdlet, on the third line, the message property of each incoming object, represented by the $_ variable, is examined to determine whether it includes the string "bios". If it includes the string, the message is added to the output variable, $out. In the fourth line of the command, the counter variable $i is increment to record that another event has been examined. Next, the Write-Progress cmdlet is called with three parameters specified. The first two parameters, Activity and status, represent header information that appears above the progress bar. The PercentComplete parameter value is calculated by dividing the number of events that have been processed ($i) by the total number of events retrieved ($events.count) and then multiplying by 100. In the last line, the End parameter of the ForEach-Object cmdlet is used to display the messages that included the string "bios", which are stored in the $out variable.
RELATED LINKS