IMPROVED PowerShell Countdown Timer

I made an earlier post on this site that demonstrated a simple Count-Down timer that could be used to pause a PowerShell script for x number of minutes and display a countdown timer to indicate how much wait time is remaining. This NEW and IMPROVED CountDown timer expands on that same idea, adding the ability to specify Hours, Minutes, or Seconds and also includes a simple Help feature as well.

The old CountDown timer used the simplistic Function(argument) format as follows:

function CountDown($waitMinutes)

This NEW and IMPROVED version uses the param declaration:

function CountDown() {
    param( [int]$hours=0,
           [int]$minutes=0,
           [int]$seconds=0,
           [switch]$help)

Note that all parameter values are all defaulted to zero and can be specified either by name or positionally specified without names.
For Example, the following invocations are equivalent:

CountDown 0 0 1
is the same as:  Countdown -seconds 1
            or:  Countdown -s 1

Countdown 1
is the same as:  Countdown -hours 1
            or:  Countdown -h 1

There is also a HELP [switch] parameter that, when invoked will display a Here-String that describes the function and its use. This same help output will be triggered if no parameters are passed. Using a here-string makes the help setup very easy as multi-line text can be can be enclosed within a single pair of quotes wrapped with ampersands:

$HelpInfo = @"
Function : CountDown
By       : xb90 at http://poshtips.com
Date     : 02/22/2011
Purpose  : Pauses a script for the specified period of time and displays a count-down timer to indicate the time remaining.
Usage    : Countdown [-Help][-hours n][-minutes n][seconds n]
           where  
              -Help       displays this help
              -Hours n    specify the number of hours (default=0)
              -Minutes n  specify the number of minutes (default=0)
              -Seconds n  specify the number of seconds (default=0)
"@

Ok, that’s enough jabber about the function – let’s take a look:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

function CountDown() {
    param(
    [int]$hours=0,
    [int]$minutes=0,
    [int]$seconds=0,
    [switch]$help)
    $HelpInfo = @"
 
Function : CountDown
By       : xb90 at http://poshtips.com
Date     : 02/22/2011
Purpose  : Pauses a script for the specified period of time and displays
 a count-down timer to indicate the time remaining.
Usage    : Countdown [-Help][-hours n][-minutes n][-seconds n]
           where      
           -Help       displays this help
           -Hours n    specify the number of hours (default=0)
           -Minutes n  specify the number of minutes (default=0)
           -Seconds n  specify the number of seconds (default=0)
"@    
 
    if ($help -or (!$hours -and !$minutes -and !$seconds)){
        write-host $HelpInfo
        return
        }
    $startTime = get-date
    $endTime = $startTime.addHours($hours)
    $endTime = $endTime.addMinutes($minutes)
    $endTime = $endTime.addSeconds($seconds)
    $timeSpan = new-timespan $startTime $endTime
    write-host $([string]::format("`nScript paused for {0:#0}:{1:00}:{2:00}",$hours,$minutes,$seconds)) -backgroundcolor black -foregroundcolor yellow
    while ($timeSpan -gt 0) {
        $timeSpan = new-timespan $(get-date) $endTime
        write-host "`r".padright(40," ") -nonewline
        write-host "`r" -nonewline
        write-host $([string]::Format("`rTime Remaining: {0:d2}:{1:d2}:{2:d2}", `
        $timeSpan.hours, `
        $timeSpan.minutes, `
        $timeSpan.seconds)) `
        -nonewline -backgroundcolor black -foregroundcolor yellow
        sleep 1
        }
    write-host ""
    }

Personally, I find this to be so useful that I add it to my $Profile startup script so that it is more easily accessed without the need to add code to a script or call via dot-sourcing. To do this, simply add the code above to your $profile script. In addition I create a shortened alias named “CntDnt” as follows:

new-item -path alias:CntDn -value CountDown |out-null