Test-Path
Determina se todos os elementos de um caminho existem ou não.
Syntax
Test-Path
[-Path] <String[]>
[-Filter <String>]
[-Include <String[]>]
[-Exclude <String[]>]
[-PathType <TestPathType>]
[-IsValid]
[-Credential <PSCredential>]
[-OlderThan <DateTime>]
[-NewerThan <DateTime>]
[<CommonParameters>]
Test-Path
-LiteralPath <String[]>
[-Filter <String>]
[-Include <String[]>]
[-Exclude <String[]>]
[-PathType <TestPathType>]
[-IsValid]
[-Credential <PSCredential>]
[-OlderThan <DateTime>]
[-NewerThan <DateTime>]
[<CommonParameters>]
Description
O Test-Path
cmdlet determina se todos os elementos do caminho existem. Ele retornará $True
se todos os elementos existirem e $False
se houver algum ausente. Ele também pode dizer se a sintaxe do caminho é válida e se o caminho leva a um contêiner ou a um terminal ou elemento folha. Se o Caminho for um espaço em branco ou uma cadeia de caracteres vazia, será $False
retornado. Se o Caminho for $null
, matriz de $null
ou matriz vazia, um erro de não terminação será retornado.
Exemplos
Exemplo 1: Testar um caminho
Test-Path -Path "C:\Documents and Settings\DavidC"
True
Esse comando verifica se todos os elementos no caminho existem, ou seja, o C:
diretório, o Documents and Settings
diretório e o DavidC
diretório. Se houver algum ausente, o cmdlet retornará $False
. Caso contrário, ele retornará $True
.
Exemplo 2: Testar o caminho de um perfil
Test-Path -Path $profile
False
Test-Path -Path $profile -IsValid
True
Esses comandos testam o caminho do perfil do PowerShell.
O primeiro comando determina se todos os elementos no caminho existem. O segundo comando determina se a sintaxe do caminho está correta. Nesse caso, o caminho é $False
, mas a sintaxe está correta $True
. Esses comandos usam $profile
, a variável automática que aponta para o local do perfil, mesmo que o perfil não exista.
Para obter mais informações sobre variáveis automáticas, consulte about_Automatic_Variables.
Exemplo 3: verificar se há arquivos além de um tipo especificado
Test-Path -Path "C:\CAD\Commercial Buildings\*" -Exclude *.dwg
False
Esse comando verifica se há arquivos no diretório Edifícios Comerciais que não sejam arquivos de .dwg.
O comando usa o parâmetro Path para especificar o caminho. Como o caminho inclui um espaço, o caminho é colocado entre aspas. O asterisco no final do caminho indica o conteúdo do diretório Prédios comerciais. Com caminhos longos, como este, digite as primeiras letras do caminho e use a tecla TAB para concluir o caminho.
O comando especifica o parâmetro Exclude para especificar arquivos que serão omitidos da avaliação.
Nesse caso, como o diretório contém apenas arquivos .dwg, o resultado é $False
.
Exemplo 4: verificar se há um arquivo
Test-Path -Path $profile -PathType leaf
True
Esse comando verifica se o caminho armazenado na $profile
variável leva a um arquivo. Nesse caso, como o perfil do PowerShell é um .ps1
arquivo, o cmdlet retorna $True
.
Exemplo 5: verificar caminhos no Registro
Esses comandos usam Test-Path
com o provedor de registro do PowerShell.
O primeiro comando testa se o caminho do Registro da chave do Registro do Microsoft.PowerShell está correto no sistema. Se o PowerShell estiver instalado corretamente, o cmdlet retornará $True
.
Importante
Test-Path
não funciona corretamente com todos os provedores do PowerShell. Por exemplo, você pode usar Test-Path
para testar o caminho de uma chave do Registro, mas se usá-la para testar o caminho de uma entrada do Registro, ela sempre retornará $False
, mesmo que a entrada do Registro esteja presente.
Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell"
True
Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy"
False
Exemplo 6: testar se um arquivo é mais recente que uma data especificada
Esse comando usa o parâmetro dinâmico NewerThan para determinar se o arquivo "PowerShell.exe" no computador é mais recente que "13 de julho de 2009".
O parâmetro NewerThan funciona apenas em unidades de sistema de arquivos.
Test-Path $pshome\pwsh.exe -NewerThan "July 13, 2009"
True
Exemplo 7: Testar um caminho com nulo como o valor
O erro retornado para null
, matriz de null
ou matriz vazia é um erro de não encerramento. Ele pode ser suprimido usando -ErrorAction SilentlyContinue
. O exemplo a seguir mostra todos os casos que retornam o NullPathNotPermitted
erro.
Test-Path $null
Test-Path $null, $null
Test-Path @()
Test-Path : Cannot bind argument to parameter 'Path' because it is null.
At line:1 char:11
+ Test-Path $null
+ ~~~~~
+ CategoryInfo : InvalidData: (:) [Test-Path], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.TestPathCommand
Exemplo 8: Testar um caminho com espaço em branco como o valor
Quando uma cadeia de caracteres de espaço em branco é fornecida para o parâmetro Path , ela retorna False. Essa é uma alteração de Windows PowerShell 5.1. Quando uma cadeia de caracteres vazia é fornecida, Test-Path
retorna um erro.
O exemplo a seguir mostra o espaço em branco e a cadeia de caracteres vazia.
Test-Path ' '
Test-Path ''
False
False
Parâmetros
-Credential
Observação
Não há suporte para esse parâmetro em nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar esse cmdlet, use Invoke-Command.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Exclude
Especifica os itens que este cmdlet omite. O valor deste parâmetro qualifica o parâmetro Path. Insira um padrão ou elemento de caminho, como "*.txt". Caracteres curinga são permitidos.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-Filter
Especifica um filtro no formato ou idioma do provedor. O valor deste parâmetro qualifica o parâmetro Path. A sintaxe do filtro, incluindo o uso de caracteres curinga, depende do provedor. Os filtros são mais eficientes do que outros parâmetros, pois o provedor os aplica quando recupera os objetos em vez de fazer com que o PowerShell filtre os objetos depois que eles são recuperados.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-Include
Especifica os caminhos que este cmdlet testa. O valor deste parâmetro qualifica o parâmetro Path. Insira um padrão ou elemento de caminho, como "*.txt". Caracteres curinga são permitidos.
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-IsValid
Indica que esse cmdlet testa a sintaxe do caminho, independentemente de os elementos do caminho existirem. Esse cmdlet retornará $True
se a sintaxe do caminho for válida e $False
se não for.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LiteralPath
Especifica um caminho a ser testado. Ao contrário de Path, o valor do parâmetro LiteralPath é usado exatamente como foi digitado. Nenhum caractere é interpretado como caractere curinga. Se o caminho incluir caracteres que podem ser interpretados pelo PowerShell como sequências de escape, você deverá colocar o caminho entre aspas simples para que eles não sejam interpretados.
Type: | String[] |
Aliases: | PSPath, LP |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NewerThan
Especifique uma hora como um objeto DateTime .
Type: | Nullable<T>[DateTime] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OlderThan
Especifique uma hora como um objeto DateTime .
Type: | Nullable<T>[DateTime] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
Especifica um caminho a ser testado. Caracteres curinga são permitidos. Se o caminho incluir espaços, coloque-os entre aspas.
Type: | String[] |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | True |
-PathType
Especifica o tipo do elemento final no caminho. Esse cmdlet retornará $True
se o elemento for do tipo especificado e $False
se não for. Os valores aceitáveis para esse parâmetro são:
- Contêiner. Um elemento que contém outros elementos, como um diretório ou chave do registro.
- Folha. Um elemento que não contém outros elementos, como um arquivo.
- Qualquer um. Pode ser tanto um contêiner quanto uma folha.
Indica se o elemento final no caminho é ou não de um tipo específico.
Cuidado
Até a versão 6.1.2 do PowerShell, quando as opções IsValid e PathType são especificadas juntas, o Test-Path
cmdlet ignora a opção PathType e valida apenas o caminho sintático sem validar o tipo de caminho.
De acordo com o problema nº 8607, corrigir esse comportamento pode ser uma alteração interruptiva em uma versão futura, em que as opções IsValid e PathType pertencem a conjuntos de parâmetros separados e, portanto, não podem ser usados juntos evitando essa confusão.
Type: | TestPathType |
Aliases: | Type |
Accepted values: | Any, Container, Leaf |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Entradas
Você pode redirecionar uma cadeia de caracteres que contém um caminho, mas não um caminho literal, para esse cmdlet.
Saídas
O cmdlet retorna um valor booliano .
Observações
Os cmdlets que contêm o substantivo Path (os cmdlets Path ) funcionam com nomes de caminho e retornam os nomes em um formato conciso que todos os provedores do PowerShell podem interpretar. Eles foram projetados para uso em programas e scripts onde você deseja exibir uma parte ou todo um nome de caminho em um formato específico. Use-os como você usaria Dirname, Normpath, Realpath, Join ou outros manipuladores de caminho.
O Test-Path
foi projetado para funcionar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis em sua sessão, digite Get-PSProvider
. Para obter mais informações, consulte about_Providers.