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
    [-ComputerName] <String[]>
    [-AsJob]
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Impersonation <ImpersonationLevel>]
    [-ThrottleLimit <Int32>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [<CommonParameters>]
Test-Connection
    [-ComputerName] <String[]>
    [-Source] <String[]>
    [-AsJob]
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Credential <PSCredential>]
    [-Impersonation <ImpersonationLevel>]
    [-ThrottleLimit <Int32>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [<CommonParameters>]
Test-Connection
    [-ComputerName] <String[]>
    [-Authentication <AuthenticationLevel>]
    [-BufferSize <Int32>]
    [-Count <Int32>]
    [-Impersonation <ImpersonationLevel>]
    [-TimeToLive <Int32>]
    [-Delay <Int32>]
    [-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 Win32_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 -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 usa el parámetro ComputerName para especificar el equipo Server01.

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 -ComputerName Server01, Server02, Server12

Ejemplo 3: Envío de solicitudes de eco desde varios equipos a un equipo

En este ejemplo se envían pings desde distintos equipos de origen a un único equipo remoto, Server01.

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

Test-Connection usa el parámetro Credential para especificar las credenciales de un usuario que tiene permiso para enviar una solicitud de ping desde los equipos de origen. Utilice este formato de comando para probar la latencia de las conexiones desde varios puntos.

Ejemplo 4: 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 -ComputerName Server01 -Count 3 -Delay 2 -TTL 255 -BufferSize 256 -ThrottleLimit 32

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 5: 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 = Test-Connection -ComputerName (Get-Content Servers.txt) -AsJob
if ($job.JobStateInfo.State -ne "Running") {$Results = Receive-Job $job}

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

El if comando comprueba que el trabajo todavía no se está ejecutando. Si el trabajo no se está ejecutando, Receive-Job obtiene los resultados y los almacena en la $Results variable .

Ejemplo 6: Hacer ping a un equipo remoto con credenciales

Este comando usa el Test-Connection cmdlet para hacer ping a un equipo remoto.

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

El comando usa el parámetro Credential para especificar una cuenta de usuario que tenga permiso para hacer ping al equipo remoto y al parámetro Impersonation para cambiar el nivel de suplantación a Identificar.

Ejemplo 7: 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 -ComputerName Server01 -Quiet) {New-PSSession Server01}

El if comando usa el Test-Connection cmdlet para hacer ping al equipo Server01. El comando usa el parámetro Quiet , que devuelve un valor booleano , en lugar de un objeto Win32_PingStatus . El valor es $True si cualquiera de los cuatro pings es correcto y, de lo contrario, $Falsees .

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

Parámetros

-AsJob

Indica que este cmdlet se ejecuta como un trabajo en segundo plano.

Para usar este parámetro, los equipos locales y remotos deben configurarse para la comunicación remota y, en Windows Vista y versiones posteriores del sistema operativo Windows, debe abrir PowerShell mediante la opción Ejecutar como administrador . Para obtener más información, consulte about_Remote_Requirements.

Al especificar el parámetro AsJob , el comando devuelve inmediatamente un objeto que representa el trabajo en segundo plano. Puede seguir trabajando en la sesión mientras finaliza el trabajo. Se crea el trabajo en el equipo local y, automáticamente, se devuelven los resultados de los equipos remotos al equipo local. Para obtener los resultados del trabajo, use el Receive-Job cmdlet .

Para más información sobre los trabajos en segundo plano de PowerShell, consulte about_Jobs y about_Remote_Jobs.

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

-Authentication

Especifica el nivel de autenticación que se usa para la conexión WMI. Test-Connection usa WMI.

Los valores válidos son los siguientes:

  • Sin cambios: el nivel de autenticación es el mismo que el comando anterior.
  • Valor predeterminado: autenticación de Windows.
  • Ninguno: sin autenticación COM.
  • Conectar: autenticación COM de nivel de conexión.
  • Llamada: autenticación COM de nivel de llamada.
  • Paquete: autenticación COM de nivel de paquete.
  • PacketIntegrity: autenticación COM de nivel de integridad de paquetes.
  • PacketPrivacy: autenticación COM de nivel de privacidad de paquetes.

El valor predeterminado es Packet que tiene un valor enumerado de 4. Para obtener más información sobre los valores de este parámetro, consulte La enumeración AuthenticationLevel .

Type:AuthenticationLevel
Accepted values:Default, None, Connect, Call, Packet, PacketIntegrity, PacketPrivacy, Unchanged
Position:Named
Default value:Packet (enumerated value of 4)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-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

-ComputerName

Especifica los equipos a los que se enviarán los pings. Escriba los nombres de equipo o las direcciones IP en formato IPv4 o IPv6. No se admite el uso de caracteres comodín. Este parámetro es obligatorio.

Este parámetro no se basa en la comunicación remota de PowerShell. Puede usar el parámetro ComputerName incluso si el equipo no está configurado para ejecutar comandos remotos.

Type:String[]
Aliases:CN, IPAddress, __SERVER, Server, Destination
Position:0
Default value:None
Required:True
Accept pipeline input:True
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

-Credential

Especifica una cuenta de usuario con permiso para enviar una solicitud de ping desde el equipo de origen. Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential , como uno del Get-Credential cmdlet.

El parámetro Credential sólo es válido cuando se usa el parámetro Source en el comando. Las credenciales no afectan al equipo de destino.

Type:PSCredential
Position:Named
Default value:Current user
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Delay

Especifica el intervalo entre pings en segundos.

Type:Int32
Position:Named
Default value:1 (second)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Impersonation

Especifica el nivel de suplantación que se va a usar cuando este cmdlet llama a WMI. Test-Connection usa WMI.

Los valores aceptables para este parámetro son los siguientes:

  • Default. Suplantación predeterminada.
  • Anónimo. oculta la identidad de la persona que llama.
  • Identificar. permite que los objetos consulten las credenciales de la persona que llama.
  • Suplantar. permite que los objetos usen las credenciales de la persona que llama.

El valor predeterminado es Suplantar.

Type:ImpersonationLevel
Accepted values:Default, Anonymous, Identify, Impersonate, Delegate
Position:Named
Default value:Impersonate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Quiet

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

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

Si algún ping se realiza correctamente, $True se devuelve.

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

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.

Type:String[]
Aliases:FCN, SRC
Position:1
Default value:Local computer
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ThrottleLimit

Especifica el número máximo de operaciones simultáneas que se pueden establecer para ejecutar este comando. Si omite este parámetro o escribe un valor 0, se usa el valor predeterminado, 32.

El límite solo se aplica al comando actual, no a la sesión ni al equipo.

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

-TimeToLive

Especifica las horas máximas que se puede reenviar un paquete. Para cada salto en puertas de enlace, enrutadores, etc. el valor TimeToLive se reduce en uno. En cero, el paquete se descarta y se devuelve un error. En Windows, el valor predeterminado es 128. El alias del parámetro TimeToLive es TTL.

Type:Int32
Aliases:TTL
Position:Named
Default value:128 in Windows
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se puede canalizar la entrada a este cmdlet.

Salidas

ManagementObject

Este cmdlet devuelve un objeto de trabajo, si especifica el parámetro AsJob .

Si especifica el parámetro Quiet , devuelve un valor booleano . Si se prueban varias conexiones, se devuelve una matriz de valores booleanos . De lo contrario, Test-Connection devuelve un objeto Win32_PingStatus para cada ping.

Notas

Este cmdlet usa la clase Win32_PingStatus . Un Get-WMIObject Win32_PingStatus comando es equivalente a un Test-Connection comando.

El conjunto de parámetros source se introdujo en PowerShell 3.0.