Test-Connection
Envia pacotes de solicitação de eco ICMP (“pings”) para um ou mais computadores.
Sintaxe
Test-Connection [-ComputerName] <string[]> [[-Source] <string[]>] [-AsJob] [-Authentication {<Default> | <None> | <Connect> | <Call> | <Packet> | <PacketIntegrity> | <PacketPrivacy> | <Unchanged>}] [-BufferSize <int>] [-Count <int>] [-Credential <PSCredential>] [-Delay <int>] [-Impersonation {<Default> | <Anonymous> | <Identify> | <Impersonate> | <Delegate>}] [-Quiet] [-ThrottleLimit <int>] [-TimeToLive <int>] [<CommonParameters>]
Descrição
O cmdlet Test-Connection envia pacotes de solicitação de ecos (“ping”) Internet Control Message Protocol (ICMP) para um ou mais computadores remotos e retorna as respostas de eco. Você pode usar esse cmdlet para determinar quando um computador específico pode ser contatado através da 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 de segundo plano, estabelecer um tempo limite e o número de pings, e configurar a conexão e autenticação.
Ao contrário do comando “ping” tradicional, Test-Connection retorna um objeto Win32_PingStatus que você pode analisar no Windows PowerShell, mas você pode usar o parâmetro Quiet para forçá-lo a retornar apenas um valor Booleano.
Parâmetros
-AsJob
Executa o comando como um trabalho em segundo plano.
Observação: para usar esse parâmetro, os computadores local e remoto devem estar configurados para comunicação remota e, no Windows Vista e versões mais recentes do Windows, é necessário abrir o Windows PowerShell com a opção "Executar como administrador". Para obter mais informações, consulte about_Remote_Requirements.
Quando você usa o parâmetro AsJob, o comando imediatamente retorna um objeto que representa o trabalho em segundo plano. É possível 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 automaticamente retornados ao computador local. Para obter os resultados do trabalho, use o cmdlet Receive-Job.
Para obter mais informações sobre os trabalhos em segundo plano do Windows PowerShell, consulte about_Jobs e about_Remote_Jobs.
Necessário? |
false |
Posição? |
named |
Valor padrão |
False |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Authentication <AuthenticationLevel>
Especifica o nível de autenticação usado para a conexão WMI. (Test-Connection usa WMI.)
Os valores válidos são:
Unchanged: o nível de autenticação é igual ao do comando anterior.
Default: autenticação Windows.
None: sem autenticação COM.
Connect: autenticação COM de nível de conexão.
Call: autenticação COM de nível de chamada.
Packet: autenticação COM de nível de pacote.
PacketIntegrity: autenticação COM de nível de Integridade de Pacote.
PacketPrivacy: autenticação COM de nível de Privacidade de Pacote.
Necessário? |
false |
Posição? |
named |
Valor padrão |
4 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-BufferSize <int>
Especifica o tamanho, em bytes, do buffer enviado com esse comando. O valor padrão é 32.
Necessário? |
false |
Posição? |
named |
Valor padrão |
32 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ComputerName <string[]>
Especifica os computadores para fazer o ping. Digite os nomes dos computadores ou digite endereços IP no formato IPv4 ou IPv6. Não são permitidos caracteres curinga. Esse parâmetro é obrigatório.
Este parâmetro não se baseia na comunicação remota do Windows PowerShell. É possível usar o parâmetro ComputerName mesmo que o seu computador não esteja configurado para executar comandos remotos.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByPropertyName) |
Aceitar caracteres curinga? |
false |
-Count <int>
Especifica o número de solicitações de eco a serem enviadas. O valor padrão é 4.
Necessário? |
false |
Posição? |
named |
Valor padrão |
4 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Credential <PSCredential>
Especifica uma conta de usuário com permissão para executar essa ação. Digite um nome de usuário, como "User01" ou "Domain01\User01" ou insira um objeto PSCredential, como aquele do cmdlet Get-Credential.
Necessário? |
false |
Posição? |
named |
Valor padrão |
Usuário atual |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Delay <int>
Especifica o intervalo entre pings, em segundos.
Necessário? |
false |
Posição? |
named |
Valor padrão |
1 (segundo) |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Impersonation <ImpersonationLevel>
Especifica o nível de representação a ser usado ao chamar WMI. (Test-Connection usa WMI.) O valor padrão é "Impersonate".
Os valores válidos são:
Default: representação padrão.
Anonymous: oculta a identidade do chamador.
Identify: permite que os objetos consultem as credenciais do chamador.
Impersonate: permite que os objetos usem as credenciais do chamador.
Necessário? |
false |
Posição? |
named |
Valor padrão |
3 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Quiet
Suprime todos os erros e retorna $True se todos pings tiveram êxito e $False se todos falharam.
Necessário? |
false |
Posição? |
named |
Valor padrão |
False |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Source <string[]>
Especifica os nomes dos computadores onde o ping se origina. Digite uma lista de nomes de computadores separados por vírgulas. O padrão é o computador local.
Necessário? |
false |
Posição? |
2 |
Valor padrão |
Computador local |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ThrottleLimit <int>
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 igual a 0, o valor padrão, 32, será usado.
O limite se aplica somente ao comando atual, não à sessão ou ao computador.
Necessário? |
false |
Posição? |
named |
Valor padrão |
32 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-TimeToLive <int>
Especifica o tempo máximo, em segundos, que cada pacote de solicitação de eco ("pings") permanece ativo. O valor padrão é 80 (segundos). O alias do parâmetro TimeToLive é TTL.
Necessário? |
false |
Posição? |
named |
Valor padrão |
80 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
Nenhum Você não pode canalizar a entrada para este cmdlet. |
Saídas |
System.Management.ManagementObject#root\cimv2\Win32_PingStatus, System.Management.Automation.RemotingJob, System.Boolean Quando você usa o parâmetro AsJob, o cmdlet retorna um objeto de trabalho. Quando você usa o parâmetro Quiet, ele retorna um Booleano. Caso contrário, esse cmdlet retorna um objeto Win32_PingStatus para cada ping. |
Observações
Este cmdlet usa a classe Win32_PingStatus. Um comando "get-wmiojbect win32_pingstatus" equivale a um comando Test-Connection.
Exemplo 1
C:\PS>test-connection server01
Source Destination IPV4Address IPV6Address Bytes Time(ms)
------ ----------- ----------- ----------- ----- --------
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 0
ADMIN1 Server01 157.59.137.44 32 1
Descrição
-----------
Esse comando envia pacotes de solicitação de eco ("pings") do computador local para o computador Server01. O comando usa o parâmetro ComputerName para especificar o computador Server01, mas omite o nome opcional do parâmetro.
Exemplo 2
C:\PS>test-connection -computername server01, server02, server12 -credential domain01\user01
Descrição
-----------
Esse comando envia pacotes de solicitação de eco ("pings") do computador local para vários computadores remotos. Ele usa o parâmetro Credential para especificar uma conta de usuário que tem permissão para executar ping em todos os computadores remotos.
Exemplo 3
C:\PS>test-connection -source Server02, Server 12, localhost -computername Server01
Descrição
-----------
Esse comando envia pings de diferentes computadores de origem para um único computador remoto, Server01. Use esse formato de comando para testar a latência das conexões de vários pontos.
Exemplo 4
C:\PS>test-connection -computername Server01 -count 3 -delay 2 -TTL 256 -buffersize 256 -throttle 32
Descrição
-----------
Esse comando envia três pings do computador local para o computador Server01. Ele usa os parâmetros de Test-Connection para personalizar o comando.
Use esse formato de comando quando se esperar que a resposta do ping demore mais tempo do que o normal, devido a um número extenso de saltos ou ao excesso de tráfego na rede.
Exemplo 5
C:\PS>$job = test-connection -computername (get-content servers.txt) -asjob
C:\PS> if ($job.jobstateinfo.state -ne "Running") {$results = receive-job $job}
Descrição
-----------
Esse exemplo mostra como executar um comando Test-Connection como um trabalho em segundo plano do Windows PowerShell.
O primeiro comando usa o cmdlet Test-Connection para executar ping em vários computadores na empresa. O valor do parâmetro ComputerName é um comando Get-Content que lê uma lista de nomes de computadores no arquivo Servers.txt. O comando usa o parâmetro AsJob para executar o comando como um trabalho em segundo plano.
O segundo comando verifica se o trabalho ainda não está sendo executado e, caso não esteja, usa um comando Receive-Job para obter os resultados e armazená-los na variável $results.
Exemplo 6
C:\PS>test-connection Server55 -credential domain55\user01 -impersonation Identify
Descrição
-----------
O comando usa o cmdlet Test-Connection para executar o ping em um computador local. O comando usa o parâmetro Credential para especificar uma conta de usuário com permissão para executar o ping no computador remoto e o parâmetro Impersonation para alterar o nível de representação para "Identify".
Exemplo 7
C:\PS>if (test-connection -computername Server01 -quiet) {new-pssession Server01}
Descrição
-----------
Esse comando criará uma PSSession no Server01 somente se pelo menos um dos pings enviados ao computador tiver sucesso.
O comando usa o cmdlet Test-Connection 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 será $True se quaisquer dos quatro pings tiver sucesso; caso contrário, será false.
Se o comando Test-Connection retornar um valor $True, o comando usará o cmdlet New-PSSession para criar a PSSession.