Test-Connection
Sends ICMP echo request packets, or pings, to one or more computers.
Syntaxe
Default (Výchozí)
Test-Connection
[-ComputerName] <String[]>
[-AsJob]
[-Authentication <AuthenticationLevel>]
[-BufferSize <Int32>]
[-Count <Int32>]
[-Impersonation <ImpersonationLevel>]
[-ThrottleLimit <Int32>]
[-TimeToLive <Int32>]
[-Delay <Int32>]
[<CommonParameters>]
Source
Test-Connection
[-ComputerName] <String[]>
[-Source] <String[]>
[-AsJob]
[-Authentication <AuthenticationLevel>]
[-BufferSize <Int32>]
[-Count <Int32>]
[-Credential <PSCredential>]
[-Impersonation <ImpersonationLevel>]
[-ThrottleLimit <Int32>]
[-TimeToLive <Int32>]
[-Delay <Int32>]
[<CommonParameters>]
Quiet
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.
Příklady
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.
Parametry
-AsJob
Indicates that this cmdlet runs as a background job.
To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of the Windows operating system, you must open PowerShell by using the Run as administrator option. For more information, see about_Remote_Requirements.
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. The job is
created on the local computer and the results from remote computers are automatically returned to
the local computer. To get the job results, use the Receive-Job cmdlet.
For more information about PowerShell background jobs, see about_Jobs and about_Remote_Jobs.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | False |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
Default
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
Source
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Authentication
Specifies the authentication level that is used for the WMI connection. Test-Connection uses WMI.
The valid values are as follows:
- Unchanged: The authentication level is the same as the previous command.
- 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.
The default value is Packet that has an enumerated value of 4. For more information about the values of this parameter, see AuthenticationLevel enumeration.
Vlastnosti parametru
| Typ: | AuthenticationLevel |
| Default value: | Packet (enumerated value of 4) |
| Přípustné hodnoty: | Default, None, Connect, Call, Packet, PacketIntegrity, PacketPrivacy, Unchanged |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-BufferSize
Specifies the size, in bytes, of the buffer sent with this command. The default value is 32.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 32 |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
| Aliasy: | Size, Bytes, BS |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-ComputerName
Specifies 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.
Vlastnosti parametru
| Typ: | String[] |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
| Aliasy: | CN, IPAddress, __SERVER, Server, Destination |
Sady parametrů
(All)
| Position: | 0 |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | True |
| Hodnota ze zbývajících argumentů: | False |
-Count
Specifies the number of echo requests to send. The default value is 4.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 4 |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Credential
Specifies 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.
Vlastnosti parametru
| Typ: | PSCredential |
| Default value: | Current user |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
Source
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Delay
Specifies the interval between pings, in seconds.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 1 (second) |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Impersonation
Specifies 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.
Vlastnosti parametru
| Typ: | ImpersonationLevel |
| Default value: | Impersonate |
| Přípustné hodnoty: | Default, Anonymous, Identify, Impersonate, Delegate |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Quiet
The 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.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | False |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
Quiet
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Source
Specifies the names of the computers where the ping originates. Enter a comma-separated list of computer names. The default is the local computer.
Vlastnosti parametru
| Typ: | String[] |
| Default value: | Local computer |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
| Aliasy: | FCN, SRC |
Sady parametrů
Source
| Position: | 1 |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-ThrottleLimit
Specifies 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.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 32 |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
Default
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
Source
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-TimeToLive
Specifies 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.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | 128 in Windows |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
| Aliasy: | TTL |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Vstupy
None
You can't pipe input to this cmdlet.
Výstupy
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.
Poznámky
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.