Compartilhar via

Test-Path

  • Referência
Módulo:
Microsoft.PowerShell.Management

Determina se todos os elementos de um caminho existem.

Sintaxe

Test-Path
    [-Path] <String[]>
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <PSCredential>]
    [-UseTransaction]
    [-OlderThan <DateTime>]
    [-NewerThan <DateTime>]
    [<CommonParameters>]
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. 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 está 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 do Microsoft.PowerShell chave do Registro 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 de não terminação. 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

Nota

Esse parâmetro não tem suporte para nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar esse cmdlet, use Invoke-Command.

Tipo:PSCredential
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:True

-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.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-LiteralPath

Especifica um caminho a ser testado. Ao contrário docaminho , 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. As aspas simples dizem ao PowerShell para não interpretar nenhum caractere como sequências de escape.

Tipo:String[]
Aliases:PSPath
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-NewerThan

Especifique uma hora como um objeto DateTime .

Tipo:DateTime
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-OlderThan

Especifique uma hora como um objeto DateTime .

Tipo:DateTime
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Path

Especifica um caminho a ser testado. Caracteres curinga são permitidos. Se o caminho incluir espaços, coloque-o entre aspas.

Tipo:String[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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 estiver. Os valores aceitáveis para este parâmetro são:

  • Recipiente. 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 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.

Tipo:TestPathType
Aliases:Type
Valores aceitos:Any, Container, Leaf
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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

Tipo:SwitchParameter
Aliases:usetx
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

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 de 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 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.