Test-Connection
Envia pacotes de solicitação de eco ICMP, ou pings, para um ou mais computadores.
Sintaxe
DefaultPing (Predefinição)
Test-Connection
[-TargetName] <string[]>
[-Ping]
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-Count <int>]
[-Delay <int>]
[-BufferSize <int>]
[-DontFragment]
[-Quiet]
[-TimeoutSeconds <int>]
[<CommonParameters>]
RepeatPing
Test-Connection
[-TargetName] <string[]>
-Repeat
[-Ping]
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-Delay <int>]
[-BufferSize <int>]
[-DontFragment]
[-Quiet]
[-TimeoutSeconds <int>]
[<CommonParameters>]
TraceRoute
Test-Connection
[-TargetName] <string[]>
-Traceroute
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-MaxHops <int>]
[-Quiet]
[-TimeoutSeconds <int>]
[<CommonParameters>]
MtuSizeDetect
Test-Connection
[-TargetName] <string[]>
-MtuSize
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Quiet]
[-TimeoutSeconds <int>]
[<CommonParameters>]
TcpPort
Test-Connection
[-TargetName] <string[]>
-TcpPort <int>
[-IPv4]
[-IPv6]
[-ResolveDestination]
[-Source <string>]
[-Count <int>]
[-Delay <int>]
[-Repeat]
[-Quiet]
[-TimeoutSeconds <int>]
[-Detailed]
[<CommonParameters>]
Description
O cmdlet Test-Connection 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 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 Test-Connection para especificar os computadores de 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 conhecido comando ping, Test-Connection retorna um objeto TestConnectionCommand+PingStatus que pode ser investigado no PowerShell. O parâmetro Quiet retorna um valor booleano em um objeto System.Boolean para cada conexão testada. Se várias conexões forem testadas, uma matriz de valores booleanos de 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 -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 o parâmetro TargetName para especificar o computador Server01. O parâmetro IPv4 especifica o protocolo para o teste.
Uma série de objetos TestConnectionCommand+PingStatus são enviados no fluxo de saída, um objeto por resposta de ping da máquina de destino.
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 -TargetName Server01, Server02, Server12
Exemplo 3: 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 -TargetName Server01 -Count 3 -Delay 2 -MaxHops 255 -BufferSize 256
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 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 4: 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 = Start-Job -ScriptBlock { Test-Connection -TargetName (Get-Content -Path "Servers.txt") }
$Results = Receive-Job $job -Wait
O comando Start-Job usa o cmdlet Test-Connection para executar ping em muitos computadores em uma empresa.
O valor do parâmetro TargetName é um comando Get-Content que lê uma lista de nomes de computadores do arquivo Servers.txt. O comando usa o cmdlet Start-Job para executar o comando como um trabalho em segundo plano e salva o trabalho na variável $job.
O comando Receive-Job é instruído a -Wait até que o trabalho seja concluído e depois obtém os resultados e os armazena na variável $Results.
Exemplo 5: 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 -TargetName Server01 -Quiet) { New-PSSession -ComputerName Server01 }
O cmdlet Test-Connection executa ping no computador Server01, com o parâmetro Quiet fornecido.
O valor resultante é $true se qualquer um dos quatro pings for bem-sucedido. Se nenhum dos pings tiver sucesso, o valor será $false.
Se o comando Test-Connection retornar um valor de $true, o comando usará o cmdlet New-PSSession para criar o PSSession.
Exemplo 6: Usar o parâmetro Traceroute
Introduzido no PowerShell 6.0, o parâmetro Traceroute mapeia uma rota entre o computador local e o destino remoto especificado com o 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
O comando Test-Connection é chamado com o parâmetro Traceroute. Os resultados, que são objetos [Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus], são enviados para o fluxo de saída Success.
Exemplo 7: Obter saída detalhada para um teste de conexão TCP
Quando você usa o parâmetro Detailed, esse cmdlet retorna informações detalhadas sobre o status das tentativas de conexão TCP.
Test-Connection bing.com -TCPPort 443 -Detailed -Count 4
Target: bing.com
Id Source Address Port Latency(ms) Connected Status
-- ------ ------- ---- ----------- --------- ------
1 circumflex 2620:1ec:c11::200 443 12 True Success
2 circumflex 2620:1ec:c11::200 443 14 True Success
3 circumflex 2620:1ec:c11::200 443 17 True Success
4 circumflex 2620:1ec:c11::200 443 17 True Success
Parâmetros
-BufferSize
Especifica o tamanho, em bytes, do buffer enviado com este comando. O valor padrão é 32.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 32 |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Tamanho, bytes, Licenciatura em Ciências |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Count
Especifica o número de solicitações de eco a serem enviadas. O valor padrão é 4.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 4 |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TcpPort
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Delay
Especifica o intervalo entre pings, em segundos.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TcpPort
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Detailed
Quando você usa o parâmetro Detailed, esse cmdlet retorna informações detalhadas sobre o status das tentativas de conexão TCP.
Esse parâmetro foi adicionado no PowerShell 7.4.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
TcpPort
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-DontFragment
Este parâmetro define o sinalizador Não fragmentar no cabeçalho IP. Você pode usar esse parâmetro com o parâmetro BufferSize para testar o tamanho da MTU do caminho. Para obter mais informações sobre o Path MTU, consulte o artigo Path MTU Discovery na wikipedia.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-IPv4
Força o cmdlet a usar o protocolo IPv4 para o teste.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-IPv6
Força o cmdlet a usar o protocolo IPv6 para o teste.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MaxHops
Define o número máximo de saltos que uma mensagem de solicitação ICMP pode ser enviada. O valor padrão é controlado pelo sistema operacional. O valor padrão para Windows 10 e superior é 128 saltos.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 128 |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | TTL, TimeToLive, Lúpulo |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TraceRoute
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-MtuSize
Este parâmetro é usado para descobrir o tamanho do MTU do percurso. O cmdlet retorna um objeto PingReply#MTUSize que contém o tamanho da MTU do caminho para o destino. Para obter mais informações sobre o Path MTU, consulte o artigo Path MTU Discovery na wikipedia.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | MtuSizeDetect |
Conjuntos de parâmetros
MtuSizeDetect
| Position: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Ping
Faz com que o cmdlet faça um teste de ping. Este é o modo padrão para o cmdlet Test-Connection.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | True |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Quiet
O parâmetro Quiet retorna um valor booleano. O uso desse parâmetro suprime todos os erros.
Cada conexão testada retorna um valor booleano de . Se o parâmetro TargetName especificar vários computadores, uma matriz de valores booleanos será retornada.
Se qualquer ping para um determinado destino tenha sido bem-sucedido, $true será retornado.
Se todos os pings para um determinado destino falharem, $false será retornado.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Repeat
Faz com que o cmdlet envie solicitações de ping continuamente. Quando o valor de TargetName é uma matriz de destinos, o cmdlet repete as solicitações de ping somente para o primeiro destino. Ignora os restantes objetivos. Este parâmetro não pode ser usado com o parâmetro Count.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Contínuo |
Conjuntos de parâmetros
RepeatPing
| Position: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TcpPort
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-ResolveDestination
Faz com que o cmdlet tente resolver o nome DNS do destino. Quando usado em conjunto com o parâmetro Traceroute, os nomes DNS de todos os hosts intermediários também serão recuperados, se possível.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Source
Especifica os nomes dos computadores de onde o ping se origina. Insira uma lista separada por vírgulas de nomes de computadores. O padrão é o computador local.
Observação
Este parâmetro não é suportado nas versões 6 e superiores do PowerShell. O fornecimento desse parâmetro causa um erro.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | Local computer |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
DefaultPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
RepeatPing
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TraceRoute
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
TcpPort
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-TargetName
Especifica o(s) computador(es) a testar. Digite os nomes dos computadores ou digite endereços IP no formato IPv4 ou IPv6.
Propriedades dos parâmetros
| Tipo: | String[] |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Nome do Computador |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-TcpPort
Especifica o número da porta TCP no destino a ser usado no teste de conexão TCP.
O cmdlet tenta fazer uma conexão TCP com a porta especificada no destino.
- O cmdlet retorna
$truese uma conexão for feita. - O cmdlet retornará
$falsese uma conexão não for feita.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
TcpPort
| Position: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-TimeoutSeconds
Define o valor de tempo limite para o teste. O teste falhará se uma resposta não for recebida antes que o tempo limite expire. O padrão é cinco segundos.
Esse parâmetro foi introduzido no PowerShell 6.0.
Propriedades dos parâmetros
| Tipo: | Int32 |
| Default value: | 5 seconds |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Traceroute
Faz com que o cmdlet faça um teste traceroute. Quando esse parâmetro é usado, o cmdlet retorna um objeto TestConnectionCommand+TraceStatus.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
TraceRoute
| Position: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | 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
Não é possível canalizar objetos para este cmdlet.
Saídas
Microsoft.PowerShell.Commands.TestConnectionCommand+PingStatus
Por padrão, esse cmdlet retorna um objeto TestConnectionCommand+PingStatus
Microsoft.PowerShell.Commands.TestConnectionCommand+TraceStatus
Quando usas o parâmetro Traceroute, este cmdlet devolve um objeto TestConnectionCommand+TraceStatus para cada resposta de ping ao longo da rota.
Boolean
Quando você usa os parâmetros Quiet ou TcpPort, esse cmdlet retorna um valor Boolean. Se o cmdlet testar várias conexões, ele retornará uma matriz de valores booleanos.
Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus
Quando você usa o parâmetro
Microsoft.PowerShell.Commands.TestConnectionCommand+TcpPortStatus
Quando você usa o parâmetro Detailed, esse cmdlet retorna um objeto TestConnectionCommand+TcpPortStatus que mostra o status da conexão TCP.
Notas
No Linux, usar o parâmetro BufferSize ou qualquer combinação de parâmetros com o MtuSize conjunto de parâmetros que resulte em um tamanho de buffer não padrão de 32 bytes pode exigir sudo. Nesses casos, Test-Command gera uma exceção com uma mensagem indicando que sudo é necessária.