Test-Connection

Syntax

Test-Connection
    [-ComputerName] <String[]>
    [-AsJob]
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Impersonation <ImpersonationLevel>]
    [-ThrottleLimit <Int32>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [<CommonParameters>]

Test-Connection
    [-ComputerName] <String[]>
    [-Source] <String[]>
    [-AsJob]
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Credential <PSCredential>]
    [-Impersonation <ImpersonationLevel>]
    [-ThrottleLimit <Int32>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [<CommonParameters>]

Test-Connection
    [-ComputerName] <String[]>
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Impersonation <ImpersonationLevel>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [-Quiet]
    [<CommonParameters>]

Description

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

You can use the parameters of Test-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 the connection and authentication.

Unlike the familiar ping command, Test-Connection returns a Win32_PingStatus object that you can investigate in PowerShell. The Quiet parameter returns a Boolean value in a System.Boolean object for each tested connection. If multiple connections are tested, an array of Boolean values is returned.

Examples

Example 1: Send echo requests to a remote computer

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

Test-Connection -ComputerName Server01

Source        Destination     IPV4Address     IPV6Address  Bytes    Time(ms)
------        -----------     -----------     -----------  -----    --------
ADMIN1        Server01         10.59.137.44                32       0
ADMIN1        Server01         10.59.137.44                32       0
ADMIN1        Server01         10.59.137.44                32       0
ADMIN1        Server01         10.59.137.44                32       1

Test-Connection uses the ComputerName parameter to specify the Server01 computer.

Example 2: Send echo requests to several computers

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

Test-Connection -ComputerName Server01, Server02, Server12

Example 3: Send echo requests from several computers to a computer

This example sends pings from different source computers to a single remote computer, Server01.

Test-Connection -Source Server02, Server12, localhost -ComputerName Server01 -Credential Domain01\Admin01

Test-Connection uses the Credential parameter to specify the credentials of a user who has permission to send a ping request from the source computers. Use this command format to test the latency of connections from multiple points.

Example 4: Use parameters to customize the test command

This example uses the parameters of Test-Connection to customize the command. The local computer sends a ping test to a remote computer.

Test-Connection -ComputerName Server01 -Count 3 -Delay 2 -TTL 255 -BufferSize 256 -ThrottleLimit 32

Test-Connection uses the TargetName parameter to specify Server01. The Count parameter specifies three pings are sent to the Server01 computer with a Delay of 2-second intervals.

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

Example 5: Run a test as a background job

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

$job = Test-Connection -ComputerName (Get-Content Servers.txt) -AsJob
if ($job.JobStateInfo.State -ne "Running") {$Results = Receive-Job $job}

The Test-Connection command pings many computers in an enterprise. The value of the ComputerName parameter is a Get-Content command that reads a list of computer names from the Servers.txt file. The command uses the AsJob parameter to run the command as a background job and it saves the job in the $job variable.

The if command checks to see that the job isn't still running. If the job isn't running, Receive-Job gets the results and stores them in the $Results variable.

Example 6: Ping a remote computer with credentials

This command uses the Test-Connection cmdlet to ping a remote computer.

Test-Connection Server55 -Credential Domain55\User01 -Impersonation Identify

The command uses the Credential parameter to specify a user account that has permission to ping the remote computer and the Impersonation parameter to change the impersonation level to Identify.

Example 7: Create a session only if a connection test succeeds

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

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

The if command uses the Test-Connection cmdlet to ping the Server01 computer. The command uses the Quiet parameter, which returns a Boolean value, instead of a Win32_PingStatus object. The value is $True if any of the four pings succeed and is, otherwise, $False.

If the Test-Connection command returns a value of $True, the command uses the New-PSSession cmdlet to create the PSSession.

Parameters

-AsJob

-Authentication

-BufferSize

-ComputerName

-Count

-Credential

-Delay

-Impersonation

-Quiet

-Source

-ThrottleLimit

-TimeToLive

Inputs

None

You can't pipe input to this cmdlet.

Outputs

ManagementObject

This cmdlet returns a job object, if you specify the AsJob parameter.

If you specify the Quiet parameter, it returns a Boolean value. If multiple connections are tested, an array of Boolean values is returned. Otherwise, Test-Connection returns a Win32_PingStatus object for each ping.

Notes

This cmdlet uses the Win32_PingStatus class. A Get-WMIObject Win32_PingStatus command is equivalent to a Test-Connection command.

The Source parameter set was introduced in PowerShell 3.0.

Related Links

• Add-Computer
• Restart-Computer
• Stop-Computer