about_Command_Precedence

Breve descrição

Descreve como o PowerShell determina qual comando executar.

Descrição longa

A precedência de comandos descreve como o PowerShell determina qual comando executar quando uma sessão contém mais de um comando com o mesmo nome. Os comandos dentro de uma sessão podem ser ocultos ou substituídos por comandos com o mesmo nome. Este artigo mostra como executar comandos ocultos e como evitar conflitos de nome de comando.

Precedência de comando

Quando uma sessão do PowerShell inclui mais de um comando com o mesmo nome, o PowerShell determina qual comando executar usando as regras a seguir.

Se você especificar o caminho para um comando, o PowerShell executará o comando no local especificado pelo caminho.

Por exemplo, o comando a seguir executa o script FindDocs.ps1 no diretório C:\TechDocs:

C:\TechDocs\FindDocs.ps1

Você pode executar qualquer comando executável usando seu caminho completo. Como recurso de segurança, o PowerShell não executa comandos executáveis, incluindo scripts do PowerShell e comandos nativos, a menos que o comando esteja localizado em um caminho listado na variável de ambiente $Env:PATH.

Para executar um arquivo executável que esteja no diretório atual, especifique o caminho completo ou use o caminho relativo .\ para representar o diretório atual.

Por exemplo, para executar o arquivo FindDocs.ps1 no diretório atual, digite:

.\FindDocs.ps1

Se você não especificar um caminho, o PowerShell usará a seguinte ordem de precedência quando executar comandos.

1. Alias
2. Função
3. Cmdlet (consulte Resolução de nomes de cmdlet)
4. Arquivos executáveis externos (incluindo arquivos de script do PowerShell)

Portanto, se você digitar help, o PowerShell primeiro procurará um alias chamado help, depois uma função chamada helpe, finalmente, um cmdlet chamado help. Ele executa o primeiro help item que encontrar.

Por exemplo, se sua sessão contiver um cmdlet e uma função, ambos chamados Get-Map, quando você digitar Get-Map, o PowerShell executará a função.

Resolver itens com os mesmos nomes

Como resultado dessas regras, os itens podem ser substituídos ou ocultos por itens com o mesmo nome.

Os itens são ocultos ou sombreados se você ainda puder acessar o item original, por exemplo, qualificando o nome do item com um nome de módulo.

Por exemplo, se você importar uma função que tenha o mesmo nome de um cmdlet na sessão, o cmdlet ficará oculto, mas não será substituído. Você pode executar o cmdlet especificando seu nome qualificado para o módulo.

Quando os itens são substituídos ou substituídos, você não pode mais acessar o item original.

Por exemplo, se você importar uma variável que tenha o mesmo nome de uma variável na sessão, a variável original será substituída. Não é possível qualificar uma variável com um nome de módulo.

Se você criar uma função na linha de comando e, em seguida, importar uma função com o mesmo nome, a função original será substituída.

Localizar comandos ocultos

O parâmetro All do cmdlet Get-Command obtém todos os comandos com o nome especificado, mesmo que estejam ocultos ou substituídos. A partir do PowerShell 3.0, por padrão, Get-Command obtém apenas os comandos que são executados quando você digita o nome do comando.

Nos exemplos a seguir, a sessão inclui uma função Get-Date e um cmdlet Get-Date. Você pode usar Get-Command para determinar qual comando é escolhido primeiro.

Get-Command Get-Date

CommandType     Name                      ModuleName
-----------     ----                      ----------
Function        Get-Date

Usa o parâmetro All para listar comandos Get-Date disponíveis.

Get-Command Get-Date -All

CommandType     Name                 Version    Source
-----------     ----                 -------    ------
Function        Get-Date
Cmdlet          Get-Date             7.0.0.0    Microsoft.PowerShell.Utility

Get-Command where -All

CommandType Name                     Version      Source
----------- ----                     -------      ------
Alias       where -> Where-Object
Application where.exe                10.0.22621.1 C:\Windows\system32\where.exe

Você pode executar comandos específicos incluindo informações de qualificação que distinguem o comando de outros comandos que podem ter o mesmo nome. Para cmdlets, você pode usar o nome qualificado do módulo. Para executáveis, você pode incluir a extensão de arquivo. Por exemplo, para executar a versão executável do where use where.exe.

Usar nomes qualificados por módulo

O uso do nome qualificado por módulo de um cmdlet permite executar comandos ocultos por um item com o mesmo nome. Por exemplo, você pode executar o cmdlet Get-Date qualificando-o com seu nome de módulo Microsoft.PowerShell.Utility ou seu caminho. Quando você usa nomes qualificados para módulo, o módulo pode ser importado automaticamente para a sessão, dependendo do valor de $PSModuleAutoLoadingPreference.

O uso de nomes qualificados por módulo garante que você esteja executando o comando que pretende executar. Esse é o método recomendado de chamar cmdlets ao escrever scripts que você pretende distribuir.

O exemplo a seguir ilustra como qualificar um comando incluindo seu nome de módulo.

New-Alias -Name "Get-Date" -Value "Get-ChildItem"
Microsoft.PowerShell.Utility\Get-Date

Tuesday, May 16, 2023 1:32:51 PM

Para executar um comando New-Map a partir do módulo MapFunctions, use seu nome qualificado para módulo:

MapFunctions\New-Map

Para localizar o módulo do qual um comando foi importado, use o ModuleName propriedade de comandos.

(Get-Command <command-name>).ModuleName

Por exemplo, para localizar a origem do cmdlet Get-Date, digite:

(Get-Command Get-Date).ModuleName

Microsoft.PowerShell.Utility

Se você quiser qualificar o nome do comando usando o caminho para o módulo, você deve usar a barra (/) como o separador de caminho e o caractere de barra invertida (\) antes do nome do comando. Use o exemplo a seguir para executar o cmdlet Get-Date:

//localhost/c$/Progra~1/PowerShell/7-preview/Modules/Microsoft.PowerShell.Utility\Get-Date

O caminho pode ser um caminho completo ou um caminho relativo ao local atual. No Windows, não é possível usar um caminho qualificado para unidade. Você deve usar um caminho UNC, como mostrado no exemplo anterior, ou um caminho relativo à unidade atual. O exemplo a seguir pressupõe que seu local atual esteja na unidade C:.

/Progra~1/PowerShell/7-preview/Modules/Microsoft.PowerShell.Utility\Get-Date

Usar o operador de chamada

Você também pode usar o operador de chamada (&) para executar comandos ocultos combinando-o com uma chamada para Get-ChildItem (o alias é dir), Get-Command ou Get-Module.

O operador de chamada executa strings e blocos de script num âmbito filho. Para obter mais informações, consulte about_Operators.

Por exemplo, use o comando a seguir para executar a função chamada Map que está oculta por um alias chamado Map.

& (Get-Command -Name Map -CommandType Function)

quer

& (dir Function:\map)

Você também pode salvar seu comando oculto em uma variável para facilitar a execução.

Por exemplo, o comando a seguir salva a função Map na variável $myMap e, em seguida, usa o operador Call para executá-la.

$myMap = (Get-Command -Name map -CommandType Function)
& ($myMap)

Itens substituídos

Um substituído item é aquele que você não pode mais acessar. Você pode substituir itens importando itens do mesmo nome de um módulo.

Por exemplo, se você digitar uma função Get-Map em sua sessão e importar uma função chamada Get-Map, ela substituirá a função original. Não é possível recuperá-lo na sessão atual.

Variáveis e aliases não podem ser ocultos porque você não pode usar um operador de chamada ou um nome qualificado para executá-los. Quando você importa variáveis e aliases de um módulo, eles substituem variáveis na sessão com o mesmo nome.

Resolução de nomes de cmdlets

Quando você não usa o nome qualificado de um cmdlet, o PowerShell verifica se o cmdlet está carregado na sessão atual. Se houver vários módulos carregados que contenham o mesmo nome de cmdlet, o PowerShell usará o cmdlet do primeiro módulo encontrado em ordem alfabética.

Se o cmdlet não for carregado, o PowerShell pesquisará os módulos instalados e carregará automaticamente o primeiro módulo que contém o cmdlet e executa esse cmdlet. O PowerShell procura módulos em cada caminho definido na variável de ambiente $Env:PSModulePath. Os caminhos são pesquisados na ordem em que são listados na variável. Dentro de cada caminho, os módulos são pesquisados em ordem alfabética. O PowerShell usa o cmdlet desde a primeira correspondência encontrada.

Evitar conflitos de nomes

A melhor maneira de gerenciar conflitos de nome de comando é evitá-los. Ao nomear seus comandos, use um nome exclusivo. Por exemplo, adicione suas iniciais ou acrônimo do nome da empresa aos substantivos em seus comandos.

Ao importar comandos para sua sessão de um módulo do PowerShell ou de outra sessão, você pode usar o parâmetro Prefix do Import-Module ou cmdlet Import-PSSession para adicionar um prefixo aos substantivos nos nomes dos comandos.

Por exemplo, o comando a seguir evita qualquer conflito com os cmdlets Get-Date e Set-Date que vêm com o PowerShell quando você importa o módulo DateFunctions.

Import-Module -Name DateFunctions -Prefix ZZ

Executar executáveis externos

No Windows. O PowerShell trata as extensões de arquivo listadas na variável de ambiente $Env:PATHEXT como arquivos executáveis. Os ficheiros que não são executáveis do Windows são entregues ao Windows para serem processados. O Windows procura a associação de arquivo e executa o verbo padrão do Shell do Windows para a extensão. Para que o Windows suporte a execução por extensão de arquivo, a associação deve ser registrada no sistema.

Você pode registrar o mecanismo executável para uma extensão de arquivo usando os comandos ftype e assoc do shell de comando CMD. O PowerShell não tem nenhum método direto para registrar o manipulador de arquivos. Para obter mais informações, consulte a documentação do comando ftype.

Para que o PowerShell veja uma extensão de arquivo como executável na sessão atual, você deve adicionar a extensão à variável de ambiente $Env:PATHEXT.

Consulte também

• about_Aliases
• about_Functions
• about_Path_Syntax
• Alias-Provider
• Function-Provider
• Get-Command
• Import-Module
• Import-PSSession