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

Write-Verbose

Write-Error

Write-Host

Write-Debug

Write-Output

Write-Warning