Test-Path
Determina se todos os elementos de um caminho existem.
Sintaxe
Path (Default)
Test-Path
[-Path] <String[]>
[-Filter <String>]
[-Include <String[]>]
[-Exclude <String[]>]
[-PathType <TestPathType>]
[-IsValid]
[-Credential <PSCredential>]
[-UseTransaction]
[-OlderThan <DateTime>]
[-NewerThan <DateTime>]
[<CommonParameters>]
LiteralPath
Test-Path
-LiteralPath <String[]>
[-Filter <String>]
[-Include <String[]>]
[-Exclude <String[]>]
[-PathType <TestPathType>]
[-IsValid]
[-Credential <PSCredential>]
[-UseTransaction]
[-OlderThan <DateTime>]
[-NewerThan <DateTime>]
[<CommonParameters>]
Description
O cmdlet Test-Path 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 elemento terminal ou folha.
Se o Path for espaço em branco, $False será retornado.
Se o Path for uma cadeia de caracteres vazia, $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 diretório C:, o diretório Documentos e Configurações e o diretório DavidC.
Caso algum esteja 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, ele é colocado entre aspas. O asterisco no final do caminho indica o conteúdo do diretório do Edifício Comercial. 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 Excluir 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 variável $profile leva a um arquivo.
Nesse caso, como o perfil do PowerShell é um arquivo .ps1, 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 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
Este 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 do sistema de arquivos.
Test-Path $pshome\PowerShell.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 não terminante.
Ele pode ser suprimido usando -ErrorAction SilentlyContinue.
O exemplo a seguir mostra todos os casos que retornam o erro NullPathNotPermitted.
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 um espaço em branco é ou uma cadeia de caracteres vazia fornecida para o parâmetro -Path, ele retorna false.
O exemplo a seguir mostra o espaço em branco e a cadeia de caracteres vazia.
Test-Path ' '
Test-Path ''
False
Test-Path : Cannot bind argument to parameter 'Path' because it is an empty string.
At line:1 char:11
+ Test-Path ''
+ ~~
+ CategoryInfo : InvalidData: (:) [Test-Path], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,Microsoft.PowerShell.Commands.TestPathCommand
Parâmetros
-Credential
Observação
Esse parâmetro não tem suporte para nenhum provedor instalado com o PowerShell. Para executar este cmdlet em nome de outro usuário ou elevar suas credenciais, use Invoke-Command.
Propriedades do parâmetro
| Tipo: | PSCredential |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-Exclude
Especifica os itens que esse cmdlet omite. O valor desse parâmetro qualifica o parâmetro Path. Insira um elemento ou padrão de caminho, como "*.txt". Caracteres curinga são permitidos.
Propriedades do parâmetro
| Tipo: | String[] |
| Valor padrão: | None |
| Dá suporte a curingas: | True |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Filter
Especifica um filtro no formato ou idioma do provedor. O valor desse 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 o PowerShell filtrar os objetos depois que eles são recuperados.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | True |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Include
Especifica os caminhos que esse cmdlet testa. O valor desse parâmetro qualifica o parâmetro Path. Insira um elemento ou padrão de caminho, como "*.txt". Caracteres curinga são permitidos.
Propriedades do parâmetro
| Tipo: | String[] |
| Valor padrão: | None |
| Dá suporte a curingas: | True |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-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.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-LiteralPath
Especifica um caminho a ser testado. Ao contrário do caminho , o valor do parâmetro LiteralPath é usado exatamente como ele é digitado. Nenhum caractere é interpretado como caractere curinga. Se o caminho incluir caracteres de escape, coloque-o entre aspas simples. Aspas simples indicam ao PowerShell que não deve interpretar nenhum caractere como uma sequência de escape.
Propriedades do parâmetro
| Tipo: | String[] |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | PSPath |
Conjuntos de parâmetros
LiteralPath
| Cargo: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-NewerThan
Especifique uma hora como um objeto DateTime.
Propriedades do parâmetro
| Tipo: | DateTime |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-OlderThan
Especifique uma hora como um objeto DateTime.
Propriedades do parâmetro
| Tipo: | DateTime |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Path
Especifica um caminho a ser testado. Caracteres curinga são permitidos. Se o caminho incluir espaços, coloque-os entre aspas.
Propriedades do parâmetro
| Tipo: | String[] |
| Valor padrão: | None |
| Dá suporte a curingas: | True |
| DontShow: | False |
Conjuntos de parâmetros
Path
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-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 estiver.
Os valores aceitáveis para este 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. Um contêiner ou uma folha.
Informa se o elemento final no caminho é de um tipo específico.
Cuidado
Até o PowerShell versão 6.1.2, quando as opções IsValid e PathType são especificadas juntas, o cmdlet Test-Path ignora a opção PathType e valida apenas o caminho sintactico sem validar o tipo de caminho.
De acordo com problema nº 8607, corrigir esse comportamento pode ser uma alteração significativa 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.
Propriedades do parâmetro
| Tipo: | TestPathType |
| Valor padrão: | None |
| Valores aceitos: | Any, Container, Leaf |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | Tipo |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseTransaction
Inclui o comando na transação ativa. Esse parâmetro só é válido quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | usetx |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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
String
Você pode redirecionar uma cadeia de caracteres que contém um caminho, mas não um caminho literal, para este cmdlet.
Saídas
Boolean
O cmdlet retorna um valor booleano de .
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 são projetados para uso em programas e scripts em que você deseja exibir todo ou parte de um nome de caminho em um formato específico. Use-os como você usaria Dirname, Normpath, Realpath, Joinou outros manipuladores de caminho.
O Test-Path foi projetado para trabalhar com os dados expostos por qualquer provedor.
Para listar os provedores disponíveis na sessão, digite Get-PSProvider.
Para obter mais informações, consulte about_Providers.