Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Breve descrição
Explica como instalar, importar e usar módulos do PowerShell.
Descrição longa
O PowerShell é um shell de comando e uma linguagem de script. Os comandos no PowerShell são implementados como scripts, funções ou cmdlets. A linguagem inclui palavras-chave, que fornecem a estrutura e a lógica de processamento, e outros recursos, como variáveis, provedores, aliases.
Um módulo é uma unidade autônoma e reutilizável que pode incluir cmdlets, provedores, funções, variáveis e outros recursos. Por padrão, o PowerShell carrega automaticamente um módulo instalado na primeira vez que você usa um comando do módulo. Você pode configurar o comportamento de carregamento automático do módulo usando a variável $PSModuleAutoLoadingPreference. Para obter mais informações, consulte about_Preference_Variables.
Você também pode carregar ou descarregar módulos manualmente durante uma sessão do PowerShell. Para carregar ou recarregar um módulo, use Import-Module. Para descarregar um módulo, use o cmdlet Remove-Module.
O PowerShell inclui um conjunto básico de módulos. Qualquer pessoa pode criar novos módulos usando C# ou a própria linguagem de script do PowerShell. Os módulos escritos em C# como assemblies .NET compilados são conhecidos como módulos nativos. Os módulos escritos no PowerShell são conhecidos como módulos de script.
Este artigo explica como usar módulos do PowerShell. Para obter informações sobre como criar módulos do PowerShell, consulte Escrevendo um módulo do PowerShell.
Observação
Antes do PowerShell 3.0, os cmdlets e provedores eram agrupados em snap-ins do PowerShell. A partir do PowerShell 3.0, o snap-in Microsoft.PowerShell.Core é automaticamente adicionado a todas as sessões. Este é o único snap-in restante no PowerShell. Todos os outros snap-ins foram convertidos em módulos. A criação de novos snap-ins não é mais suportada.
Locais de módulo padrão
O PowerShell armazena módulos nos seguintes locais padrão:
- No Windows
- Âmbito de aplicação de todos os utilizadores -
$Env:ProgramFiles\PowerShell\Modules - Escopo do usuário atual -
$HOME\Documents\PowerShell\Modules - Módulos fornecidos com o PowerShell -
$PSHOME\Modules
- Âmbito de aplicação de todos os utilizadores -
- No Linux e macOS
- Âmbito de aplicação de todos os utilizadores -
/usr/local/share/powershell/Modules - Escopo do usuário atual -
$HOME/.local/share/powershell/Modules - Módulos fornecidos com o PowerShell -
$PSHOME/Modules
- Âmbito de aplicação de todos os utilizadores -
Por padrão, a pasta Modules para o usuário atual não existe. Se você instalou um módulo no escopo CurrentUser usando Install-Module ou Install-PSResource, esses cmdlets criarão a pasta Modules para o usuário atual. Se a pasta não existir, você poderá criá-la manualmente.
Use o seguinte comando para criar uma pasta Modules para o usuário atual:
$folder = New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules
Esses locais são automaticamente incluídos na variável de ambiente $Env:PSModulePath. Para obter mais informações sobre os locais de módulo padrão, consulte about_PSModulePath.
Carregamento automático do módulo
Na primeira vez que você executa um comando de um módulo instalado, o PowerShell importa automaticamente (carrega) esse módulo. O módulo deve ser armazenado nos locais especificados na variável de ambiente $Env:PSModulePath.
O carregamento automático do módulo permite que você use comandos em um módulo sem qualquer configuração de configuração ou perfil. Cada um dos exemplos a seguir faz com que o módulo
Execute o comando
Get-CimInstance Win32_OperatingSystemObter o comando
Get-Command Get-CimInstanceObter ajuda para o comando
Get-Help Get-CimInstance
Quando você usa Get-Command com um caractere curinga (*), o PowerShell não importa nenhum módulo. Você pode usar curingas para descoberta de comandos sem carregar módulos que talvez não sejam necessários em sua sessão.
Importar manualmente um módulo
A importação manual de um módulo é necessária quando um módulo não está instalado nos locais especificados pela variável de ambiente $Env:PSModulePath ou quando o módulo é fornecido como um arquivo .dll ou .psm1 autônomo, em vez de um módulo empacotado.
Além disso, os comandos que usam provedores do PowerShell não importam automaticamente um módulo. Por exemplo, se você usar um comando que exija a unidade
Você também pode querer alterar a forma como o módulo é importado em sua sessão. Por exemplo, o parâmetro Prefix de Import-Module adiciona um prefixo distinto à parte nominal dos cmdlets importados do módulo. O parâmetro NoClobber impede que o módulo adicione comandos que ocultariam ou substituiriam comandos existentes na sessão. Para obter mais informações, consulte Gerenciar conflitos de nome.
O exemplo a seguir importa o módulo BitsTransfer para a sessão atual.
Import-Module BitsTransfer
Para importar um módulo que não esteja no seu $Env:PSModulePath, use o caminho totalmente qualificado para a pasta do módulo. Por exemplo, para adicionar o módulo TestCmdlets do diretório C:\ps-test à sua sessão, digite:
Import-Module C:\ps-test\TestCmdlets
Para importar um arquivo de módulo que não esteja contido em uma pasta de módulo, use o caminho totalmente qualificado para o arquivo de módulo no comando. Por exemplo, para adicionar o módulo TestCmdlets.dll no diretório C:\ps-test à sua sessão, digite:
Import-Module C:\ps-test\TestCmdlets.dll
Para obter mais informações sobre como adicionar módulos à sua sessão, consulte Import-Module.
Importar um módulo no início de cada sessão
O comando Import-Module importa módulos para sua sessão atual do PowerShell. Para importar um módulo para cada sessão do PowerShell iniciada, adicione o comando Import-Module ao seu perfil do PowerShell.
Para obter mais informações sobre perfis, consulte about_Profiles.
Instalar um módulo publicado
Um módulo publicado é um módulo disponível em um repositório registrado, como a Galeria do PowerShell. Os módulos PowerShellGet e Microsoft.PowerShell.PSResourceGet fornecem cmdlets para localizar, instalar e publicar módulos do PowerShell em um repositório registrado.
O módulo PowerShellGet está incluído no PowerShell 5.0 e versões posteriores. O módulo Microsoft.PowerShell.PSResourceGet está incluído no PowerShell 7.4 e versões posteriores e é o gerenciador de pacotes preferido para o PowerShell.
Microsoft.PowerShell.PSResourceGet pode ser instalado, lado a lado com o PowerShellGet, em versões mais antigas do PowerShell. Use o cmdlet Install-Module ou Install-PSResource para instalar módulos da Galeria do PowerShell.
Get-Command Install-Module, Install-PSResource
CommandType Name Version Source
----------- ---- ------- ------
Function Install-Module 2.9.0 PowerShellGet
Cmdlet Install-PSResource 1.0.0 Microsoft.PowerShell.PSResourceGet
Para obter mais informações, consulte PowerShellGet Overview.
Instalar manualmente um módulo
Você pode instalar manualmente um módulo copiando o conteúdo do módulo de outra pasta. Essa pasta pode estar em outro local na máquina local ou instalada em outra máquina. Para instalar um módulo manualmente, copie toda a pasta do módulo para um novo local incluído no seu $Env:PSModulePath.
No PowerShell, use o Copy-Item cmdlet. Por exemplo, execute o seguinte comando para copiar a pasta MyModule de C:\PSTest:
$modulePath = $HOME\Documents\PowerShell\Modules\MyModule
Copy-Item -Path C:\PSTest\MyModule\* -Destination $modulePath -Recurse
Você pode instalar um módulo em qualquer local, mas instalar seus módulos em um local de módulo padrão os torna mais fáceis de gerenciar.
Localizar módulos instalados
O cmdlet Get-Module obtém os módulos do PowerShell que são carregados na sessão atual do PowerShell.
Get-Module
Os módulos listados podem incluir módulos que foram importados de qualquer local, não apenas de $Env:PSModulePath.
Use o seguinte comando para listar os módulos instalados no $Env:PSModulePath:
Get-Module -ListAvailable
Este comando obtém todos os módulos instalados no $Env:PSModulePath, não apenas os módulos importados para a sessão atual. Este comando não lista módulos instalados em outros locais.
Para obter mais informações, consulte Get-Module.
Listar os comandos em um módulo
Use o cmdlet Get-Command para localizar todos os comandos disponíveis. Você pode usar os parâmetros do cmdlet Get-Command para filtrar comandos como por módulo, nome e substantivo.
Para localizar todos os comandos em um módulo, digite:
Get-Command -Module <module-name>
Por exemplo, para localizar os comandos no módulo
Get-Command -Module BitsTransfer
Para obter mais informações sobre o cmdlet Get-Command, consulte Get-Command.
Remover um módulo
Quando você remove um módulo, os comandos que o módulo adicionou são excluídos da sessão. Por exemplo, o comando a seguir remove o módulo BitsTransfer da sessão atual.
Remove-Module BitsTransfer
A remoção de um módulo reverte a operação de importação de um módulo. A remoção de um módulo não o desinstala. Para obter mais informações, consulte Remove-Module.
Os comandos podem ser adicionados à sua sessão a partir de módulos e snap-ins. Os módulos podem adicionar todos os tipos de comandos, incluindo cmdlets, provedores e funções, e itens, como variáveis, aliases e unidades do PowerShell. Os snap-ins só podem adicionar cmdlets e provedores.
Antes de remover um módulo da sessão, use os seguintes comandos para determinar qual módulo você deseja remover.
Por exemplo, use o seguinte comando para localizar a origem dos cmdlets Get-Date e Get-Help:
Get-Command Get-Date, Get-Help -All |
Select-Object -Property Name, CommandType, Module ,PSSnapIn
A saída a seguir mostra que o cmdlet Get-Help está no snap-in Microsoft.PowerShell.Core. Este snap-in não pode ser removido da sessão.
Name CommandType Module PSSnapIn
---- ----------- ------ --------
Get-Date Function
Get-Date Cmdlet Microsoft.PowerShell.Utility
Get-Help Cmdlet Microsoft.PowerShell.Core
Existem duas fontes para Get-Date. Um é uma função e o outro é um cmdlet no módulo Microsoft.PowerShell.Utility Remove-Module. Para remover a função, pode excluí-la da unidade Function:.
Remove-Item Function:Get-Date
Para obter mais informações sobre a unidade Function:, consulte about_Function_Provider.
Gerenciar conflitos de nomes
Os conflitos de nome ocorrem quando mais de um comando na sessão tem o mesmo nome. A importação de um módulo causa um conflito de nomes quando os comandos no módulo têm os mesmos nomes que os comandos ou itens na sessão.
Import-Module pode adicionar comandos que ocultam e substituem comandos na sessão atual. Os conflitos de nomes podem resultar em comandos ocultos ou substituídos. A substituição de comandos ocorre quando o módulo importado contém um comando com o mesmo nome de um comando existente na sessão. O comando recém-importado tem precedência sobre o comando existente.
Por exemplo, quando uma sessão inclui uma função e um cmdlet com o mesmo nome, o PowerShell executa a função por padrão. Quando a sessão inclui comandos do mesmo tipo com o mesmo nome, como dois cmdlets com o mesmo nome, por padrão, ela executa o comando adicionado mais recentemente.
Para obter mais informações, incluindo uma explicação das regras de precedência e instruções para executar comandos ocultos, consulte about_Command_Precedence.
Você pode executar um comando oculto ou substituído qualificando o nome do comando. Para qualificar o nome do comando, adicione o nome do módulo que contém a versão do comando desejada. Por exemplo:
Microsoft.PowerShell.Utility\Get-Date
A execução de Get-Date com o prefixo do nome do módulo garante que esteja a executar a versão do módulo Microsoft.PowerShell.Utility.
Para detetar conflitos de nome, use o parâmetro All do cmdlet Get-Command. Por padrão, Get-Command obtém apenas os comandos que são executados quando você digita o nome do comando. O parâmetro All reúne todos os comandos com o nome específico dado na sessão.
Para evitar conflitos de nome, use os parâmetros NoClobber ou Prefix do cmdlet Import-Module. O parâmetro Prefix adiciona um prefixo aos nomes dos comandos importados para que eles sejam exclusivos na sessão. O parâmetro NoClobber não importa comandos que possam ocultar ou substituir comandos existentes na sessão.
Você também pode usar Alias, Cmdlet, Functione Variable como parâmetros de Import-Module para selecionar apenas os comandos que pretende importar, e pode excluir comandos que provocam conflitos de nomes na sessão.
Os autores do módulo podem evitar conflitos de nome usando a propriedade DefaultCommandPrefix do manifesto do módulo para adicionar um prefixo padrão a todos os nomes de comando. O valor do parâmetro Prefix tem precedência sobre o valor de DefaultCommandPrefix.
Ver também
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
