Module:

Microsoft.PowerShell.Management Module

Sends ICMP echo request packets, or pings, to one or more computers.

Test-Connection    [-TargetName] <string[]>    [-Ping]    [-IPv4]    [-IPv6]    [-ResolveDestination]    [-Source <string>]    [-MaxHops <int>]    [-Count <int>]    [-Delay <int>]    [-BufferSize <int>]    [-DontFragment]    [-Quiet]    [-TimeoutSeconds <int>]    [<CommonParameters>]

Test-Connection    [-TargetName] <string[]>    -Repeat    [-Ping]    [-IPv4]    [-IPv6]    [-ResolveDestination]    [-Source <string>]    [-MaxHops <int>]    [-Delay <int>]    [-BufferSize <int>]    [-DontFragment]    [-Quiet]    [-TimeoutSeconds <int>]    [<CommonParameters>]

Test-Connection    [-TargetName] <string[]>    -Traceroute    [-IPv4]    [-IPv6]    [-ResolveDestination]    [-Source <string>]    [-MaxHops <int>]    [-Quiet]    [-TimeoutSeconds <int>]    [<CommonParameters>]

Test-Connection    [-TargetName] <string[]>    -MtuSize    [-IPv4]    [-IPv6]    [-ResolveDestination]    [-Quiet]    [-TimeoutSeconds <int>]    [<CommonParameters>]

Test-Connection    [-TargetName] <string[]>    -TcpPort <int>    [-IPv4]    [-IPv6]    [-ResolveDestination]    [-Source <string>]    [-Count <int>]    [-Delay <int>]    [-Repeat]    [-Quiet]    [-TimeoutSeconds <int>]    [-Detailed]    [<CommonParameters>]

TheTest-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets, orpings, to one or more remote computers and returns the echo response replies. You can use thiscmdlet to determine whether a particular computer can be contacted across an IP network.

You can use the parameters ofTest-Connection to specify both the sending and receiving computers,to run the command as a background job, to set a time-out and number of pings, and to configure theconnection and authentication.

Unlike the familiarping command,Test-Connection returns aTestConnectionCommand+PingStatus object that you can investigate in PowerShell. TheQuietparameter returns aBoolean value in aSystem.Boolean object for each tested connection. Ifmultiple connections are tested, an array ofBoolean values is returned.

This example sends echo request packets from the local computer to the Server01 computer.

Test-Connection -TargetName Server01 -IPv4

   Destination: Server01Ping Source           Address                   Latency BufferSize Status                                                   (ms)        (B)---- ------           -------                   ------- ---------- ------   1 ADMIN1           10.59.137.44                   24         32 Success   2 ADMIN1           10.59.137.44                   39         32 Success   3 ADMIN1           *                               *          * TimedOut   4 ADMIN1           10.59.137.44                   28         32 Success

Test-Connection uses theTargetName parameter to specify the Server01 computer. TheIPv4parameter specifies the protocol for the test.

A series ofTestConnectionCommand+PingStatus objects are sent to the output stream, oneobject per ping reply from the target machine.

This example sends pings from the local computer to several remote computers.

Test-Connection -TargetName Server01, Server02, Server12

This example uses the parameters ofTest-Connection to customize the command. The local computersends a ping test to a remote computer.

Test-Connection -TargetName Server01 -Count 3 -Delay 2 -MaxHops 255 -BufferSize 256

Test-Connection uses theTargetName parameter to specify Server01. TheCount parameterspecifies three pings are sent to the Server01 computer with aDelay of 2-second intervals.

You might use these options when the ping response is expected to take longer than usual, eitherbecause of an extended number of hops or a high-traffic network condition.

This example shows how to run aTest-Connection command as a PowerShell background job.

$job = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path "Servers.txt") }$Results = Receive-Job $job -Wait

TheStart-Job command uses theTest-Connection cmdlet to ping many computers in an enterprise.The value of theTargetName parameter is aGet-Content command that reads a list of computernames from theServers.txt file. The command uses theStart-Job cmdlet to run the command as abackground job and it saves the job in the$job variable.

TheReceive-Job command is instructed to-Wait until the job is completed, and then gets theresults and stores them in the$Results variable.

This example creates a session on the Server01 computer only if at least one of the pings sent tothe computer succeeds.

if (Test-Connection -TargetName Server01 -Quiet) { New-PSSession -ComputerName Server01 }

TheTest-Connection cmdlet pings theServer01 computer, with theQuiet parameter provided.The resulting value is$true if any of the four pings succeed. If none of the pings succeed,the value is$false.

If theTest-Connection command returns a value of$true, the command uses theNew-PSSessioncmdlet to create thePSSession.

Introduced in PowerShell 6.0, theTraceroute parameter maps a route between the local computerand the remote destination you specify with theTargetName parameter.

Test-Connection -TargetName www.google.com -Traceroute

   Target: google.comHop Hostname                  Ping Latency Status           Source       TargetAddress                                      (ms)--- --------                  ---- ------- ------           ------       -------------  1 172.20.0.1                   1       4 Success          Lira         172.217.9.174  1 172.20.0.1                   2       3 Success          Lira         172.217.9.174  1 172.20.0.1                   3       2 Success          Lira         172.217.9.174  2 12.108.153.193               1       3 Success          Lira         172.217.9.174  2 12.108.153.193               2       3 Success          Lira         172.217.9.174  2 12.108.153.193               3       2 Success          Lira         172.217.9.174  3 12.244.85.177                1      11 Success          Lira         172.217.9.174  3 12.244.85.177                2      12 Success          Lira         172.217.9.174  3 12.244.85.177                3      12 Success          Lira         172.217.9.174  4 *                            1      14 DestinationNetw… Lira         172.217.9.174  4 *                            2       * TimedOut         Lira         172.217.9.174  4 *                            3      20 DestinationNetw… Lira         172.217.9.174  5 *                            1       * TimedOut         Lira         172.217.9.174  5 *                            2      15 DestinationNetw… Lira         172.217.9.174  5 *                            3       * TimedOut         Lira         172.217.9.174  6 *                            1      18 DestinationNetw… Lira         172.217.9.174  6 *                            2       * TimedOut         Lira         172.217.9.174  6 *                            3      16 DestinationNetw… Lira         172.217.9.174  7 *                            1       * TimedOut         Lira         172.217.9.174  7 *                            2       * TimedOut         Lira         172.217.9.174  7 *                            3       * TimedOut         Lira         172.217.9.174  8 *                            1       * TimedOut         Lira         172.217.9.174  8 *                            2       * TimedOut         Lira         172.217.9.174  8 *                            3       * TimedOut         Lira         172.217.9.174  9 *                            1       * TimedOut         Lira         172.217.9.174  9 *                            2       * TimedOut         Lira         172.217.9.174  9 *                            3       * TimedOut         Lira         172.217.9.174 10 *                            1       * TimedOut         Lira         172.217.9.174 10 *                            2       * TimedOut         Lira         172.217.9.174 10 *                            3       * TimedOut         Lira         172.217.9.174 11 172.217.9.174                1      23 Success          Lira         172.217.9.174 11 172.217.9.174                2      21 Success          Lira         172.217.9.174 11 172.217.9.174                3      22 Success          Lira         172.217.9.174

TheTest-Connection command is called with theTraceroute parameter. The results, which are[Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus] objects, are output totheSuccess output stream.

When you use theDetailed parameter, this cmdlet returns a detailed information about the statusof the TCP connection attempts.

Test-Connection bing.com -TCPPort 443 -Detailed -Count 4

   Target: bing.comId Source     Address           Port Latency(ms) Connected Status-- ------     -------           ---- ----------- --------- ------ 1 circumflex 2620:1ec:c11::200  443          12 True      Success 2 circumflex 2620:1ec:c11::200  443          14 True      Success 3 circumflex 2620:1ec:c11::200  443          17 True      Success 4 circumflex 2620:1ec:c11::200  443          17 True      Success

Note

This parameter is not supported in PowerShell versions 6 and up. Supplying this parametercauses an error.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, seeabout_CommonParameters.

You can't pipe objects to this cmdlet.

By default, this cmdlet returns aTestConnectionCommand+PingStatus object for eachping reply.

When you use theTraceroute parameter, this cmdlet returns aTestConnectionCommand+TraceStatus object for each ping reply along the route.

When you use theQuiet orTcpPort parameters, this cmdlet returns aBoolean value. Ifthe cmdlet tests multiple connections, it returns an array ofBoolean values.

When you use theMtuSize parameter, this cmdlet returns aTestConnectionCommand+PingMtuStatus object for each ping reply.

When you use theDetailed parameter, this cmdlet returns aTestConnectionCommand+TcpPortStatus object that shows the status of the TCP connection.

On Linux, using theBufferSize parameter or any combination of parameters with theMtuSizeparameter set that results in a non-default buffer size of 32 bytes may requiresudo. In thosecases,Test-Command raises an exception with a message indicating thatsudo is required.