Compartilhar via

Test-Path

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

Determina se todos os elementos de um caminho existem ou não.

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>]
Test-Path
    [-Path] <string[]>
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <pscredential>]
    [-UseTransaction]
    [<CommonParameters>]
Test-Path
    -LiteralPath <string[]>
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <pscredential>]
    [-UseTransaction]
    [<CommonParameters>]

Description

O Test-Path cmdlet determina se todos os elementos do caminho existem. Ele retorna $true se todos os elementos existirem e $false se algum estiver faltando. 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 Path for um espaço em branco ou uma cadeia de caracteres vazia, o cmdlet retornará $false. Se o Path for $null, uma matriz de $null ou uma matriz vazia, o cmdlet retornará um erro de não encerramento.

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, incluindo o C: diretório, o Documents and Settings diretório e o DavidC diretório. Se algum estiver faltando, 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: Verifique se há algum arquivo além de um tipo especificado

Test-Path -Path "C:\CAD\Commercial Buildings\*" -Exclude *.dwg

False

Este comando verifica se há algum arquivo no diretório Edifícios comerciais além de .dwg arquivos.

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 os arquivos a serem omitidos da avaliação.

Nesse caso, como o diretório contém apenas .dwg arquivos, o resultado é $false.

Exemplo 4: Verificar se há um arquivo

Test-Path -Path $profile -PathType leaf

True

Este comando verifica se o $profile caminho armazenado na 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 são usados 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 do que uma data especificada

Esse comando usa o parâmetro dinâmico NewerThan para determinar se o PowerShell.exe arquivo no computador é mais recente que July 13, 2009o .

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 null como o valor

O erro retornado para null, array de null ou empty array é um erro não finalizado. 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 $true. Quando uma cadeia de caracteres vazia é fornecida, Test-Path retorna um erro. O exemplo a seguir mostra espaços em branco e cadeia de caracteres vazia.

Test-Path ' '
Test-Path ''

True
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

Exemplo 9: Testar um caminho que pode ter uma unidade inválida

Quando você testa um caminho que inclui uma especificação de unidade, o teste da validade do caminho falhará se a unidade não existir. Você pode prefixar a unidade com o nome do provedor para contornar esse problema.

Test-Path -IsValid Z:\abc.txt
Test-Path -IsValid FileSystem::Z:\abc.txt

False
True

Parâmetros

-Credential

Observação

Esse parâmetro não tem suporte de 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 com que o PowerShell filtre 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. Se o caminho que está sendo testado incluir uma especificação de unidade, o cmdlet retornará false quando a unidade não existir. O PowerShell retorna false porque não sabe qual provedor de unidade testar.

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 de Path, o valor do parâmetro LiteralPath é usado exatamente como é digitado. Nenhum caractere é interpretado como caractere curinga. Se o caminho incluir caracteres que possam ser interpretados pelo PowerShell como sequências de escape, você deverá colocar o caminho entre aspas simples para que eles não sejam interpretados.

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

-NewerThan

Esse é um parâmetro dinâmico disponibilizado pelo provedor FileSystem.

Especifique uma hora como um objeto DateTime .

Antes do PowerShell 7.5, o cmdlet ignora:

  • Esse parâmetro quando você especifica PathType como qualquer valor diferente de Any.
  • O parâmetro OlderThan quando usado com esse parâmetro.
  • Esse parâmetro quando Path aponta para um diretório.

A partir do PowerShell 7.5, você pode usar esse parâmetro com qualquer valor para o parâmetro PathType , para testar um intervalo de datas com o parâmetro OlderThan e testar a idade dos diretórios.

Para obter mais informações, consulte about_FileSystem_Provider.

Tipo:Nullable<T>[[DateTime]]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-OlderThan

Esse é um parâmetro dinâmico disponibilizado pelo provedor FileSystem.

Especifique uma hora como um objeto DateTime .

Antes do PowerShell 7.5, o cmdlet ignora:

  • Esse parâmetro quando você especifica PathType como qualquer valor diferente de Any.
  • Esse parâmetro quando usado com o parâmetro NewerThan .
  • Esse parâmetro quando Path aponta para um diretório.

A partir do PowerShell 7.5, você pode usar esse parâmetro com qualquer valor para o parâmetro PathType , para testar um intervalo de datas com o parâmetro NewerThan e testar a idade dos diretórios.

Para obter mais informações, consulte about_FileSystem_Provider.

Tipo:Nullable<T>[[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-os 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 for. Os valores aceitáveis para esse parâmetro são:

  • Container - Um elemento que contém outros elementos, como um diretório ou uma chave do Registro.
  • Leaf - Um elemento que não contém outros elementos, como um arquivo.
  • Any - Um recipiente ou 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 #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 usadas juntas para evitar 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. Este parâmetro é válido somente 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 canalizar uma cadeia de caracteres que contém um caminho, mas não um caminho literal, para esse cmdlet.

Saídas

Boolean

O cmdlet retorna um valor booliano .

Observações

Os cmdlets que contêm o substantivo Path (os cmdlets Path ) funcionam com path 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 caminho em um formato específico. Use-os como 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.