Test-Connection
Envia pacotes de solicitação de eco ICMP, ou pings, para um ou mais computadores.
Sintaxe
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
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 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 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
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, Server12Exemplo 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 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 TargetName para especificar Server01. O parâmetro
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 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 pings muitos computadores em uma empresa. O valor do parâmetro ComputerName é um comando Get-Content 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 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 obtém os resultados e os armazena na variável $Results.
Exemplo 6: Executar ping em um computador remoto com credenciais
Este comando usa o cmdlet Test-Connection para executar ping em um computador remoto.
Test-Connection Server55 -Credential Domain55\User01 -Impersonation IdentifyO 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 Impersonation 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 comando if usa o cmdlet Test-Connection para executar ping no computador Server01. O comando usa o parâmetro $True se qualquer um dos quatro pings for bem-sucedido e for, caso contrário, $False.
Se o comando Test-Connection retornar um valor de $True, o comando usará o cmdlet New-PSSession 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 opção. 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 cmdlet Receive-Job.
Para obter mais informações sobre trabalhos em segundo plano do PowerShell, consulte about_Jobs e about_Remote_Jobs.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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:
- Unchanged: O nível de autenticação é o mesmo que o comando anterior.
- padrão: Autenticação do Windows.
- Nenhum: 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 no nível do pacote.
- PacketIntegrity: Autenticação COM no nível de integridade de pacotes.
- PacketPrivacy: Autenticação COM no nível de privacidade do pacote.
O valor padrão é de pacote que tem um valor enumerado de 4. Para obter mais informações sobre os valores desse parâmetro, consulte AuthenticationLevel enumeração.
| Tipo: | AuthenticationLevel |
| Valores aceites: | Default, None, Connect, Call, Packet, PacketIntegrity, PacketPrivacy, Unchanged |
| Position: | Named |
| Default value: | Packet (enumerated value of 4) |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-BufferSize
Especifica o tamanho, em bytes, do buffer enviado com este comando. O valor padrão é 32.
| Tipo: | Int32 |
| Aliases: | Size, Bytes, BS |
| Position: | Named |
| Default value: | 32 |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | String[] |
| Aliases: | CN, IPAddress, __SERVER, Server, Destination |
| Position: | 0 |
| Default value: | None |
| Necessário: | True |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | False |
-Count
Especifica o número de solicitações de eco a serem enviadas. O valor padrão é 4.
| Tipo: | Int32 |
| Position: | Named |
| Default value: | 4 |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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 Get-Credential.
O parâmetro Credential é válido somente quando o parâmetro Source é usado no comando. As credenciais não afetam o computador de destino.
| Tipo: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Delay
Especifica o intervalo entre pings, em segundos.
| Tipo: | Int32 |
| Position: | Named |
| Default value: | 1 (second) |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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:
- Padrão. Representação padrão.
- Anónimo. Oculta a identidade do chamador.
- Identificar. Permite que os objetos consultem as credenciais do chamador.
- Personificar. Permite que os objetos usem as credenciais do chamador.
O valor padrão é Impersonate.
| Tipo: | ImpersonationLevel |
| Valores aceites: | Default, Anonymous, Identify, Impersonate, Delegate |
| Position: | Named |
| Default value: | Impersonate |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Quiet
O parâmetro
Cada conexão testada retorna um valor de booleano. Se o parâmetro ComputerName especificar vários computadores, uma matriz de valores de booleanos será retornada.
Se qualquer ping for bem-sucedido, $True será retornado.
Se todos os pings falharem, $False será retornado.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | String[] |
| Aliases: | FCN, SRC |
| Position: | 1 |
| Default value: | Local computer |
| Necessário: | True |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | Int32 |
| Position: | Named |
| Default value: | 32 |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | Int32 |
| Aliases: | TTL |
| Position: | Named |
| Default value: | 128 in Windows |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
Entradas
None
Não é possível canalizar a entrada para este cmdlet.
Saídas
Este cmdlet retorna um objeto de trabalho, se você especificar o parâmetro AsJob.
Se você especificar o parâmetro Quiet, ele retornará um valor Boolean. Se várias conexões forem testadas, uma matriz de valores de booleanos será retornada. Caso contrário, Test-Connection retorna um objeto Win32_PingStatus para cada ping.
Notas
Este cmdlet usa a classe Win32_PingStatus. Um comando Get-WMIObject Win32_PingStatus é equivalente a um comando Test-Connection.
O conjunto de parâmetros Source foi introduzido no PowerShell 3.0.