Today's cmdlet of the day is Test-Connection. Test-Connection is a cmdlet that not surprisingly tests your network connection. Think of Test-Connection as PowerShell's implementation of the popular ping utility. Even though both have ICMP in common, you'll see that the two methods are a little different under the covers.

Using this cmdlet is simple. At its most basic, just specify a ComputerName parameter, and it will send four ICMP requests to the destination host.

PS> Test-Connection -ComputerName google.com
Source        Destination     IPV4Address      IPV6Address                              Bytes    Time(ms)
------        -----------     -----------      -----------                              -----    --------
MACWINVM      google.com      172.217.0.14     2607:f8b0:4009:80c::200e                 32       47
MACWINVM      google.com      172.217.0.14     2607:f8b0:4009:80c::200e                 32       90
MACWINVM      google.com      172.217.0.14     2607:f8b0:4009:80c::200e                 32       88
MACWINVM      google.com      172.217.0.14     2607:f8b0:4009:80c::200e                 32       205

This output looks similar to ping.exe and, on the surface, it is but Test-Connection issues the ICMP request a little differently. Unlike ping.exe, Test-Connection is using the local computer's WMI class Win32_PingStatus to send the ICMP request. Using the local WMI repository means you'd better be sure your local WMI repository is healthy else Test-Connection will not work.

Test-Connection's Object Output

Also, as with the beauty of PowerShell, this cmdlet doesn't merely return what immediately shows up in the console. We see rich objects that we can gather more information from.

If I assign the output to a variable and then check out the properties, you can see that I've gathered a lot more useful information.

PS> $pingResults | Get-Member
TypeName: System.Management.ManagementObject#root\cimv2\Win32_PingStatus
Name                           MemberType     Definition
----                           ----------     ----------
PSComputerName                 AliasProperty  PSComputerName = __SERVER
Address                        Property       string Address {get;set;}
BufferSize                     Property       uint32 BufferSize {get;set;}
NoFragmentation                Property       bool NoFragmentation {get;set;}
PrimaryAddressResolutionStatus Property       uint32
PrimaryAddressResolutionStatus {get;set;}
ProtocolAddress                Property       string ProtocolAddress {get;set;}
ProtocolAddressResolved        Property       string
ProtocolAddressResolved {get;set;}
RecordRoute                    Property       uint32 RecordRoute {get;set;}
ReplyInconsistency             Property       bool ReplyInconsistency {get;set;}
ReplySize                      Property       uint32 ReplySize {get;set;}
ResolveAddressNames            Property       bool ResolveAddressNames {get;set;}
ResponseTime                   Property       uint32 ResponseTime {get;set;}
ResponseTimeToLive             Property       uint32 ResponseTimeToLive {get;set;}
RouteRecord                    Property       string[] RouteRecord {get;set;}
RouteRecordResolved            Property       string[] RouteRecordResolved {get;set;}
SourceRoute                    Property       string SourceRoute {get;set;}
SourceRouteType                Property       uint32 SourceRouteType {get;set;}
StatusCode                     Property       uint32 StatusCode {get;set;}
Timeout                        Property       uint32 Timeout {get;set;}
TimeStampRecord                Property       uint32[] TimeStampRecord {get;set;}
TimeStampRecordAddress         Property       string[] TimeStampRecordAddress {get;set;} TimeStampRecordAddressResolved Property       string[]
TimeStampRecordAddressResolved {get;set;}
TimestampRoute                 Property       uint32 TimestampRoute {get;set;}
<SNIP>

If you're testing internal hosts, Test-Connection will use DCOM to authenticate to remote hosts. By default, it will use Packet level DCOM authentication but the authentication type can always be changed with the DcomAuthentication parameter.

Using Background Jobs

This cmdlet can also run as a background job. Background jobs come in handy if you've got lots of remote computers to ping and rather than wait forever for ones that'll eventually time out, just send it to a background job.

According to the PowerShell help for Test-Connection, it says that PowerShell remoting must be enabled on both the local and remote computers, but this is not true. As you can see below, I'm testing google.com, and the command still works great.

Test-Connection -AsJob -ComputerName google.com
Get-Job | Receive-Job

Keeping it Simple

Finally, if you're just looking for a binary yes/no answer to if a computer is responding or not, you can always use the Quiet parameter. A common string I always use to quickly see if a server is online or not is to use Quiet and Count of 1 to force Test-Connection to send a single ICMP request.

PS> Test-Connection -ComputerName google.com -Quiet -Count 1
True

That's it for our cmdlet of the day! We covered the majority of what's possible with Test-Connection but, as always, check out the PowerShell help content or head over to the Microsoft documentation for a full breakdown.

Join the Jar Tippers on Patreon

It takes a lot of time to write detailed blog posts like this one. In a single-income family, this blog is one way I depend on to keep the lights on. I'd be eternally grateful if you could become a Patreon patron today!

Become a Patron!