Partilhar via

Test-Connection

  • Referência
Módulo:
Microsoft.PowerShell.Management

Envia pacotes de solicitação de eco ICMP, ou pings, para um ou mais computadores.

Syntax

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>]

Description

O Test-Connection cmdlet envia pacotes de solicitação de eco ICMP (Internet Control Message Protocol), ou pings, para um ou mais computadores remotos e retorna as respostas de resposta de eco. Você pode usar esse cmdlet para determinar se um determinado computador pode ser contatado através de uma rede IP.

Você pode usar os parâmetros de para especificar os computadores de Test-Connection envio e de recebimento, para executar o comando como um trabalho em segundo plano, para definir um tempo limite e um número de pings e para configurar a conexão e a autenticação.

Ao contrário do comando ping familiar, Test-Connection retorna um objeto Win32_PingStatus que você pode investigar no PowerShell. O parâmetro Quiet retorna um valor Boolean em um objeto System.Boolean para cada conexão testada. Se várias conexões forem testadas, uma matriz de valores booleanos será retornada.

Exemplos

Exemplo 1: Enviar solicitações de eco para um computador remoto

Este exemplo envia pacotes de solicitação de eco do computador local para o computador 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 o parâmetro ComputerName para especificar o computador Server01.

Exemplo 2: Enviar solicitações de eco para vários computadores

Este exemplo envia pings do computador local para vários computadores remotos.

Test-Connection -ComputerName Server01, Server02, Server12

Exemplo 3: Enviar solicitações de eco de vários computadores para um computador

Este exemplo envia pings de computadores de origem diferentes para um único computador remoto, Server01.

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

Test-Connection usa o parâmetro Credential para especificar as credenciais de um usuário que tem permissão para enviar uma solicitação de ping dos computadores de origem. Use este formato de comando para testar a latência de conexões de vários pontos.

Exemplo 4: Usar parâmetros para personalizar o comando test

Este exemplo usa os parâmetros de Test-Connection para personalizar o comando. O computador local envia um teste de ping para um computador remoto.

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

Test-Connection usa o parâmetro ComputerName para especificar Server01. O parâmetro Count especifica que três pings são enviados para o computador Server01 com um atraso de intervalos de 2 segundos.

Você pode usar essas opções quando se espera que a resposta de ping demore mais do que o normal, devido a um número estendido de saltos ou a uma condição de rede de alto tráfego.

Exemplo 5: Executar um teste como um trabalho em segundo plano

Este exemplo mostra como executar um Test-Connection comando como um trabalho em segundo plano do PowerShell.

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

O Test-Connection comando pings muitos computadores em uma empresa. O valor do parâmetro ComputerName é um Get-Content comando que lê uma lista de nomes de computadores do Servers.txt file. O comando usa o parâmetro AsJob para executar o comando como um trabalho em segundo plano e salva o $job trabalho na variável.

O if comando verifica se o trabalho ainda não está em execução. Se o trabalho não estiver em execução, Receive-Job obtém os resultados e armazena-os $Results na variável.

Exemplo 6: Executar ping em um computador remoto com credenciais

Este comando usa o Test-Connection cmdlet para executar ping em um computador remoto.

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

O comando usa o parâmetro Credential para especificar uma conta de usuário que tenha permissão para executar ping no computador remoto e o parâmetro Imrepresentation para alterar o nível de representação para Identify.

Exemplo 7: Criar uma sessão somente se um teste de conexão for bem-sucedido

Este exemplo cria uma sessão no computador Server01 somente se pelo menos um dos pings enviados para o computador for bem-sucedido.

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

O if comando usa o Test-Connection cmdlet para executar ping no computador Server01. O comando usa o parâmetro Quiet , que retorna um valor booleano , em vez de um objeto Win32_PingStatus . O valor é $True se qualquer um dos quatro pings for bem-sucedido e for, caso contrário, $False.

Se o Test-Connection comando retornar um valor de $True, o comando usará o New-PSSession cmdlet para criar o PSSession.

Parâmetros

-AsJob

Indica que esse cmdlet é executado como um trabalho em segundo plano.

Para usar esse parâmetro, os computadores locais e remotos devem ser configurados para comunicação remota e, no Windows Vista e em versões posteriores do sistema operacional Windows, você deve abrir o PowerShell usando a opção Executar como administrador . Para obter mais informações, consulte about_Remote_Requirements.

Quando você especifica o parâmetro AsJob , o comando retorna imediatamente um objeto que representa o trabalho em segundo plano. Você pode continuar a trabalhar na sessão enquanto o trabalho termina. O trabalho é criado no computador local e os resultados de computadores remotos são retornados automaticamente para o computador local. Para obter os resultados do trabalho, use o Receive-Job cmdlet.

Para obter mais informações sobre trabalhos em segundo plano do PowerShell, consulte about_Jobs e about_Remote_Jobs.

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

-BufferSize

Especifica o tamanho, em bytes, do buffer enviado com este comando. O valor padrão é 32.

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

-ComputerName

Especifica os computadores a serem submetidos a ping. Digite os nomes dos computadores ou digite endereços IP no formato IPv4 ou IPv6. Caracteres curinga não são permitidos. Este parâmetro é obrigatório.

Esse parâmetro não depende da comunicação remota do PowerShell. Você pode usar o parâmetro ComputerName mesmo que o computador não esteja configurado para executar comandos remotos.

Nota

O parâmetro ComputerName é renomeado para TargetName no PowerShell 6.0 e superior.

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 o número de solicitações de eco a serem enviadas. O valor predefinido é 4.

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

-Credential

Especifica uma conta de usuário que tem permissão para enviar uma solicitação de ping do computador de origem. Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential , como um do Get-Credential cmdlet.

O parâmetro Credential é válido somente quando o parâmetro Source é usado no comando. As credenciais não afetam o computador de destino.

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

-DcomAuthentication

Especifica o nível de autenticação que esse cmdlet usa com o WMI. Test-Connection usa WMI. Os valores aceitáveis para este parâmetro são:

  • Inadimplência. Autenticação do Windows
  • Nenhum. Sem autenticação COM
  • Ligar. Autenticação COM no nível de conexão
  • Ligue. Autenticação COM no nível de chamada
  • Pacote. Autenticação COM no nível do pacote
  • PacketIntegrity. Autenticação COM no nível de integridade do pacote
  • PacketPrivacy. Autenticação COM no nível de privacidade de pacotes
  • Inalterado. O mesmo que o comando anterior

O valor padrão é Packet que tem um valor enumerado de 4. Para obter mais informações sobre os valores desse parâmetro, consulte AuthenticationLevel enumeration.

Type:AuthenticationLevel
Aliases:Authentication
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

-Delay

Especifica o intervalo entre pings, em segundos.

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

-Impersonation

Especifica o nível de representação a ser usado quando esse cmdlet chamar WMI. Test-Connection usa WMI.

Os valores aceitáveis para este parâmetro são os seguintes:

  • Inadimplência. Representação padrão.
  • Anónimo. Oculta a identidade do chamador.
  • Identifique. Permite que os objetos consultem as credenciais do chamador.
  • Personificar. Permite que os objetos usem as credenciais do chamador.

O valor padrão é Impersonate.

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

-Protocol

Especifica um protocolo. Os valores aceitáveis para este parâmetro são DCOM e WSMan.

Type:String
Accepted values:DCOM, WSMan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Quiet

O parâmetro Quiet retorna um valor booleano em um objeto System.Boolean . O uso desse parâmetro suprime todos os erros.

Cada conexão testada retorna um valor booleano . Se o parâmetro ComputerName especificar vários computadores, uma matriz de valores booleanos será retornada.

Se algum ping for bem-sucedido, $True será retornado.

Se todos os pings falharem, $False será retornado.

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

-Source

Especifica os nomes dos computadores de onde o ping se origina. Insira uma lista separada por vírgulas de nomes de computadores. A predefinição é o computador local.

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

-ThrottleLimit

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar esse comando. Se você omitir esse parâmetro ou inserir um valor de 0, o valor padrão, 32, será usado.

O limite de aceleração aplica-se apenas ao comando atual, não à sessão ou ao computador.

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

-TimeToLive

Especifica as vezes máximas que um pacote pode ser encaminhado. Para cada salto em gateways, roteadores, etc., o valor TimeToLive é reduzido em um. No zero, o pacote é descartado e um erro é retornado. No Windows, o valor padrão é 128. O alias do parâmetro TimeToLive é TTL.

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

-WsmanAuthentication

Especifica o mecanismo usado para autenticar as credenciais do usuário quando esse cmdlet usa o protocolo WSMan. Os valores aceitáveis para este parâmetro são:

  • Básica
  • CredSSP
  • Predefinido
  • Resumo
  • Kerberos
  • Negociar.

O valor padrão é Default.

Para obter mais informações sobre os valores desse parâmetro, consulte Enumeração AuthenticationMechanism.

Cuidado: A autenticação CredSSP (Credential Security Service Provider), na qual as credenciais do usuário são passadas para um computador remoto para ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Este mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas para ele podem ser usadas para controlar a sessão de rede.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Type:String
Accepted values:Default, Basic, Negotiate, CredSSP, Digest, Kerberos
Position:Named
Default value:Default
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

ManagementObject

Por padrão, esse cmdlet retorna um objeto Win32_PingStatus para cada resposta de ping.

System.Management.Automation.RemotingJob

Esse cmdlet retorna um objeto de trabalho, se você especificar o parâmetro AsJob .

Boolean

Quando você usa o parâmetro Quiet , isso retorna um valor booleano . Se o cmdlet testar várias conexões, ele retornará uma matriz de valores booleanos .

Notas

Este cmdlet usa a classe Win32_PingStatus . Um Get-WMIObject Win32_PingStatus comando é equivalente a um Test-Connection comando.

O conjunto de parâmetros Source foi introduzido no PowerShell 3.0.