Test-Path Cmdlet do PowerShell: Verificar Arquivos, Chaves e Mais

Se você precisa validar um caminho para um arquivo, chave de registro, certificado ou qualquer outro caminho de PowerShell drive, você precisa do cmdlet Test-Path.

O cmdlet Test-Path é uma maneira simples, mas útil, de verificar rapidamente muitos atributos de um arquivo e outros itens. Ele pode verificar se um arquivo existe (ou outros tipos de itens), se uma string está no formato de caminho adequado ou até mesmo se um item é mais recente ou mais antigo que um tempo específico.

Neste tutorial, você vai aprender tudo sobre o cmdlet Test-Path do PowerShell e como usá-lo para aprimorar seus scripts do PowerShell.

Pré-requisitos

Se você quiser seguir os exemplos deste tutorial, você vai precisar de uma coisa; PowerShell. Mais especificamente, o tutorial usará PowerShell v7.03 no Windows 10, embora muitas das técnicas que você aprenderá se apliquem a versões mais antigas também.

O que o cmdlet Test-Path faz?

O cmdlet Test-Path do PowerShell é um dos comandos mais simples. É um comando que está no PowerShell desde o início e só retorna dois valores; Verdadeiro ou Falso.

Mas, não deixe a simplicidade te enganar; ele vai economizar muito tempo na validação de informações em seus scripts do PowerShell.

Pense no cmdlet Test-Path do PowerShell como controle de qualidade ao trabalhar com provedores e unidades do PowerShell. Ao escrever um script, você comumente lidará com vários itens contidos nas unidades do PowerShell. Unidades do PowerShell, como C:\, HKLM, Cert, e assim por diante.

Test-Path não funciona com todas as unidades do PowerShell. Se, por exemplo, você tentar usar Test-Path em uma chave de registro, funcionará. Se você tentar usar Test-Path em um valor de registro, ele retornará False todas as vezes.

Se estiver curioso, execute o cmdlet Get-PSDrive agora no PowerShell e observe todas as unidades do PowerShell que aparecem para você.

Todas essas unidades têm caminhos dentro delas, como C:\Windows, HKLM:\Software, etc. Ao trabalhar com caminhos em seus scripts do PowerShell, é sempre uma boa prática primeiro testar se o caminho é válido ou se ele existe ou não. Isso é o que o Test-Path do PowerShell faz.

Test-Path define uma condição que retorna True ou False dependendo se uma condição específica é atendida (normalmente se um arquivo/pasta, chave de registro, certificado ou até mesmo uma variável existe ou não).

Parâmetros e Uso do Test-Path

Como muitos outros cmdlets do PowerShell, o cmdlet Test-Path possui vários parâmetros que alteram seu comportamento. Vamos agora cobrir cada parâmetro e demonstrar como ele funciona e que tipo de resultados você pode esperar ver.

Caminho

O parâmetro Caminho é um parâmetro obrigatório que você usará com cada execução do Test-Path. O parâmetro Caminho define o caminho do PSDrive que você gostaria de testar para verificar a existência.

Se, por exemplo, você gostaria de testar se a pasta C:\Foo existe ou não, você forneceria o caminho apropriado para o parâmetro Caminho. Então, dependendo se C:\Foo realmente existe ou não, Test-Path retornaria True ou False.

PS> Test-Path -Path 'C:\Foo'
True

A mesma técnica pode ser usada para qualquer caminho de item também. Talvez você queira verificar se a chave do registro HKLM:\Software\Foo existe ou não. Basta usar o caminho da chave do registro com o parâmetro Caminho.

PS> Test-Path -Path 'HKLM:\Software\Foo'
True

Saiba que todas as técnicas demonstradas ao longo deste tutorial funcionarão com qualquer caminho de unidade do PowerShell.

Usando Wildcards

O que acontece se você não se importa necessariamente se um caminho tem um valor literal. Em vez disso, você gostaria apenas de verificar se um caminho corresponde a um padrão específico. Nesse caso, você pode usar curingas no valor do Caminho.

Talvez você queira verificar se sua pasta C:\Foo contém alguma subpasta que começa com Bar. Nesse caso, você poderia usar um curinga.

PS> Test-Path -Path 'C:\Foo\Bar*'

Uma vez que você execute o comando acima, Test-Path irá verificar a existência de qualquer pasta que comece com Bar e retornar True ou False dependendo se alguma pasta que corresponda a esse critério existe ou não.

Asteriscos (*) correspondem a um ou mais caracteres, mas você também pode usar pontos de interrogação (?) para ser mais específico e testar apenas um caractere.

Usando o cenário acima como exemplo, se a pasta C:\Foo\Bar1 existe, você pode testar por qualquer subpasta de Foo que comece com Bar e tenha exatamente quatro caracteres usando o comando abaixo.

PS> Test-Path -Path 'C:\Foo\Bar?'

Se, por algum motivo, você deseja usar o parâmetro Path com curingas, mas deseja corresponder literalmente a um caractere curinga como *, você sempre pode escapar os caracteres curinga com um acento grave (`).

LiteralPath

O parâmetro LiteralPath é quase idêntico ao parâmetro Path com uma exceção; ele não permite curingas. Usar o LiteralPath interpretará o valor do caminho literalmente.

Por exemplo, se você tentar usar um asterisco ou ponto de interrogação dentro do valor do caminho usando LIteralPath, o Test-Path irá ignorar completamente os caracteres curinga e testará literalmente por C:\Foo\Bar? como no exemplo abaixo.

PS> Test-Path -LiteralPath 'C:\Foo\Bar?'

Você deve usar LiteralPath como o parâmetro de caminho padrão se não precisar usar caracteres curinga para garantir que o Test-Path teste o caminho que você espera.

PathType

Por padrão, quando você executa Test-Path e fornece um caminho, ele retornará True se encontrar algo nesse caminho. O item com um caminho pode ser um contêiner como uma pasta de arquivo, uma chave de registro, uma loja de certificados e assim por diante, ou uma folha como um arquivo, um valor de registro ou um certificado.

Você pode forçar Test-Path a ser mais detalhado e testar especificamente para um contêiner ou item de folha usando o parâmetro PathType.

Test-Path usa o valor Any para PathType, por padrão.

Se, por exemplo, houver uma pasta em C:\Foo\Bar e você estiver procurando por um arquivo nesse caminho, você poderia usar o parâmetro PathType como mostrado abaixo. Você deseja apenas verificar se existe um arquivo chamado C:\Foo\Bar.

PS> Test-Path -LiteralPath 'C:\Foo\Bar' -PathType Leaf

Talvez, em vez disso, você precise confirmar se C:\Foo\Bar é realmente um arquivo. Nesse caso, você verificará um contêiner.

PS> Test-Path -LiteralPath 'C:\Foo\Bar' -PathType Container

Incluir

Se estiver usando o parâmetro Path e curingas, às vezes será necessário ser mais específico. Nesse caso, você precisa analisar os parâmetros Include e Exclude.

Vamos dizer que você tenha as seguintes pastas:

• C:\Foo\Bar1
• C:\Foo\Bar2
• C:\Foo\Bar3

Você gostaria de verificar se alguma pasta que comece com Bar existe que tenham exatamente quatro caracteres como Bar1, Bar2, etc.

PS> Test-Path -Path C:\Foo\Bar? -PathType Container

O comando acima funciona bem, mas agora você gostaria de encontrar apenas pastas em C:\Foo com o nome de Bar2. Nesse caso, você poderia usar o parâmetro Include.

PS> Test-Path -Path C:\Foo\Bar? -PathType Container -Include 'Bar2'

O comando acima agora testa essencialmente apenas uma pasta `C:\Foo\Bar2`. Provavelmente, você estará melhor apenas usando `Test-Path -Path ‘C:\Foo\Bar2’ -PathType Container` em vez disso.

Excluir

O parâmetro `Exclude` funciona de forma semelhante ao parâmetro `Include`, exceto que desta vez ele exclui caminhos que correspondem a uma string.

Talvez você queira garantir que haja pelo menos um arquivo dentro da pasta `C:\Foo`, e você pode usar o seguinte comando:

PS> Test-Path -Path C:\Foo\* -PathType Leaf

O comando acima retorna `True` ou `False` se houver arquivos em C:\Foo. Mas talvez você queira garantir que existam arquivos além dos que têm a extensão de arquivo `txt`. Nesse caso, você poderia usar o parâmetro `Exclude` usando um wildcard para excluir todos os arquivos com a extensão `txt` dos testes.

PS> Test-Path -Path C:\Foo\* -PathType Leaf -Exclude *.txt

Filtro

De acordo com a documentação da Microsoft, o parâmetro `Filter` “especifica um filtro no formato ou idioma do provedor. O valor deste parâmetro qualifica como o parâmetro `Path`. A sintaxe do filtro, incluindo o uso de caracteres curinga, depende do provedor”.

Embora o parâmetro `Filter` deva ser usado com outros cmdlets como `Get-Childitem`, por exemplo, raramente, se é que alguma vez, é usado com `Test-Path`. Se você encontrou um bom uso para o parâmetro `Filter`, entre em contato pelo Twitter em @adbertram.

Relacionado: Get-ChildItem: Listando Arquivos, Registro, Certificados e Mais em um Único Comando

NewerThan

Você já precisou verificar o carimbo de data e hora de um arquivo e tomar uma decisão com base nisso? Se sim, os parâmetros NewerThan e OlderThan economizam muito código. O parâmetro NewerThan verifica se o carimbo de data e hora de um item é mais recente do que uma data específica.

O parâmetro NewerThan aceita uma string ou um objeto DateTime para representar um carimbo de data e hora a ser verificado. Por exemplo, para verificar se o arquivo C:\Foo\bar.txt foi criado após 20 de janeiro de 2021, você executaria o comando Test-Path como abaixo.

Test-Path -LiteralPath 'C:\Foo\bar.txt' -NewerThan 'January 20, 2021'
## ou
Test-Path -LiteralPath 'C:\Foo\bar.txt' -NewerThan '1/20/21'

OlderThan

O parâmetro OlderThan é exatamente o mesmo que o parâmetro NewerThan, mas oposto. Este parâmetro verifica se um item é mais antigo do que uma data específica.

Test-Path -LiteralPath 'C:\Foo\bar.txt' -OlderThan 'January 20, 2021'
## ou
Test-Path -LiteralPath 'C:\Foo\bar.txt' -OlderThan '1/20/21'

IsValid

Se você já construiu dinamicamente um caminho em um script, sabe das dificuldades. Às vezes, você pode errar ao digitar uma tecla ou de alguma forma inserir algum caractere especial em um caminho; se for o caso, o parâmetro IsValid é para você.

O parâmetro IsValid é um parâmetro único que transforma Test-Path, não em um cmdlet que verifica a existência de um item, mas em um que verifica a sintaxe do caminho. Este parâmetro confirma se um caminho é válido apenas.

Por exemplo, talvez você precise verificar se um caminho é sintaticamente válido. Você está trabalhando com algumas variáveis e as concatena para construir um caminho.

Ao concatenar caminhos, sempre use o cmdlet Join-Path. Isso é apenas para fins de exemplo!

$someVar = 'abc:dff'
$rootPath = 'C:\'
$path = "$someVar$rootPath

Agora, para garantir que o caminho que você criou dinamicamente seja válido, use o parâmetro IsValid como abaixo. Você verá que Test-Path retorna False.

PS> Test-Path -LiteralPath $path -IsValid
False

O caminho abc:dffC:\ não é um caminho válido, permitindo que você crie uma rotina de validação a partir dessa situação.

Se você estiver usando o PowerShell v6.1.2 ou anterior e estiver usando os parâmetros IsValid e PathType juntos, Test-Path ignorará o parâmetro PathType.

Credencial

Mesmo que você encontre o parâmetro Credential em Test-Path, você pode pensar que pode usá-lo para autenticar nos drives do PS como outro usuário. Essa é uma suposição válida, mas está errada.

Infelizmente, o parâmetro Credential não faz muito com o cmdlet Test-Path. A Microsoft recomenda usar o cmdlet Invoke-Command e usar o parâmetro Credential lá se você quiser invocar Test-Path com credenciais alternativas.

Invoke-Command -Credential (Get-Credential) -Scriptblock {Test-Path -LiteralPath 'C:\'}

Relacionado: Invoke-Command: A Melhor Maneira de Executar Código Remoto