Se você precisa validar um caminho para um arquivo, chave do registro, certificado ou qualquer outro caminho de unidade do PowerShell, você precisa do cmdlet Test-Path.
O cmdlet Test-Path é uma maneira simples, porém ú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 correto ou até mesmo se um item é mais recente ou mais antigo do que um tempo específico.
Neste tutorial, você aprenderá tudo sobre o cmdlet Test-Path do PowerShell e como utilizá-lo para melhorar seus scripts do PowerShell.
Pré-requisitos
Se você deseja acompanhar os exemplos deste tutorial, você vai precisar de uma coisa: o PowerShell. Mais especificamente, o tutorial utilizará o PowerShell v7.03 no Windows 10, embora muitas das técnicas que você aprenderá se apliquem também a versões mais antigas.
O que o cmdlet Test-Path faz?
O cmdlet Test-Path do PowerShell é um dos comandos mais simples disponíveis. É um comando que existe desde o início do PowerShell e retorna apenas dois valores: Verdadeiro ou Falso.
No entanto, não se deixe enganar pela simplicidade; ele economizará tanto tempo na validação de informações nos 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 trabalhará com vários itens contidos em unidades do PowerShell. Unidades do PowerShell como C:\, HKLM, Cert, e assim por diante.
Test-Pathnão funciona com todas as unidades do PS. Se, por exemplo, você tentar usarTest-Pathcontra uma chave de registro, ele funcionará. Se você tentar usarTest-Pathcontra um valor de registro, ele retornaráFalsotodas as vezes.
Se você está curioso, execute o cmdlet Get-PSDrive agora mesmo no PowerShell e observe todas as unidades do PS que aparecem para você.
Todas essas unidades têm caminhos dentro delas como C:\Windows, HKLM:\Software, etc. Ao trabalhar com caminhos dentro de seus scripts do PowerShell, é sempre uma boa prática primeiro testar se o caminho é válido ou se existe ou não. Isso é o que o Test-Path do PowerShell faz.
Test-Path define uma condição que retorna Verdadeiro ou Falso dependendo se uma condição específica é atendida (tipicamente 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
Assim como muitos outros cmdlets do PowerShell, o cmdlet Test-Path possui vários parâmetros que alteram seu comportamento. Vamos agora abordar cada parâmetro e demonstrar como ele funciona e que tipo de resultados você pode esperar ver.
Path
O parâmetro Path é um parâmetro obrigatório que você usará com cada execução do Test-Path. O parâmetro Path define o caminho do PSDrive que você deseja testar para saber se ele existe.
Por exemplo, se você deseja testar se a pasta C:\Foo existe ou não, você forneceria o caminho apropriado para o parâmetro Path. Então, dependendo se C:\Foo realmente existe ou não, o Test-Path retornaria True ou False.
A mesma técnica pode ser usada para qualquer caminho de item também. Talvez você queira testar se a chave do registro HKLM:\Software\Foo existe ou não. Basta usar o caminho da chave do registro com o parâmetro Path.
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 importar necessariamente se um caminho tem um valor literal. Em vez disso, você só gostaria de verificar se um caminho corresponde a um padrão específico. Nesse caso, você pode usar wildcards no valor do Path.
Talvez você queira verificar se sua pasta C:\Foo contém alguma subpasta que comece com Bar. Nesse caso, você poderia usar um wildcard.
Uma vez que você execute o comando acima, Test-Path 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 um único caractere.
Usando o cenário acima como exemplo, se a pasta C:\Foo\Bar1 existir, você poderá testar qualquer subpasta de Foo que comece com Bar e tenha exatamente quatro caracteres usando o comando abaixo.
Se, por algum motivo, você quiser usar o parâmetro
Pathcom caracteres curinga, mas quiser corresponder literalmente a um caractere curinga como*, você sempre pode escapar dos 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 caracteres curinga. 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, Test-Path ignorará completamente os caracteres curinga e testará literalmente para C:\Foo\Bar? como no exemplo abaixo.
Você deve usar
LiteralPathcomo o parâmetro de caminho padrão se não precisar usar caracteres curinga para garantir queTest-Pathteste o caminho que você está esperando.
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, um repositório 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 se tornar mais granular e testar especificamente para um contêiner ou item de folha usando o parâmetro PathType.
Test-Path usa o valor de
PathTypeAny, 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 conforme mostrado abaixo. Você quer apenas verificar se existe um arquivo chamado C:\Foo\Bar.
Talvez, em vez disso, você precise confirmar se C:\Foo\Bar é realmente um arquivo. Nesse caso, você verificará se é um contêiner.
Incluir
Se estiver usando o parâmetro Path e curingas, às vezes será necessário ser mais específico. Nesse caso, você precisa examinar 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 existe alguma pasta que comece com Bar e que tenha exatamente quatro caracteres, como Bar1, Bar2, etc.
O comando acima funciona bem, mas agora você gostaria de encontrar apenas pastas em C:\Foo chamadas Bar2. Nesse caso, você poderia usar o parâmetro Include.
O comando acima agora testa essencialmente apenas uma única pasta C:\Foo\Bar2. Provavelmente, você estará melhor usando apenas 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ê usa o seguinte comando:
O comando acima retorna True ou False se houver algum arquivo em C:\Foo. Mas talvez você queira garantir que existam quaisquer arquivos exceto aqueles com uma extensão de arquivo txt. Nesse caso, você poderia usar o parâmetro Exclude usando um caractere curinga para excluir todos os arquivos com a extensão txt do teste.
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 se 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, ele raramente é, se alguma vez, usado com Test-Path. Se você encontrou um bom uso para o parâmetro Filter, por favor, entre em contato pelo Twitter em @adbertram.
Relacionado: Get-ChildItem: Listando Arquivos, Registro, Certificado e Mais como Um
NewerThan
Você já precisou verificar o carimbo de data/hora em 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/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/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 Test-Path como abaixo.
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.
IsValid
Se você já construiu dinamicamente um caminho em um script, conhece a luta. Às vezes, você pode digitar errado 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 o 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!
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.
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
IsValidePathTypejuntos,Test-Pathignorará o parâmetroPathType.
Credencial
Mesmo que você encontre o parâmetro Credential em Test-Path, pode pensar que pode usá-lo para autenticar unidades PS como outro usuário. Essa é uma suposição válida, mas está incorreta.
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 quiser invocar Test-Path com credenciais alternativas.
Relacionado: Invoke-Command: A Melhor Maneira de Executar Código Remoto