Format time and date output of PowerShell New-TimeSpan

• Author
• Recent Posts

Emanuel Halapciuc

Emanuel is an IT consultant who has worked for 20 years in the industry. He is currently involved in a deployment project for the European Commission and focuses on Active Directory, Group Policy, Azure, and automation with PowerShell.

Latest posts by Emanuel Halapciuc (see all)

• Get and set IP address with PowerShell - Wed, Oct 18 2023
• If a Windows service hangs, restart the service with PowerShell - Mon, Dec 12 2022
• Install, remove, list, and set default printer with PowerShell - Mon, Nov 7 2022

My function displays the number of weeks, days, hours, minutes, and seconds. For short time spans, Prerequisites

My function works with any version of PowerShell that supports the PowerShell New-Timespan cmdlet. Basically, this means that any currently available PowerShell version is supported. You can test whether New-Timespan is available on your system like this:

Get-Command New-TimeSpan

Testing support for Get TimeSpanPretty

If you receive an output like in the screenshot above, you can use Get-TimespanPretty.

Examples

Let's see Get-TimespanPretty in action. I like to learn by example. For more details and a formal description of the function, you can run Get-Help, as shown below.

Get-Help Get-TimeSpanPretty

or

Get-Help Get-TimeSpanPretty -Examples

Use with New-TimeSpan

Simply pipe the output of New-TimeSpan to Get-TimespanPretty to get a simpler, prettier format for the time interval. In the example below, you'll first see the original output, and then you'll get the more human-friendly format created by my function.

New-TimeSpan -Start "2022-09-15 14:55" -End "2022-10-05 11:20:05"
New-TimeSpan -Start "2022-09-15 14:55" -End "2022-10-05 11:20:05" | Get-TimeSpanPretty

Get TimeSpanPretty provides a more concise way to view a time interval

Measure the execution time of a script with New-TimeSpan

As before, you can use New-TimeSpan to measure the time it took to run one or more PowerShell commands. This can be very useful for measuring scripts that need to run a long time to complete their task.

$StartTime = Get-Date

# your (long-running) commands go here
# Optimize-VHD -Path C:\VMs\FS1-UserData.vhdx -Mode Full
# Get-Aduser -Filter {Department -like "*Manager*"} | Remove-ADUser -Confirm:$false

$EndTime = Get-Date

New-TimeSpan -Start $StartTime -End $EndTime | Get-TimeSpanPretty 

Measuring the time it takes to run a PowerShell command

As you can see in the screenshot above, it took the PowerShell script one minute and 48 seconds to complete the task.

Measure the execution time of a script with Measure-Command

Another way to measure the execution time of a script is to use Measure-Command. As before, I'll pipe the output to Get-TimespanPretty.

Measure-Command {Get-Service | foreach {Start-Sleep -Milliseconds 15}} 
Measure-Command {Get-Service | foreach {Start-Sleep -Milliseconds 15}} | Get-TimeSpanPretty 

Another way to measure the duration of one or more commands

As in the previous example, you first see the raw output and then the human-friendly version created by my function.

The Get-TimespanPretty function

Below, you'll find the complete code for my Get-TimespanPretty function. Instead of playing the copy-and-paste game every time you need it, you can include it in your PowerShell profile script or in a module.

Function Get-TimeSpanPretty {
<#
.Synopsis
   Displays the time span between two dates in a single line, in an easy-to-read format
.DESCRIPTION
   Only non-zero weeks, days, hours, minutes and seconds are displayed.
   If the time span is less than a second, the function display "Less than a second."
.PARAMETER TimeSpan
   Uses the TimeSpan object as input that will be converted into a human-friendly format
.EXAMPLE
   Get-TimeSpanPretty -TimeSpan $TimeSpan
   Displays the value of $TimeSpan on a single line as number of weeks, days, hours, minutes, and seconds.
.EXAMPLE
   $LongTimeSpan | Get-TimeSpanPretty
   A timeline object is accepted as input from the pipeline. 
   The result is the same as in the previous example.
.OUTPUTS
   String(s)
.NOTES
   Last changed on 28 July 2022
#>

    [CmdletBinding()]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory,ValueFromPipeline)][ValidateNotNull()][timespan]$TimeSpan
    )

    Begin {}
    Process{

        # Initialize $TimeSpanPretty, in case there is more than one timespan in the input via pipeline
        [string]$TimeSpanPretty = ""
    
        $Ts = [ordered]@{
            Weeks   = [math]::Floor($TimeSpan.Days / 7)
            Days    = [int]$TimeSpan.Days % 7
            Hours   = [int]$TimeSpan.Hours
            Minutes = [int]$TimeSpan.Minutes
            Seconds = [int]$TimeSpan.Seconds
        } 

        # Process each item in $Ts (week, day, etc.)
        foreach ($i in $Ts.Keys){

            # Skip if zero
            if ($Ts.$i -ne 0) {
                
                # Append the value and key to the string
                $TimeSpanPretty += "{0} {1}, " -f $Ts.$i,$i
                
            } #Close if
    
        } #Close for
    
    # If the $TimeSpanPretty is not 0 (which could happen if start and end time are identical.)
    if ($TimeSpanPretty.Length -ne 0){

        # delete the last coma and space
        $TimeSpanPretty = $TimeSpanPretty.Substring(0,$TimeSpanPretty.Length-2)
    }
    else {
        
        # Display "Less than a second" instead of an empty string.
        $TimeSpanPretty = "Less than a second"
    }

    $TimeSpanPretty

    } # Close Process

    End {}

} #Close function Get-TimeSpanPretty

Summary

My function, Get-TimeSpanPretty, gives you a quick and easy way to convert TimeSpan objects into a user-friendly format. You can include it in your scripts or PowerShell-generated reports for better-looking output.