Exploring the New-TimeSpan Cmdlet in PowerShell

Welcome back to Wahmans Powershell blog! Today, we’re diving into an incredibly useful cmdlet in PowerShell: New-TimeSpan. This cmdlet helps you create a TimeSpan object, which represents a time interval — that is, the amount of time between two DateTime values or a custom duration you define. Whether you’re scheduling tasks, logging durations, or calculating intervals, New-TimeSpan is a valuable tool to have in your PowerShell toolbox.

Basic Syntax

New-TimeSpan [-Start] <DateTime> [-End] <DateTime>
New-TimeSpan [-Days <int>] [-Hours <int>] [-Minutes <int>] [-Seconds <int>]

You can use it with specific dates or simply by specifying an interval using days, hours, minutes, etc.

Example 1: Basic TimeSpan of 1 Hour

This example is perfect for beginners. Here we create a TimeSpan representing 1 hour.

$ts = New-TimeSpan -Hours 1
Write-Output $ts

Output: 01:00:00 – a TimeSpan of 1 hour.

Example 2: Time Between Two Dates

This one compares two DateTime values to find the elapsed time between them.

$start = Get-Date -Year 2024 -Month 1 -Day 1
$end = Get-Date -Year 2024 -Month 6 -Day 1
$span = New-TimeSpan -Start $start -End $end
Write-Output $span

The result will output the number of days and duration between January 1st and June 1st, 2024.

Example 3: Time Until a Future Event

This example shows you how to calculate the time left until an upcoming event — handy for countdowns!

$now = Get-Date
$target = Get-Date -Year 2024 -Month 12 -Day 31 -Hour 23 -Minute 59
$timeRemaining = New-TimeSpan -Start $now -End $target
Write-Output "Time left until New Year's Eve: $timeRemaining"

Example 4: Using TimeSpan in a Wait Timer

In advanced scripting, you sometimes want to pause execution for a specific interval. Here’s how to do it using New-TimeSpan and Start-Sleep.

# Create a 2 minute and 30 second time span
$delay = New-TimeSpan -Minutes 2 -Seconds 30

Write-Output "Sleeping for $($delay.TotalSeconds) seconds..."
Start-Sleep -Seconds $delay.TotalSeconds
Write-Output "Awake!"

This can be great for throttling API calls or delaying actions conditionally.

Wrap-Up

As you’ve seen today, the New-TimeSpan cmdlet is a flexible way to work with durations and compute differences between times in PowerShell. From simple intervals to advanced execution control, this cmdlet has a wide range of use cases.

Happy scripting, and I will see you in the next post!