Test-Connection

将 ICMP 回显请求数据包或 ping 发送给一台或多台计算机。

语法

Test-Connection
    [-TargetName] <string[]>
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Count <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -Repeat
    [-Ping]
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Delay <int>]
    [-BufferSize <int>]
    [-DontFragment]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -Traceroute
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-MaxHops <int>]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -MtuSize
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [<CommonParameters>]
Test-Connection
    [-TargetName] <string[]>
    -TcpPort <int>
    [-IPv4]
    [-IPv6]
    [-ResolveDestination]
    [-Source <string>]
    [-Count <int>]
    [-Delay <int>]
    [-Repeat]
    [-Quiet]
    [-TimeoutSeconds <int>]
    [-Detailed]
    [<CommonParameters>]

说明

Test-Connection cmdlet 将 Internet 控制消息协议 (ICMP) 回显请求数据包或 ping 发送给一台或多台远程计算机并返回回显响应回复。 可以使用此 cmdlet 确定是否可通过 IP 网络联系特定的计算机。

使用 Test-Connection 的参数可以指定发送和接收计算机,将该命令作为后台作业运行,设置 ping 的超时值和数量以及配置连接和身份验证。

与熟悉的 ping 命令不同,Test-Connection 返回可在 PowerShell 中调查的 TestConnectionCommand+PingStatus 对象。 Quiet 参数为每个测试的连接返回 System.Boolean 对象中的布尔值。 如果测试了多个连接,则将返回一组布尔值。

示例

示例 1:向远程计算机发送回显请求

此示例将来自本地计算机的回显请求数据包发送到计算机 Server01。

Test-Connection -TargetName Server01 -IPv4

Destination: Server01

Ping Source           Address                   Latency BufferSize Status
                                                   (ms)        (B)
---- ------           -------                   ------- ---------- ------
   1 ADMIN1           10.59.137.44                   24         32 Success
   2 ADMIN1           10.59.137.44                   39         32 Success
   3 ADMIN1           *                               *          * TimedOut
   4 ADMIN1           10.59.137.44                   28         32 Success

Test-Connection 使用 TargetName 参数指定 Server01 计算机。 IPv4 参数指定测试的协议。

一系列 TestConnectionCommand+PingStatus 对象发送到输出流,每个来自目标计算机的 ping 回复一个对象。

示例 2:向多台计算机发送回显请求

此示例将来自本地计算机的 ping 请求发送到多台远程计算机。

Test-Connection -TargetName Server01, Server02, Server12

示例 3:使用参数自定义测试命令

此示例使用 Test-Connection 的参数来自定义命令。 本地计算机将 ping 测试发送到远程计算机。

Test-Connection -TargetName Server01 -Count 3 -Delay 2 -MaxHops 255 -BufferSize 256

Test-Connection 使用 TargetName 参数指定 Server01。 Count 参数指定将三个 ping 发送到 Server01 计算机,延迟 2 秒间隔。

如果因跃点数增加或网络流量较高而预计 ping 响应比往常需要更长时间,可以使用这些选项。

示例 4:以后台作业身份运行测试

此示例演示了如何将 Test-Connection 命令作为 PowerShell 后台作业运行。

$job = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path "Servers.txt") }
$Results = Receive-Job $job -Wait

Start-Job 命令使用 Test-Connection cmdlet 对企业中的多台计算机执行 ping 操作。 TargetName 参数的值是一个 Get-Content 命令,会从 Servers.txt 文件读取计算机名称列表。 该命令使用 Start-Job cmdlet 将命令作为后台作业运行,并将作业保存在 $job 变量中。

指示 Receive-Job 命令在作业完成之前 -Wait,然后获取结果并将其存储在 $Results 变量中。

示例 5:仅当连接测试成功时创建会话

仅当发送到 Server01 计算机上的至少一条 ping 成功时,此示例才会在该计算机上创建一个会话。

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

Test-Connection cmdlet 使用提供的 Quiet 参数对 Server01 计算机执行 ping 操作。 如果四个 ping 中的任何一个成功,则生成的值为 $True。 如果 pings 均未成功,则值为 $False

如果 Test-Connection 命令返回 $True 值,则该命令将使用 New-PSSession cmdlet 创建 PSSession

示例 6:使用 Traceroute 参数

Traceroute 参数是在 PowerShell 6.0 中引入的,映射本地计算机与使用 TargetName 参数指定的远程目标之间的路由。

Test-Connection -TargetName www.google.com -Traceroute

Target: google.com

Hop Hostname                  Ping Latency Status           Source       TargetAddress
                                      (ms)
--- --------                  ---- ------- ------           ------       -------------
  1 172.20.0.1                   1       4 Success          Lira         172.217.9.174
  1 172.20.0.1                   2       3 Success          Lira         172.217.9.174
  1 172.20.0.1                   3       2 Success          Lira         172.217.9.174
  2 12.108.153.193               1       3 Success          Lira         172.217.9.174
  2 12.108.153.193               2       3 Success          Lira         172.217.9.174
  2 12.108.153.193               3       2 Success          Lira         172.217.9.174
  3 12.244.85.177                1      11 Success          Lira         172.217.9.174
  3 12.244.85.177                2      12 Success          Lira         172.217.9.174
  3 12.244.85.177                3      12 Success          Lira         172.217.9.174
  4 *                            1      14 DestinationNetw… Lira         172.217.9.174
  4 *                            2       * TimedOut         Lira         172.217.9.174
  4 *                            3      20 DestinationNetw… Lira         172.217.9.174
  5 *                            1       * TimedOut         Lira         172.217.9.174
  5 *                            2      15 DestinationNetw… Lira         172.217.9.174
  5 *                            3       * TimedOut         Lira         172.217.9.174
  6 *                            1      18 DestinationNetw… Lira         172.217.9.174
  6 *                            2       * TimedOut         Lira         172.217.9.174
  6 *                            3      16 DestinationNetw… Lira         172.217.9.174
  7 *                            1       * TimedOut         Lira         172.217.9.174
  7 *                            2       * TimedOut         Lira         172.217.9.174
  7 *                            3       * TimedOut         Lira         172.217.9.174
  8 *                            1       * TimedOut         Lira         172.217.9.174
  8 *                            2       * TimedOut         Lira         172.217.9.174
  8 *                            3       * TimedOut         Lira         172.217.9.174
  9 *                            1       * TimedOut         Lira         172.217.9.174
  9 *                            2       * TimedOut         Lira         172.217.9.174
  9 *                            3       * TimedOut         Lira         172.217.9.174
 10 *                            1       * TimedOut         Lira         172.217.9.174
 10 *                            2       * TimedOut         Lira         172.217.9.174
 10 *                            3       * TimedOut         Lira         172.217.9.174
 11 172.217.9.174                1      23 Success          Lira         172.217.9.174
 11 172.217.9.174                2      21 Success          Lira         172.217.9.174
 11 172.217.9.174                3      22 Success          Lira         172.217.9.174

使用 Traceroute 参数调用 Test-Connection 命令。 结果([Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus] 对象)将输出到 Success 输出流。

示例 7:获取 TCP 连接测试的详细输出

使用 Detailed 参数时,此 cmdlet 将返回有关 TCP 连接尝试状态的详细信息。

Test-Connection bing.com -TCPPort 443 -Detailed -Count 4

Target: bing.com

Id Source     Address           Port Latency(ms) Connected Status
-- ------     -------           ---- ----------- --------- ------
 1 circumflex 2620:1ec:c11::200  443          12 True      Success
 2 circumflex 2620:1ec:c11::200  443          14 True      Success
 3 circumflex 2620:1ec:c11::200  443          17 True      Success
 4 circumflex 2620:1ec:c11::200  443          17 True      Success

参数

-BufferSize

指定使用此命令发送的缓冲区的大小,以字节为单位。 默认值为 32。

类型:Int32
别名:Size, Bytes, BS
Position:Named
默认值:32
必需:False
接受管道输入:False
接受通配符:False

-Count

指定要发送的回显请求数。 默认值为 4。

类型:Int32
Position:Named
默认值:4
必需:False
接受管道输入:False
接受通配符:False

-Delay

指定两次 ping 操作之间的间隔时间,以秒为单位。

类型:Int32
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-Detailed

使用 Detailed 参数时,此 cmdlet 将返回有关 TCP 连接尝试状态的详细信息。

此参数已在 PowerShell 7.4 中添加。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-DontFragment

此参数设置 IP 标头中的“Don't Fragment”标志。 可以将此参数与 BufferSize 参数一起使用,以测试路径 MTU 大小。 有关路径 MTU 的详细信息,请参阅维基百科中的路径 MTU 发现一文。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-IPv4

强制 cmdlet 对测试使用 IPv4 协议。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-IPv6

强制 cmdlet 对测试使用 IPv6 协议。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-MaxHops

设置 ICMP 请求消息可以发送的最大跃点数。 默认值由操作系统控制。 Windows 10 及更高版本的默认值为 128 个跃点。

类型:Int32
别名:Ttl, TimeToLive, Hops
Position:Named
默认值:128
必需:False
接受管道输入:False
接受通配符:False

-MtuSize

此参数用于发现路径 MTU 大小。 该 cmdlet 返回 PingReply#MTUSize 对象,该对象包含目标的路径 MTU 大小。 有关路径 MTU 的详细信息,请参阅维基百科中的路径 MTU 发现一文。

类型:SwitchParameter
别名:MtuSizeDetect
Position:Named
默认值:False
必需:True
接受管道输入:False
接受通配符:False

-Ping

使 cmdlet 执行 ping 测试。 这是 Test-Connection cmdlet 的默认模式。

类型:SwitchParameter
Position:Named
默认值:True
必需:False
接受管道输入:False
接受通配符:False

-Quiet

Quiet 参数返回布尔值。 使用此参数可禁止显示所有错误。

测试的每个连接都会返回一个布尔值。 如果 TargetName 参数指定多台计算机,则返回一组布尔值。

如果给定目标的任何 ping 成功,则返回 $True

如果给定目标的所有 ping 失败,则返回 $False

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-Repeat

使 cmdlet 持续发送 ping 请求。 当 TargetName 的值是目标数组时,该 cmdlet 仅对第一个目标重复 ping 请求。 它忽略剩余的目标。 此参数不能与 Count 参数一起使用。

类型:SwitchParameter
别名:Continuous
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-ResolveDestination

使 cmdlet 尝试解析目标的 DNS 名称。 与 Traceroute 参数结合使用时,还将检索所有中间主机的 DNS 名称(如果可能)。

类型:SwitchParameter
Position:Named
默认值:False
必需:False
接受管道输入:False
接受通配符:False

-Source

指定发出 ping 请求的计算机的名称。 请输入以逗号分隔的计算机名称的列表。 默认为本地计算机。

注意

PowerShell 版本 6 及更高版本不支持此参数。 提供此参数会导致错误。

类型:String
Position:Named
默认值:Local computer
必需:False
接受管道输入:False
接受通配符:False

-TargetName

指定要测试的计算机。 请键入计算机名称或者以 IPv4 或 IPv6 格式键入 IP 地址。

类型:String[]
别名:ComputerName
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-TcpPort

指定要在 TCP 连接测试中使用的目标上的 TCP 端口号。

该 cmdlet 将尝试与目标上的指定端口建立 TCP 连接。

  • 如果已建立连接,则该 cmdlet 将返回 $True
  • 如果未建立连接,则该 cmdlet 将返回 $False
类型:Int32
Position:Named
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-TimeoutSeconds

设置测试的超时值。 如果在超时到期前未收到响应,测试将失败。 默认值为 5 秒。

此参数是在 PowerShell 6.0 中引入的。

类型:Int32
Position:Named
默认值:5 seconds
必需:False
接受管道输入:False
接受通配符:False

-Traceroute

使 cmdlet 执行 traceroute 测试。 使用此参数时,cmdlet 将返回 TestConnectionCommand+TraceStatus 对象。

类型:SwitchParameter
Position:Named
默认值:False
必需:True
接受管道输入:False
接受通配符:False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

Microsoft.PowerShell.Commands.TestConnectionCommand+PingStatus

默认情况下,此 cmdlet 为每个 ping 回复返回 TestConnectionCommand+PingStatus 对象。

Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus

使用 Traceroute 参数时,此 cmdlet 将返回沿路由的每个 ping 答复的 TestConnectionCommand+TraceStatus 对象。

Boolean

使用 QuietTcpPort 参数时,此 cmdlet 将返回布尔值。 如果 cmdlet 测试多个连接,它将返回一组布尔值。

Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus

使用 MtuSize 参数时,此 cmdlet 会为每个 ping 回复返回 TestConnectionCommand+PingMtuStatus 对象。

Microsoft.PowerShell.Commands.TestConnectionCommand+TcpPortStatus

使用 Detailed 参数时,此 cmdlet 将返回显示 TCP 连接状态的 TestConnectionCommand+TcpPortStatus 对象。

备注

在 Linux 上,如果使用的 BufferSize 参数或任何参数与 MtuSizeDetect 参数集的组合导致缓冲区大小不是默认的 32 字节,则可能需要 sudo 在这些情况下,Test-Command 会引发异常,并显示一条消息,指示需要 sudo