Test Connection - PowerShell

Overview

Test-Connection is a PowerShell command used to check network connectivity and determine whether a remote host or resource is reachable. It sends a series of ICMP echo requests to the target and displays the results, providing insights into network connectivity and latency.

Syntax

Test-Connection [-ComputerName] <string> [-Port] <int>
 [-SourceAddress] <string> [-Count] <int> [-Delay] <int>
 [-BufferSize] <int> [-Timeout] <int> [-UseTcp]
 [-UseUdp] [-UseIpv4] [-UseIpv6] [-DisableEndpoint]
 [-DisableGateway] [-DisableRedirect] [-DisableDns] [-DisableAlive]
 [-SkipAuthentication] [-ShowCommand] [-PassThru]
 [-AcceptAnyConnection] [-UseTimeoutForEstimates]
 [-LimitAttemptsTo] <int> [-Direction] <{ Incoming | Outgoing }>
 [-SkipDnsResolution] [-TraceSession] <ulong> [-IPv6Fallback]
 [-UnknownHostAction] <{ Ignore | Error | IgnoreErrors }>
 [-LocalPort] <int> [-DontResolveNames] [-Strict] [-NoDisconnect]
 [-ThrottleLimit] <int> [-ProfileID] <string>
 [-MaximumErrors] <int>

Options/Flags

| Option | Description | Default |
|—|—|—|
| -ComputerName | Specifies the target host or IP address to check connectivity. | |
| -Port | Specifies the port number to test on the target host. | 80 |
| -SourceAddress | Specifies the source IP address to use for the test. | |
| -Count | Sets the number of ICMP echo requests to send. | 4 |
| -Delay | Sets the time delay between each ICMP echo request. | 1000 (1 second) |
| -BufferSize | Sets the size of the ICMP echo request payload. | 32 |
| -Timeout | Specifies the timeout period for each ICMP echo request. | 10000 (10 seconds) |
| -UseTcp | Uses TCP protocol instead of ICMP for the test. | |
| -UseUdp | Uses UDP protocol instead of ICMP for the test. | |
| -UseIpv4 | Forces the use of IPv4 protocol. | |
| -UseIpv6 | Forces the use of IPv6 protocol. | |
| -DisableEndpoint | Disables endpoint detection. | |
| -DisableGateway | Disables gateway detection. | |
| -DisableRedirect | Disables redirect detection. | |
| -DisableDns | Disables DNS resolution. | |
| -DisableAlive | Disables the “is alive” message. | |
| -SkipAuthentication | Skips authentication for the test. | |
| -ShowCommand | Displays the command used to perform the test. | |
| -PassThru | Returns the TcpTest or UdpTest result objects. | |
| -AcceptAnyConnection | Accepts any connection from the target host. | |
| -UseTimeoutForEstimates | Uses the timeout value for TCP connection estimates. | |
| -LimitAttemptsTo | Limits the number of attempts to connect to the target host. | |
| -Direction | Specifies the direction of the test (incoming or outgoing). | Outgoing |
| -SkipDnsResolution | Skips DNS resolution for the target host. | |
| -TraceSession | Specifies a trace session ID for monitoring the test. | |
| -IPv6Fallback | Falls back to IPv4 if IPv6 fails. | |
| -UnknownHostAction | Specifies the action to take if the target host is unknown. | Ignore |
| -LocalPort | Specifies the local port number to use for the test. | |
| -DontResolveNames | Prevents DNS resolution of IP addresses. | |
| -Strict | Enforces strict test conditions. | |
| -NoDisconnect | Prevents the command from disconnecting from the target host. | |
| -ThrottleLimit | Sets the maximum number of concurrent connections for the test. | |
| -ProfileID | Specifies the PowerShell profile to use for the test. | |
| -MaximumErrors | Sets the maximum number of errors allowed before the test fails. | |

Examples

Simple ICMP Connectivity Test:

Test-Connection google.com

TCP Port Connectivity Test:

Test-Connection -ComputerName www.microsoft.com -Port 443 -UseTcp

UDP Port Connectivity Test:

Test-Connection -ComputerName 8.8.8.8 -Port 53 -UseUdp

With Custom Number of Requests and Timeout:

Test-Connection -ComputerName myhost.com -Count 10 -Timeout 20000

Common Issues

• Host not found: Ensure that the target host or IP address is correct and reachable.
• Connection failed: Check network connectivity, firewall settings, and port availability on the target host.
• Timeout errors: Increase the timeout value or check for network congestion or latency issues.
• Authentication failures: Provide valid credentials if the target host requires authentication.

Integration

Test-Connection can be used in conjunction with other PowerShell commands to automate network connectivity checks and troubleshoot network issues. For example:

• Check multiple hosts:

$hosts = @(
    "google.com",
    "microsoft.com",
    "amazon.com"
)
foreach ($host in $hosts) {
    Test-Connection -ComputerName $host
}

• Parse results and notify:

$result = Test-Connection -ComputerName myhost.com
if ($result.TcpTestSucceeded) {
    Write-Host "Connection successful!"
} else {
    Send-MailMessage -Subject "Network Issue" -Body "Connection to myhost.com failed."
}

Related Commands

• Connect-RemoteDesktop
• Enter-PSSession
• Get-TcpConnection
• Get-UdpConnection
• Invoke-Command