Test-Path

Módulo:

Microsoft.PowerShell.Management Module

Determina se todos os elementos de um caminho existem.

Sintaxe

Path (Default) - FileSystem provider

Test-Path
    [-Path] <String[]>
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <PSCredential>]
    [-OlderThan <DateTime>]
    [-NewerThan <DateTime>]
    [<CommonParameters>]

LiteralPath - FileSystem provider

Test-Path
    -LiteralPath <String[]>
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <PSCredential>]
    [-OlderThan <DateTime>]
    [-NewerThan <DateTime>]
    [<CommonParameters>]

Path (Default) - All providers

Test-Path
    [-Path] <string[]>
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <pscredential>]
    [<CommonParameters>]

LiteralPath - All providers

Test-Path
    -LiteralPath <string[]>
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-PathType <TestPathType>]
    [-IsValid]
    [-Credential <pscredential>]
    [<CommonParameters>]

Description

O cmdlet Test-Path 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 elemento terminal ou folha. Se o Path for um espaço em branco ou uma cadeia de caracteres vazia, o cmdlet retornará $false. Se o Caminho do for $null, uma matriz de $null ou uma matriz vazia, o cmdlet retornará um erro não terminativo.

Exemplos

Exemplo 1: Testar um caminho

Test-Path -Path "C:\Documents and Settings\DavidC"

True

Este comando verifica se todos os elementos no caminho existem, incluindo o diretório C:, o diretório Documents and Settings e o diretório DavidC. Se algum estiver faltando, o cmdlet retornará $false. Caso contrário, ele retorna $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. Neste 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 existem ficheiros para 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 Commercial Buildings diferente 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 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 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 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 Registo

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 você usá-lo para testar o caminho de uma entrada do Registro, ele 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

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

O parâmetro NewerThan funciona apenas em unidades do sistema de arquivos.

Test-Path $pshome\pwsh.exe -NewerThan "July 13, 2009"

True

Exemplo 7: Testar um caminho com null como o valor

O erro retornado para null, matriz de null ou matriz vazia é um erro que não termina. 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 valor

Quando uma cadeia de caracteres de espaço em branco é fornecida para o parâmetro Path, ela retorna $false. Esta é uma alteração do Windows PowerShell 5.1. Quando uma cadeia de caracteres vazia é fornecida, Test-Path retorna um erro. O exemplo a seguir mostra espaço em branco e cadeia de caracteres vazia.

Test-Path ' '
Test-Path ''

False
False

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

Quando se testa um caminho que inclui uma especificação de drive, o teste da validade do caminho falhará se o drive 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 é suportado por nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar esse cmdlet, use Invoke-Command.

Propriedades dos parâmetros

Tipo:	PSCredential
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-Exclude

Especifica os itens que este cmdlet omite. O valor desse parâmetro qualifica o parâmetro Path. Insira um elemento ou padrão de caminho, como *.txt. Caracteres coringa são permitidos.

Propriedades dos parâmetros

Tipo:	String[]
Default value:	None
Suporta carateres universais:	True
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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, porque 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.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	True
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Include

Especifica os caminhos que este cmdlet testa. O valor desse parâmetro qualifica o parâmetro Path. Insira um elemento ou padrão de caminho, como *.txt. Caracteres coringa são permitidos.

Propriedades dos parâmetros

Tipo:	String[]
Default value:	None
Suporta carateres universais:	True
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-IsValid

Indica que esse cmdlet testa a sintaxe do caminho, independentemente de os elementos do caminho existirem. Este cmdlet retorna $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.

Observação

Uma alteração significativa nas APIs de caminho foi introduzida no .NET 2.1. Esses métodos não verificam mais se há caracteres de caminho inválidos. Essa alteração causou uma regressão no PowerShell, onde a verificação IsValid não testa mais caracteres inválidos. A regressão será abordada em uma versão futura. Para obter mais informações, consulte Alterações significativas no .NET Core 2.1.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-LiteralPath

Especifica um caminho a ser testado. Ao contrário de Path, o valor do parâmetro LiteralPath é usado exatamente como foi escrito. Nenhum caractere é interpretado como um 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.

Propriedades dos parâmetros

Tipo:	String[]
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	PSPath, LP

Conjuntos de parâmetros

LiteralPath

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-NewerThan

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

Especifique uma hora como um objeto DateTime .

Antes do PowerShell 7.5, o cmdlet ignora:

• Este parâmetro quando você especifica PathType como qualquer valor diferente de Any.
• O parâmetro OlderThan quando usado com este parâmetro.
• Este 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 para testar a idade dos diretórios.

Para obter mais informações, consulte about_FileSystem_Provider.

Propriedades dos parâmetros

Tipo:	Nullable<T>[[DateTime]]
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-OlderThan

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

Especifique uma hora como um objeto DateTime .

Antes do PowerShell 7.5, o cmdlet ignora:

• Este parâmetro quando você especifica PathType como qualquer valor diferente de Any.
• Quando este parâmetro é usado com o parâmetro NewerThan.
• Este 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 para testar a idade dos diretórios.

Para obter mais informações, consulte about_FileSystem_Provider.

Propriedades dos parâmetros

Tipo:	Nullable<T>[[DateTime]]
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Path

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

Propriedades dos parâmetros

Tipo:	String[]
Default value:	None
Suporta carateres universais:	True
NãoMostrar:	False

Conjuntos de parâmetros

Path

Position:	0
Obrigatório:	True
Valor do pipeline:	True
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-PathType

Especifica o tipo do elemento final no caminho. Este cmdlet retorna $true se o elemento for do tipo especificado e $false se não for. Os valores aceitáveis para este parâmetro são:

• Container - Um elemento que contém outros elementos, como um diretório ou chave do Registro.
• Leaf - Um elemento que não contém outros elementos, como um arquivo.
• Any - Um recipiente ou uma folha.

Informa se o elemento final no caminho é de um tipo específico.

Atenção

Até a versão 6.1.2 do PowerShell, quando as opções IsValid e PathType são especificadas juntas, o cmdlet Test-Path ignora a opção PathType e só valida 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 numa versão futura, onde os switches IsValid e PathType pertencem a conjuntos de parâmetros separados e, portanto, não podem ser usados em conjunto, evitando assim essa confusão.

Propriedades dos parâmetros

Tipo:	TestPathType
Default value:	None
Valores aceites:	Any, Container, Leaf
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Tipo

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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 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 booleano .

Notas

Os cmdlets que contêm o substantivo Path (os cmdlets Path) trabalham 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 onde você deseja exibir todo ou parte de um caminho em um formato específico. Use-os como você usaria Dirname, Normpath, Realpath, Joinou outros manipuladores de caminho.

O Test-Path é projetado para trabalhar 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.

Ligações Relacionadas

• Convert-Path
• Join-Path
• Resolve-Path
• Split-Path