CmdID

CmdID / PowerShell / Cmdlets / Test

Test-Connection

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

From the PowerShell reference 14 parameters

Opens CmdID with your command, read as PowerShell. It is read in your browser and sent nowhere.

What it does

from the PowerShell reference, CC BY 4.0

Sends ICMP echo request packets, or pings, to one or more computers. 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.

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

Send echo requests to a remote computer

Test-Connection -ComputerName Server01Identify

Send echo requests to several computers

Test-Connection -ComputerName Server01, Server02, Server12Identify

Send echo requests from several computers to a computer

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

Use parameters to customize the test command

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

Run a test as a background job

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

Ping a remote computer with credentials

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

Create a session only if a connection test succeeds

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

Its page in the reference: Test-Connection.

Parameters

14 in the PowerShell reference
-AsJobIndicates that this cmdlet runs as a background job. When you specify the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job finishes. To get the job results, use the Receive-Job cmdlet. For more information about PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
-BufferSizeSpecifies the size, in bytes, of the buffer sent with this command. The default value is 32.
-ComputerNameSpecifies the computers to ping. Type the computer names or type IP addresses in IPv4 or IPv6 format. Wildcard characters are not permitted. This parameter is required. This parameter doesn't rely on PowerShell remoting. You can use the ComputerName parameter even if your computer isn't configured to run remote commands. NOTE: The ComputerName parameter is renamed to TargetName in PowerShell 6.0 and above.
-CountSpecifies the number of echo requests to send. The default value is 4.
-CredentialSpecifies a user account that has permission to send a ping request from the source computer. Type a user name, such as User01 or Domain01\User01, or enter a PSCredential object, such as one from the Get-Credential cmdlet. The Credential parameter is valid only when the Source parameter is used in the command. The credentials don't affect the destination computer.
-DcomAuthenticationSpecifies the authentication level that this cmdlet uses with WMI. Test-Connection uses WMI. The acceptable values for this parameter are: - Default. Windows Authentication - None. No COM authentication - Connect. Connect-level COM authentication - Call. Call-level COM authentication - Packet. Packet-level COM authentication - PacketIntegrity. Packet Integrity-level COM authentication - PacketPrivacy. Packet Privacy-level COM authentication - Unchanged. Same as the previous command The default value is Packet that has an enumerated value of 4. For more information about the values of this parameter, see AuthenticationLevel enumeration.
-DelaySpecifies the interval between pings, in seconds.
-ImpersonationSpecifies the impersonation level to use when this cmdlet calls WMI. Test-Connection uses WMI. The acceptable values for this parameter are as follows: - Default. Default impersonation. - Anonymous. Hides the identity of the caller. - Identify. Allows objects to query the credentials of the caller. - Impersonate. Allows objects to use the credentials of the caller. The default value is Impersonate.
-ProtocolSpecifies a protocol. The acceptable values for this parameter are DCOM and WSMan.
-QuietThe Quiet parameter returns a Boolean value in a System.Boolean object. Using this parameter suppresses all errors. Each connection that's tested returns a Boolean value. If the ComputerName parameter specifies multiple computers, an array of Boolean values is returned. If any ping succeeds, $true is returned. If all pings fail, $false is returned.
-SourceSpecifies the names of the computers where the ping originates. Enter a comma-separated list of computer names. The default is the local computer.
-ThrottleLimitSpecifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer.
-TimeToLiveSpecifies the maximum times a packet can be forwarded. For every hop in gateways, routers etc. the TimeToLive value is decreased by one. At zero the packet is discarded and an error is returned. In Windows, The default value is 128. The alias of the TimeToLive parameter is TTL.
-WsmanAuthenticationSpecifies the mechanism that is used to authenticate the user credentials when this cmdlet uses the WSMan protocol. The acceptable values for this parameter are: - Basic - CredSSP - Default - Digest - Kerberos - Negotiate. The default value is Default. For more information about the values of this parameter, see AuthenticationMechanism Enumeration. Caution: Credential Security Service Provider (CredSSP) authentication, in which the user credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. This parameter was introduced in Windows PowerShell 3.0.

See also

Add-Computer · Restart-Computer · Stop-Computer