Test-Connection

  • Referencia
Módulo:
Microsoft.PowerShell.Management

Envía paquetes de solicitud de eco ICMP, o pings, a uno o varios equipos.

Syntax

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

Description

El Test-Connection cmdlet envía paquetes de solicitud de eco del Protocolo de mensajes de control de Internet (ICMP) o pings a uno o varios equipos remotos y devuelve las respuestas de respuesta de eco. Puede usar este cmdlet para determinar si se puede establecer contacto con un equipo determinado a través de una red IP.

Puede usar los parámetros de Test-Connection para especificar los equipos de envío y recepción, para ejecutar el comando como trabajo en segundo plano, para establecer un tiempo de espera y un número de pings, y para configurar la conexión y la autenticación.

A diferencia del comando ping conocido, Test-Connection devuelve un objeto TestConnectionCommand+PingStatus que puede investigar en PowerShell. El parámetro Quiet devuelve un valor booleano en un objeto System.Boolean para cada conexión probada. Si se prueban varias conexiones, se devuelve una matriz de valores booleanos .

Ejemplos

Ejemplo 1: Envío de solicitudes de eco a un equipo remoto

En este ejemplo se envían paquetes de solicitud de eco desde el equipo local al equipo 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 usa el parámetro TargetName para especificar el equipo Server01. El parámetro IPv4 especifica el protocolo para la prueba.

Una serie de objetos TestConnectionCommand+PingStatus se envían al flujo de salida, un objeto por respuesta ping de la máquina de destino.

Ejemplo 2: Envío de solicitudes de eco a varios equipos

En este ejemplo se envían pings desde el equipo local a varios equipos remotos.

Test-Connection -TargetName Server01, Server02, Server12

Ejemplo 3: Uso de parámetros para personalizar el comando de prueba

En este ejemplo se usan los parámetros de Test-Connection para personalizar el comando. El equipo local envía una prueba de ping a un equipo remoto.

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

Test-Connection usa el parámetro TargetName para especificar Server01. El parámetro Count especifica que se envían tres pings al equipo Server01 con un retraso de intervalos de 2 segundos.

Puede usar estas opciones cuando se espera que la respuesta de ping tarde más de lo habitual, ya sea debido a un número extendido de saltos o a una condición de red de tráfico elevado.

Ejemplo 4: Ejecución de una prueba como trabajo en segundo plano

En este ejemplo se muestra cómo ejecutar un Test-Connection comando como un trabajo en segundo plano de PowerShell.

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

El Start-Job comando usa el Test-Connection cmdlet para hacer ping a muchos equipos de una empresa. El valor del parámetro TargetName es un Get-Content comando que lee una lista de nombres de equipo del Servers.txt archivo. El comando usa el Start-Job cmdlet para ejecutar el comando como un trabajo en segundo plano y guarda el trabajo en la $job variable .

El Receive-Job comando se indica a -Wait hasta que se completa el trabajo y, a continuación, obtiene los resultados y los almacena en la $Results variable .

Ejemplo 5: Crear una sesión solo si una prueba de conexión se realiza correctamente

En este ejemplo se crea una sesión en el equipo Server01 solo si al menos uno de los pings enviados al equipo se realiza correctamente.

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

El Test-Connection cmdlet hace ping al Server01 equipo, con el parámetro Quiet proporcionado. El valor resultante es si cualquiera de los cuatro pings se $True realiza correctamente. Si ninguno de los pings se realiza correctamente, el valor es $False.

Si el Test-Connection comando devuelve un valor de $True, el comando usa el New-PSSession cmdlet para crear la PSSession.

Ejemplo 6: Uso del parámetro Traceroute

Introducido en PowerShell 6.0, el parámetro Traceroute asigna una ruta entre el equipo local y el destino remoto que especifique con el parámetro 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

Se Test-Connection llama al comando con el parámetro Traceroute . Los resultados, que son [Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus] objetos, se generan en el flujo de salida Correcto .

Parámetros

-BufferSize

Especifica el tamaño en bytes del búfer enviado con este comando. El valor predeterminado es 32.

Type:Int32
Aliases:Size, Bytes, BS
Position:Named
Default value:32
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Count

Especifica el número de solicitudes de eco que se enviarán. El valor predeterminado es 4.

Type:Int32
Position:Named
Default value:4
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Delay

Especifica el intervalo entre pings en segundos.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DontFragment

Este parámetro establece la marca No fragmentar en el encabezado IP. Puede usar este parámetro con el parámetro BufferSize para probar el tamaño de MTU de ruta de acceso. Para obtener más información sobre la MTU de ruta de acceso, consulte el artículo Path MTU Discovery (Detección de MTU de ruta de acceso) en wikipedia.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPv4

Obliga al cmdlet a usar el protocolo IPv4 para la prueba.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPv6

Obliga al cmdlet a usar el protocolo IPv6 para la prueba.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxHops

Establece el número máximo de saltos que se puede enviar un mensaje de solicitud ICMP. El sistema operativo controla el valor predeterminado. El valor predeterminado de Windows 10 y superior es de 128 saltos.

Type:Int32
Aliases:Ttl, TimeToLive, Hops
Position:Named
Default value:128
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MtuSize

Este parámetro se usa para detectar el tamaño de MTU de ruta de acceso. El cmdlet devuelve un objeto PingReply#MTUSize que contiene el tamaño de MTU de ruta de acceso al destino. Para obtener más información sobre la MTU de ruta de acceso, consulte el artículo Path MTU Discovery (Detección de MTU de ruta de acceso) en wikipedia.

Type:SwitchParameter
Aliases:MtuSizeDetect
Position:Named
Default value:False
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Ping

Hace que el cmdlet realice una prueba de ping. Este es el modo predeterminado para el Test-Connection cmdlet .

Type:SwitchParameter
Position:Named
Default value:True
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Quiet

El parámetro Quiet devuelve un valor booleano . El uso de este parámetro suprime todos los errores.

Cada conexión que se prueba devuelve un valor booleano . Si el parámetro TargetName especifica varios equipos, se devuelve una matriz de valores booleanos .

Si algún ping a un destino determinado se realiza correctamente, $True se devuelve .

Si se produce un error en todos los pings a un destino determinado, $False se devuelve .

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Repeat

Hace que el cmdlet envíe solicitudes de ping continuamente. Este parámetro no se puede usar con el parámetro Count .

Type:SwitchParameter
Aliases:Continuous
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ResolveDestination

Hace que el cmdlet intente resolver el nombre DNS del destino. Cuando se usa junto con el parámetro Traceroute , los nombres DNS de todos los hosts intermedios también se recuperarán, si es posible.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Source

Especifica los nombres de los equipos donde se origina el ping. Escriba una lista separada por comas de nombres de equipos. La opción predeterminada es el equipo local.

Nota

Este parámetro no se admite en las versiones 6 y posteriores de PowerShell. Si se proporciona este parámetro, se produce un error.

Type:String
Position:Named
Default value:Local computer
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TargetName

Especifica los equipos que se van a probar. Escriba los nombres de equipo o las direcciones IP en formato IPv4 o IPv6.

Type:String[]
Aliases:ComputerName
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-TcpPort

Especifica el número de puerto TCP en el destino que se va a usar en la prueba de conexión TCP. El cmdlet intentará realizar una conexión TCP al puerto especificado en el destino.

Si se puede realizar una conexión, $True se devolverá.

Si no se puede realizar una conexión, $False se devolverá.

Type:Int32
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSeconds

Establece el valor de tiempo de espera de la prueba. Se produce un error en la prueba si no se recibe una respuesta antes de que expire el tiempo de espera. El valor predeterminado es cinco segundos.

Este parámetro se introdujo en PowerShell 6.0.

Type:Int32
Position:Named
Default value:5 seconds
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Traceroute

Hace que el cmdlet realice una prueba traceroute. Cuando se usa este parámetro, el cmdlet devuelve un TestConnectionCommand+TraceStatus objeto .

Type:SwitchParameter
Position:Named
Default value:False
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se puede canalizar la entrada a este cmdlet.

Salidas

TestConnectionCommand+PingStatus, TestConnectionCommand+TraceStatus, Boolean, TestConnectionCommand+PingMtuStatus

De forma predeterminada, Test-Connection devuelve un objeto TestConnectionCommand+PingStatus para cada respuesta de ping.

Si especifica el parámetro Traceroute , el cmdlet devolverá un objeto TestConnectionCommand+TraceStatus para cada respuesta de ping a lo largo de la ruta.

Si especifica los parámetros Quiet o TcpPort , devuelve un valor booleano . Si se prueban varias conexiones, se devuelve una matriz de valores booleanos .