< Back
Write-Progress
Post
NAME Write-Progress
SYNOPSIS
Displays a progress bar within a Windows PowerShell command window.
SYNTAX
Write-Progress [-Activity] <String> [[-Status] <String>] [[-Id] <Int32>] [-Completed] [-CurrentOperation <String>] [-ParentId <Int32>]
[-PercentComplete <Int32>] [-SecondsRemaining <Int32>] [-SourceId <Int32>] [<CommonParameters>]
DESCRIPTION
The Write-Progress cmdlet displays a progress bar in a Windows PowerShell command window that depicts the status of a running command or script.
You can select the indicators that the bar reflects and the text that appears above and below the progress bar.
PARAMETERS
-Activity <String>
Specifies the first line of text in the heading above the status bar. This text describes the activity whose progress is being reported.
Required? true
Position? 0
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Completed [<SwitchParameter>]
Indicates whether the progress bar is visible. If this parameter is omitted, Write-Progress displays progress information.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-CurrentOperation <String>
Specifies the line of text below the progress bar. This text describes the operation that is currently taking place.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Id <Int32>
Specifies an ID that distinguishes each progress bar from the others. Use this parameter when you are creating more than one progress bar in a
single command. If the progress bars do not have different IDs, they are superimposed instead of being displayed in a series.
Required? false
Position? 2
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ParentId <Int32>
Specifies 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 None
Accept pipeline input? False
Accept wildcard characters? false
-PercentComplete <Int32>
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 None
Accept pipeline input? False
Accept wildcard characters? false
-SecondsRemaining <Int32>
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 None
Accept pipeline input? False
Accept wildcard characters? false
-SourceId <Int32>
Specifies the source of the record.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Status <String>
Specifies the second line of text in the heading above the status bar. This text describes current state of the activity.
Required? false
Position? 1
Default value None
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
None
You cannot pipe input to this cmdlet.
OUTPUTS
None
Write-Progress does not generate any output.
NOTES
* If the progress bar does not appear, check the value of the $ProgressPreference variable. If the value is set to SilentlyContinue, the
progress bar is not displayed. For more information about Windows PowerShell preferences, see about_Preference_Variables.
The parameters of the cmdlet correspond to the properties of the ProgressRecord class ( System.Management.Automation.ProgressRecord *). For
more information, see ProgressRecordhttps://msdn.microsoft.com/en-us/library/system.management.automation.progressrecord(v=vs.85).aspx
(https://msdn.microsoft.com/en-us/librar ... s.85).aspx ) in the Windows PowerShell Software
Development Kit (SDK).
Example 1: Display the progress of a For loop
PS C:\\>for ($I = 1; $I -le 100; $I++ )
{Write-Progress -Activity "Search in Progress" -Status "$I% Complete:" -PercentComplete $I;}
This command displays the progress of a For loop that counts from 1 to 100. The Write-Progress command includes a status bar heading ("activity"),
a status line, and the variable $I (the counter in the For loop), which indicates the relative completeness of the task.
Example 2: Display the progress of nested For loops
PS C:\\>for($I = 1; $I -lt 101; $I++ )
{Write-Progress -Activity Updating -Status 'Progress->' -PercentComplete $I -CurrentOperation OuterLoop; `
PS C:\\> for($j = 1; $j -lt 101; $j++ )
{Write-Progress -Id 1 -Activity Updating -Status 'Progress' - PercentComplete $j -CurrentOperation InnerLoop} }
Updating
Progress ->
[ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo]
OutsideLoop
Updating
Progress
[oooooooooooooooooo ]
InnerLoop
This example displays the progress of two nested For loops, each of which is represented by a progress bar.
The Write-Progress command for the second progress bar includes the Id parameter that distinguishes it from the first progress bar. Without the Id
parameter, the progress bars would be superimposed on each other instead of being displayed one below the other.
Example 3: Display the progress while searching for a string
PS C:\\>$Events = Get-EventLog -logname system
PS C:\\> $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 the progress of a command to find the string "bios" in the System event log.
In the first line of the command, the Get-EventLog cmdlet gets the events in the System log and stores them in the $Events variable.
In the second line, the events are piped to the ForEach-Object cmdlet. Before processing begins, the Clear-Host cmdlet is used to clear the
screen, the $I counter variable is set to zero, and the $out output variable is set to the empty string.
In the third line, which is the Process script block of the ForEach-Object cmdlet, the cmdlet searches the message property of each incoming
object for "bios". If the string is found, the message is added to $out. Then, the $I counter variable is incremented to record that another event
has been examined.
The fourth line uses the Write-Progress cmdlet with values for the Activity and Status text fields that create the first and second lines of the
progress bar heading, respectively. 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 that result by 100.
In the last line, the End parameter of the ForEach-Object cmdlet is used to display the messages that are stored in the $out variable.
RELATED LINKS
Online Version: http://go.microsoft.com/fwlink/?LinkId=821879
Write-Debug
Write-Error
Write-Host
Write-Information
Write-Output
Write-Progress
Write-Verbose
Write-Warning
SYNOPSIS
Displays a progress bar within a Windows PowerShell command window.
SYNTAX
Write-Progress [-Activity] <String> [[-Status] <String>] [[-Id] <Int32>] [-Completed] [-CurrentOperation <String>] [-ParentId <Int32>]
[-PercentComplete <Int32>] [-SecondsRemaining <Int32>] [-SourceId <Int32>] [<CommonParameters>]
DESCRIPTION
The Write-Progress cmdlet displays a progress bar in a Windows PowerShell command window that depicts the status of a running command or script.
You can select the indicators that the bar reflects and the text that appears above and below the progress bar.
PARAMETERS
-Activity <String>
Specifies the first line of text in the heading above the status bar. This text describes the activity whose progress is being reported.
Required? true
Position? 0
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Completed [<SwitchParameter>]
Indicates whether the progress bar is visible. If this parameter is omitted, Write-Progress displays progress information.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-CurrentOperation <String>
Specifies the line of text below the progress bar. This text describes the operation that is currently taking place.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Id <Int32>
Specifies an ID that distinguishes each progress bar from the others. Use this parameter when you are creating more than one progress bar in a
single command. If the progress bars do not have different IDs, they are superimposed instead of being displayed in a series.
Required? false
Position? 2
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ParentId <Int32>
Specifies 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 None
Accept pipeline input? False
Accept wildcard characters? false
-PercentComplete <Int32>
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 None
Accept pipeline input? False
Accept wildcard characters? false
-SecondsRemaining <Int32>
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 None
Accept pipeline input? False
Accept wildcard characters? false
-SourceId <Int32>
Specifies the source of the record.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Status <String>
Specifies the second line of text in the heading above the status bar. This text describes current state of the activity.
Required? false
Position? 1
Default value None
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
None
You cannot pipe input to this cmdlet.
OUTPUTS
None
Write-Progress does not generate any output.
NOTES
* If the progress bar does not appear, check the value of the $ProgressPreference variable. If the value is set to SilentlyContinue, the
progress bar is not displayed. For more information about Windows PowerShell preferences, see about_Preference_Variables.
The parameters of the cmdlet correspond to the properties of the ProgressRecord class ( System.Management.Automation.ProgressRecord *). For
more information, see ProgressRecordhttps://msdn.microsoft.com/en-us/library/system.management.automation.progressrecord(v=vs.85).aspx
(https://msdn.microsoft.com/en-us/librar ... s.85).aspx ) in the Windows PowerShell Software
Development Kit (SDK).
Example 1: Display the progress of a For loop
PS C:\\>for ($I = 1; $I -le 100; $I++ )
{Write-Progress -Activity "Search in Progress" -Status "$I% Complete:" -PercentComplete $I;}
This command displays the progress of a For loop that counts from 1 to 100. The Write-Progress command includes a status bar heading ("activity"),
a status line, and the variable $I (the counter in the For loop), which indicates the relative completeness of the task.
Example 2: Display the progress of nested For loops
PS C:\\>for($I = 1; $I -lt 101; $I++ )
{Write-Progress -Activity Updating -Status 'Progress->' -PercentComplete $I -CurrentOperation OuterLoop; `
PS C:\\> for($j = 1; $j -lt 101; $j++ )
{Write-Progress -Id 1 -Activity Updating -Status 'Progress' - PercentComplete $j -CurrentOperation InnerLoop} }
Updating
Progress ->
[ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo]
OutsideLoop
Updating
Progress
[oooooooooooooooooo ]
InnerLoop
This example displays the progress of two nested For loops, each of which is represented by a progress bar.
The Write-Progress command for the second progress bar includes the Id parameter that distinguishes it from the first progress bar. Without the Id
parameter, the progress bars would be superimposed on each other instead of being displayed one below the other.
Example 3: Display the progress while searching for a string
PS C:\\>$Events = Get-EventLog -logname system
PS C:\\> $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 the progress of a command to find the string "bios" in the System event log.
In the first line of the command, the Get-EventLog cmdlet gets the events in the System log and stores them in the $Events variable.
In the second line, the events are piped to the ForEach-Object cmdlet. Before processing begins, the Clear-Host cmdlet is used to clear the
screen, the $I counter variable is set to zero, and the $out output variable is set to the empty string.
In the third line, which is the Process script block of the ForEach-Object cmdlet, the cmdlet searches the message property of each incoming
object for "bios". If the string is found, the message is added to $out. Then, the $I counter variable is incremented to record that another event
has been examined.
The fourth line uses the Write-Progress cmdlet with values for the Activity and Status text fields that create the first and second lines of the
progress bar heading, respectively. 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 that result by 100.
In the last line, the End parameter of the ForEach-Object cmdlet is used to display the messages that are stored in the $out variable.
RELATED LINKS
Online Version: http://go.microsoft.com/fwlink/?LinkId=821879
Write-Debug
Write-Error
Write-Host
Write-Information
Write-Output
Write-Progress
Write-Verbose
Write-Warning