Compartilhar via

Test-Connection

Módulo:
Microsoft.PowerShell.Management Module

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

Sintaxe

Default (Default) 

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

O cmdlet Test-Connection envia pacotes de solicitação de eco de protocolo ICMP, 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 em uma rede IP.

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

Ao contrário do comando de 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 forem testadas várias conexões, uma matriz de valores Boolean será retornada.

Exemplos

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

Esse exemplo envia pacotes de solicitação 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 diferentes computadores de origem para um único computador remoto, o 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 esse formato de comando para testar a latência de conexões de vários pontos.

Exemplo 4: Usar parâmetros para personalizar o comando de teste

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 TargetName 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 a resposta de ping deve levar mais tempo do que o normal, seja 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 comando Test-Connection 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 comando Test-Connection executa ping em muitos computadores em uma empresa. O valor do parâmetro ComputerName é um comando Get-Content que lê uma lista de nomes de computador do Servers.txt file. O comando usa o parâmetro AsJob para executar o comando como um trabalho em segundo plano e salva o trabalho na variável $job.

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

Exemplo 6: Executar ping em um computador remoto com credenciais

Esse comando usa o cmdlet Test-Connection 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 de Representação para alterar o nível de representação para Identificar.

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 tiver êxito.

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

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

Se o comando Test-Connection retornar um valor de $True, o comando usará o cmdlet New-PSSession para criar a 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 versões posteriores do sistema operacional Windows, você deve abrir o PowerShell usando a opção Executar como administrador. Para obter mais informações, confira 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 é concluído. 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 cmdlet Receive-Job.

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

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Default
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
Source
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Authentication

Especifica o nível de autenticação usado para a conexão WMI. Test-Connection usa WMI.

Os valores válidos são os seguintes:

  • Inalterado: o nível de autenticação é o mesmo que o comando anterior.
  • Padrão: Autenticação do Windows.
  • None: nenhuma autenticação COM.
  • Connect: autenticação COM no nível de conexão.
  • Call: 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 do pacote.

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

Propriedades do parâmetro

Tipo:AuthenticationLevel
Valor padrão:Packet (enumerated value of 4)
Valores aceitos:Default, None, Connect, Call, Packet, PacketIntegrity, PacketPrivacy, Unchanged
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-BufferSize

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

Propriedades do parâmetro

Tipo:Int32
Valor padrão:32
Dá suporte a curingas:False
DontShow:False
Aliases:Tamanho, Bytes, Bacharelado em Ciências

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-ComputerName

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

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

Propriedades do parâmetro

Tipo:

String[]

Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:China, Endereço IP, __SERVIDOR, Servidor, Destino

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:True
Valor dos argumentos restantes:False

-Count

Especifica o número de solicitações de eco a serem enviadas. O valor padrão é 4.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:4
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 cmdlet .

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

Propriedades do parâmetro

Tipo:PSCredential
Valor padrão:Current user
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Source
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Delay

Especifica o intervalo entre pings, em segundos.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:1 (second)
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Impersonation

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

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

  • Padrão. Representação padrão.
  • Anônimo. Oculta a identidade do chamador.
  • Identificar. Permite que os objetos consultem as credenciais do chamador.
  • Representar. Permite que os objetos usem as credenciais do chamador.

O valor padrão é Represente.

Propriedades do parâmetro

Tipo:ImpersonationLevel
Valor padrão:Impersonate
Valores aceitos:Default, Anonymous, Identify, Impersonate, Delegate
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Quiet

O parâmetro Quiet retorna um valor de booliano em um objeto System.Boolean. Usar esse 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 de booliano será retornada.

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

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

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Quiet
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Source

Especifica os nomes dos computadores nos quais o ping se origina. Insira uma lista separada por vírgulas de nomes de computador. O padrão é o computador local.

Propriedades do parâmetro

Tipo:

String[]

Valor padrão:Local computer
Dá suporte a curingas:False
DontShow:False
Aliases:FCN, SRC

Conjuntos de parâmetros

Source
Cargo:1
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 limitação se aplica somente ao comando atual, não à sessão ou ao computador.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:32
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Default
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
Source
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-TimeToLive

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

Propriedades do parâmetro

Tipo:Int32
Valor padrão:128 in Windows
Dá suporte a curingas:False
DontShow:False
Aliases:TTL

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Você não pode canalizar a entrada para este cmdlet.

Saídas

ManagementObject

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

Se você especificar o parâmetro Quiet, ele retornará um valor de booliano . Se forem testadas várias conexões, uma matriz de valores Boolean será retornada. Caso contrário, Test-Connection retorna um objeto Win32_PingStatus para cada ping.

Observações

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

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