about_Command_Precedence

Artigo
03/12/2024

Descrição breve

Descreve como o PowerShell determina qual comando executar.

Descrição longa

Precedência de comando 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 seguinte comando executa o script FindDocs.ps1 no C:\TechDocs diretório:

C:\TechDocs\FindDocs.ps1

Você pode executar qualquer comando executável usando seu caminho completo. Como um 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 $env:Path na variável de ambiente.

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 FindDocs.ps1 arquivo no diretório atual, digite:

.\FindDocs.ps1

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

Alias
Função
Cmdlet (consulte Resolução de nomes de cmdlets)
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 encontra.

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.

Observação

Isso só se aplica a comandos carregados. Se houver um build executável e um alias build para uma função com o nome de dentro de Invoke-Build um módulo que não é carregado na sessão atual, o PowerShell executará o build executável. Ele não carrega módulos automaticamente se encontrar o executável externo. É somente quando nenhum executável externo é encontrado que um alias, função ou cmdlet com o nome fornecido é invocado.

Resolvendo 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 ficam 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 pelo 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.

Localizando 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 Get-Date função 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 disponíveis Get-Date .

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 para módulo

O uso do nome qualificado de módulo de um cmdlet permite executar comandos ocultos por um item com o mesmo nome. Por exemplo, você pode executar o Get-Date cmdlet 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.

Observação

Não é possível usar nomes de módulo para qualificar variáveis ou aliases.

O uso de nomes qualificados para 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.

Importante

A qualificação do módulo usa o caractere de barra invertida (\) para separar o nome do módulo do nome do comando, independentemente da plataforma.

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

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

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

MapFunctions\New-Map

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

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

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

(Get-Command Get-Date).ModuleName

Microsoft.PowerShell.Utility

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

//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, você não pode 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 C: unidade.

/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 cadeias de caracteres e blocos de script em um escopo 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)

& (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 Map$myMap função na variável e usa o Call operador para executá-la.

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

Itens substituídos

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

Por exemplo, se você digitar uma Get-Map função na 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 executará esse cmdlet. O PowerShell procura módulos em cada caminho definido na $env:PSModulePath variável de ambiente. Os caminhos são pesquisados na ordem em que estão listados na variável. Dentro de cada caminho, os módulos são pesquisados em ordem alfabética. O PowerShell usa o cmdlet da primeira correspondência encontrada.

Evitando conflitos de nome

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 de 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 Prefixparâmetro do cmdlet Import-Module ou Import-PSSession para adicionar um prefixo aos substantivos nos nomes dos comandos.

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

Import-Module -Name DateFunctions -Prefix ZZ

Executando executáveis externos

No Windows. O PowerShell trata as extensões de arquivo listadas na $env:PATHEXT variável de ambiente como arquivos executáveis. Os arquivos 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 ofereça suporte à 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 ftype comandos 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 à $env:PATHEXT variável de ambiente.