Updated March 8, 2023
Introduction to PowerShell test-connection
Test-Connection cmdlet in a PowerShell sends Internet Control Message Protocol (ICMP) echo request packets to the remote computers and, in return, receives the echo-response to check if the remote computers are alive or in the network or can be connected. Unlike the familiar ping command, this command Tests the connections, sets the buffersize, number of hope, throttle limits, the delay between each request, and includes the ping status.
Syntax
Below is the syntax:
Pair 1:
Test-Connection
[-TargetName] <string[]>
[-Ping]
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-Count <int>]
[-Delay <int>]
[-BufferSize <int>]
[-DontFragment]
[-TimeoutSeconds <int>]
[-Quiet]
[<CommonParameters>]
Pair2:
Test-Connection
[-TargetName] <string[]>
-Repeat
[-Ping]
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-Delay <int>]
[-BufferSize <int>]
[-DontFragment]
[-TimeoutSeconds <int>]
[-Quiet]
[<CommonParameters>]
Pair3:
Test-Connection
[-TargetName] <string[]>
-MtuSize
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-TimeoutSeconds <int>]
[-Quiet]
[<CommonParameters>]
Pair4:
Test-Connection
[-TargetName] <string[]>
-Traceroute
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-TimeoutSeconds <int>]
[-Quiet]
[<CommonParameters>]
Pair5:
Test-Connection
[-TargetName] <string[]>
-TcpPort <int>
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-TimeoutSeconds <int>]
[-Quiet]
[<CommonParameters>]
Please note: We need to use a single pair at a time as a syntax. We can’t use the combination of pairs. For example, We can’t use Mtusize and TraceRoute parameters together.
How does the Test-Connection command work in PowerShell?
This command’s sole purpose is to check if the remote computers are online or not by sending them ICMP requests to the remote hosts. Remote computer response depends on offline, their firewall rules, network security rules, etc.
Many times remote computers are online, but they cannot respond due to the above-mentioned reasons. This command is far better than the ping command as we can play with the different parameters like we can specify the number of count in response, can send requests for the multiple servers, set the buffer size and MTU limit, etc.
Examples
Different examples are mentioned below:
Example #1 – Test-Connection for a remote computer.
This example simply explains remote connectivity.
Test-Connection -ComputerName LabMachine2k12
Output:
In the above example, Source mentions the originated machine, the destination is the remote computer, IP address is the remote computer IP.
For PowerShell core version (version 6.0+) ComputerName parameter is renamed to TargentName.
Example #2 – Test-Connection for multiple remote computers.
To check the connectivity of the multiple remote computers, we can provide the multiple computer names for the -ComputerName parameter because this parameter accepts the string array.
help Test-Connection -Parameter ComputerName
Output:
You can check the ComputerName parameter is a String array parameter.
Example #3 – Test-Connection with -Count parameter.
We can specify the number of counts we need to receive as a response from the remote computer using the -Count Parameter. The default number of responses we receive from remote computers is 4.
Test-Connection -ComputerName LabMachine2k12 -Count 2
Output:
This parameter is generally used when we test connections for multiple computers. If we keep the default parameter, it counts for 4, and checking remote connectivity for multiple servers will take more than the expected time.
Example #4 – Test-Connection with -Quiet parameter.
The -Quiet parameter returns the output in Boolean (True or False). If the server is reachable, the output is true; otherwise, the output is false.
For example,
Test-Connection -ComputerName LabMachine2k12 -Quiet
Output:
If the remote system isn’t reachable,
Most of the time, programmers use both -Count and -Quiet parameters together to check multiple server’s connectivities. For example, we have a Servers.txt file containing the list of servers, and to check if the server is reachable or not we will use the below code.
foreach($server in (Get-Content C:\temp\Servers.txt)){
if(Test-Connection -ComputerName $server -Count 2 -Quiet){Write-Output "$server is Online"}
else{Write-Output "Server is offline"}
}
Example #5 – Establishing a session if connection successful
From the above examples reference, you can also establish a session with the remote server only when the connection is successful. For example,
if(Test-Connection -ComputerName 'LabMachine2k12' -Count 2 -Quiet){
New-PSSession -ComputerName 'LabMachine2k12'
}
Output:
Example #6 – Using -Delay Parameter
We can use the delay parameter and provide values in seconds. This parameter specifies the delay in seconds between each request.
In the below example, there will be 2 requests sent to the remote servers with an interval of 5 seconds.
Test-Connection -ComputerName LabMachine2k12 -Delay 5 -count 2
The default delay is 1 second, and however, the delay parameter is not recommended unless using for any investigation or troubleshooting purpose because it delays the PowerShell operation.
Example #7 – Test-Connection with BufferSize.
BufferSize parameter specifies the size in bytes of the buffer sent with the Test-Connection command. The default value is 32 if not specified. This is an integer parameter.
Test-Connection -ComputerName LabMachine2k12 -BufferSize 64
Output:
If the buffer size is not specified, the output will produce 32 (Default value) in the Bytes field. We can use this parameter for the high traffic network condition.
Example #8 – Using ThrottleLimit parameter.
ThrottleLimit is the integer parameter and specifies the number of concurrent connections to establish. Its default value is 32, but we can change this value for more concurrent connections.
Test-Connection -ComputerName LabMachine2k12 -ThrottleLimit 50
We can use both buffersize and throttlelimit parameters together.
Test-Connection -ComputerName LabMachine2k12 -BufferSize 64 -ThrottleLimit 50
Example #9 – Test-Connection with different credentials.
If the remote server(s) are not in the same domain, we can connect use remote server credentials to test the connection. For example,
$creds = Get-Credential
Test-Connection -ComputerName LabMachine2k12 -Credential $creds -Count 2
Example #10 – Test-Connection with TTL parameter.
TimeToLive (Alias: TTL) specifies the maximum number of times the packets can be forwarded. For every hope in the gateway, routers, etc. Each time the TTL value is decreased by one, and when it becomes 0, the error is returned. Its default value is 128.
You can change the TTL value using the parameter as shown below.
Test-Connection -ComputerName LabMachine2k12 -TimeToLive 200
If there are more hopes, you can increase the TTL value.
Conclusion
Test-Connection is the first step and very crucial step in the PowerShell script as it saves a lot of time running the remote commands because they can be executed only when this command returns True value. In some organizations, the Firewall blocks the ICMP port for security reasons, and in that case, we can also determine by using WINRM connectivity using the Test-WSMan command if the remote computer is reachable or not.
Recommended Articles
This is a guide to PowerShell test-connection. Here we discuss How does the Test-Connection command work in PowerShell, along with the examples. You may also have a look at the following articles to learn more –
