This is the built-in help made by Microsoft for the command 'Test-Connection', in PowerShell version 2 - as retrieved from
Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Sends ICMP echo request packets ("pings") to one or more computers.
Test-Connection [-ComputerName] <string[]> [[-Source] <string[]>] [-AsJob] [-Authentication {Default | None | Connect | Call | Packet | PacketInt
egrity | PacketPrivacy | Unchanged}] [-BufferSize <int>] [-Count <int>] [-Credential <PSCredential>] [-Delay <int>] [-Impersonation {Default | An
onymous | Identify | Impersonate | Delegate}] [-Quiet] [-ThrottleLimit <int>] [-TimeToLive <int>] [<CommonParameters>]
The Test-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets ("pings") to one or more remote computers and retu
rns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an Internet Protocol (I
P) 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 timeout and number of pings, and to configure the connection and authentication.
Unlike the traditional "ping" command, Test-Connection returns a Win32_PingStatus object that you can investigate in Windows PowerShell, but you
can use the Quiet parameter to force it to return only a Boolean value.
<
Online version: http://go.microsoft.com/fwlink/?LinkID=135266
Add-Computer
Restart-Computer
Stop-Computer
<
-------------------------- EXAMPLE 1 --------------------------
C:\PS>test-connection server01
Source Destination IPV4Address IPV6Address Bytes Time(ms)
------ ----------- ----------- ----------- ----- --------
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 1
Description
-----------
This command sends echo request packets ("pings") from the local computer to the Server01 computer. This command uses the ComputerName parameter
to specify the Server01 computer, but omits the optional parameter name.
-------------------------- EXAMPLE 2 --------------------------
C:\PS>test-connection -computername server01, server02, server12 -credential domain01\user01
Description
-----------
This command sends pings from the local computer to several remote computers. It uses the Credential parameter to specify a user account that has
permission to ping all of the remote computers.
-------------------------- EXAMPLE 3 --------------------------
C:\PS>test-connection -source Server02, Server 12, localhost -computername Server01
Description
-----------
This command sends pings from different source computers to a single remote computer, Server01. Use this command format to test the latency of co
nnections from multiple points.
-------------------------- EXAMPLE 4 --------------------------
C:\PS>test-connection -computername Server01 -count 3 -delay 2 -TTL 256 -buffersize 256 -throttle 32
Description
-----------
This command sends three pings from the local computer to the Server01 computer. It uses the parameters of Test-Connection to customize the comma
nd.
Use this command format when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traf
fic network condition.
-------------------------- EXAMPLE 5 --------------------------
C:\PS>$job = test-connection -computername (get-content servers.txt) -asjob
C:\PS> if ($job.jobstateinfo.state -ne "Running") {$results = receive-job $job}
Description
-----------
This example shows how to run a Test-Connection command as a Windows PowerShell background job.
The first command uses the Test-Connection cmdlet to ping many computers in an enterprise. The value of ComputerName parameter is a Get-Content c
ommand 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
.
The second command checks to see that the job is not still running, and if it is not, it uses a Receive-Job command to get the results and store
them in the $results variable.
-------------------------- EXAMPLE 6 --------------------------
C:\PS>test-connection Server55 -credential domain55\user01 -impersonation Identify
Description
-----------
This command uses the Test-Connection cmdlet to ping a remote computer. The command uses the Credential parameter to specify a user account with
permission to ping the remote computer and the Impersonation parameter to change the impersonation level to "Identify".
-------------------------- EXAMPLE 7 --------------------------
C:\PS>if (test-connection -computername Server01 -quiet) {new-pssession Server01}
Description
-----------
This command creates a PSSession on the Server01 only if at least one of the pings sent to the computer succeeds.
The command uses the Test-Connection cmdlet to ping the Server01 computer. The command uses the Quiet parameter, which returns a Boolean value, i
nstead 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.