Prof. Powershell

PowerShell's Write-Progress Explored

Jeffery Hicks breaks down how to use the Write-Progress cmdlet.

• By Jeffery Hicks
• 02/11/2014

The last few lessons have been on displaying status messages in your PowerShell scripts and functions. There is also a built-in cmdlet that doesn't get used as much as it should so I thought I'd give you a quick introduction to Write-Progress.

This cmdlet has been around from the very beginning of PowerShell. You've probably seen something like this before:

To use the cmdlet you are required to specify an Activity. You can also specify a status, what the script is currently doing and a percentage complete progress bar. Or you can specify seconds remaining which I find harder to calculate, as least for the scripts I write.

Using the scenario from the last lesson to get top level folder usage, I'm going to use Write-Progress. Here's my path.

$Path = "C:\Scripts"

I like using a hash table of parameter values that I can splat to Write-Progress. Personally I find it easier to read and troubleshoot the script.

$progParam=@{
Activity = "Directory Usage Analysis"
CurrentOperation=$path
Status="Querying top level folders"
PercentComplete=0
}

I'm going to go ahead and use all the options. Activity is the only required parameter. Splatting the parameters gets me started.

Write-Progress @progParam

Now to get top level folders. Again, I've arbitrarily thrown in some Start-Sleep commands to make it easier to see the changes in the progress bar.

$top = Get-ChildItem -Path $path -Directory
Start-Sleep -Milliseconds 300

As with my previous articles, I find it easier to use Write-Progress when using ForEach, primarily because I know in advance how many items I have to process so I can calculate a percentage.

#initialize a counter
$i=0

foreach ($folder in $top) {

#calculate percentage
$i++
[int]$pct = ($i/$top.count)*100

 $progParam.CurrentOperation ="Measuring size: $($folder.Name)"
$progParam.Status="Analyzing"
$progParam.PercentComplete = $pct

 Write-Progress @progParam

 start-sleep -Milliseconds 100
$stats = Get-ChildItem -path $folder -Recurse -File |
Measure-Object -Property Length -Sum -Average
[pscustomobject]@{
Path=$folder.Name
Files = $stats.count
SizeKB = [math]::Round($stats.sum/1KB,2)
Avg = [math]::Round($stats.average,2)
}
} #foreach

This is essentially the same code I used last time, except each time through I'm updating the hash table and splatting the new table to Write-Progress. Here's what it looks like (video).

For long running scripts or functions using Write-Progress is very helpful. You can get very creative with this cmdlet so I encourage you to take the time to read the full cmdlet help and examples. Next time, we'll look at one more status progress example.