about_Modules
Descrição breve
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 do processamento, e outros recursos, como variáveis, provedores, aliases.
Um módulo é uma unidade independente e reutilizável que pode incluir cmdlets, provedores, funções, variáveis e outros recursos que podem ser importados para uma sessão do PowerShell ou qualquer programa personalizado do PowerShell.
Antes que a funcionalidade contida em um módulo seja utilizável, o módulo deve ser carregado na sessão do PowerShell. 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 descarregar ou recarregar manualmente os módulos durante uma sessão do PowerShell. Para descarregar um módulo, use o Remove-Module cmdlet. Para carregar ou recarregar um módulo, use Import-Module.
O PowerShell vem com um conjunto básico de módulos. Qualquer pessoa pode criar novos comandos do PowerShell ou outros recursos e publicá-los como módulos que os usuários podem instalar conforme necessário.
Você pode escrever módulos em C# como assemblies .NET compilados, conhecidos como módulos nativos, ou no PowerShell simples, conhecidos como módulos de script. Este tópico 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, cmdlets e provedores eram empacotados em snap-ins do PowerShell. A partir do PowerShell 3.0, o snap-in Microsoft.PowerShell.Core é adicionado a todas as sessões por padrão. Esse é o único snap-in restante no PowerShell. Todos os outros snap-ins foram convertidos em módulos. Não há mais suporte para a criação de novos snap-ins.
Instalar um módulo publicado
Um módulo publicado é um módulo que está 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. Microsoft.PowerShell.PSResourceGet é o novo gerenciador de pacotes preferencial para o PowerShell e pode ser instalado em versões anteriores do PowerShell. Use o Install-Module cmdlet 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 Visão geral do PowerShellGet.
Instalar manualmente um módulo
Se você receber um módulo como uma pasta com arquivos, precisará instalá-lo em seu computador antes de poder usá-lo no PowerShell.
O PowerShell vem com vários módulos pré-instalados. Em computadores baseados no Windows, muitos recursos do Windows incluem módulos para gerenciar o recurso. Esses módulos são instalados quando o recurso é instalado. Outros módulos podem vir em um instalador ou programa de instalação que instala o módulo.
Por padrão, a Modules pasta do usuário atual não existe. Se você instalou um módulo no CurrentUser escopo usando Install-Module ou Install-PSResource, esses cmdlets criarão a Modules pasta para o usuário atual. Se a pasta não existir, você poderá criá-la manualmente.
Use o seguinte comando para criar uma Modules pasta para o usuário atual:
$folder = New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules
Copie toda a pasta do módulo para a nova pasta criada. No PowerShell, use o Copy-Item cmdlet. Por exemplo, execute o seguinte comando para copiar a MyModule pasta de para a pasta que você acabou de C:\PSTest criar:
Copy-Item -Path C:\PSTest\MyModule -Destination $folder
Você pode instalar um módulo em qualquer local, mas instalar os módulos em um local padrão de módulo torna-os mais fáceis de gerenciar. 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 (carrega) automaticamente esse módulo. O módulo deve ser armazenado nos locais especificados na variável de $env:PSModulePath ambiente. Os módulos em outros locais devem ser importados usando o Import-Module cmdlet.
O carregamento automático do módulo permite que você use comandos em um módulo sem qualquer configuração ou configuração de perfil. Não há necessidade de gerenciar módulos depois de instalá-los em seu computador.
Cada um dos exemplos a seguir faz com que o módulo CimCmdlets , que contém Get-CimInstance, seja importado para sua sessão.
Execute o comando
Get-CimInstance Win32_OperatingSystemObter o comando
Get-Command Get-CimInstanceObter ajuda para o comando
Get-Help Get-CimInstance
Você pode usar o Get-Command cmdlet listar os comandos em todos os módulos instalados, mesmo que eles ainda não estejam na sessão. 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.
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 WSMan: unidade, como o Get-PSSessionConfiguration cmdlet, talvez seja necessário executar o Import-Module cmdlet para importar o módulo Microsoft.WSMan.Management que inclui a WSMan: unidade.
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 $env:PSModulePath variável de ambiente ou quando o módulo é fornecido como um arquivo autônomo .dll ou .psm1 arquivo, em vez de um módulo empacotado.
Você também pode querer alterar como o módulo é importado em sua sessão. Por exemplo, o parâmetro Prefix de Import-Module adiciona um prefixo distinto à parte substantiva 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.
Você pode importar um módulo instalado em seu $env:PSModulePath especificando o nome do módulo. Por exemplo, o comando a seguir importa o módulo BitsTransfer para a sessão atual.
Import-Module BitsTransfer
Para importar um módulo que não está no seu $env:PSModulePath, use o caminho totalmente qualificado para a pasta do módulo. Por exemplo, para adicionar o módulo TestCmdlets no 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 está 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 Import-Module comando importa módulos para sua sessão atual do PowerShell. Para importar um módulo para cada sessão do PowerShell que você iniciar, adicione o comando ao seu perfil do Import-Module PowerShell.
Para obter mais informações sobre perfis, consulte about_Profiles.
Localizar módulos instalados
O Get-Module cmdlet obtém os módulos do PowerShell que foram importados em sua sessão.
Get-Module
Os módulos listados podem incluir módulos que foram importados de qualquer local, não apenas do $env:PSModulePath.
Use o seguinte comando para listar os módulos instalados no $env:PSModulePath:
Get-Module -ListAvailable
Esse comando obtém todos os módulos instalados no $env:PSModulePath, não apenas os módulos importados para a sessão atual. Esse comando não lista os módulos instalados em outros locais.
Para obter mais informações, consulte Get-Module.
Listar os comandos em um módulo
Use o Get-Command cmdlet para localizar todos os comandos disponíveis. Você pode usar os parâmetros do Get-Command cmdlet 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 BitsTransfer , digite:
Get-Command -Module BitsTransfer
Para obter mais informações sobre o Get-Command cmdlet, 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
Remover um módulo inverte a operação de importação de um módulo. A remoção de um módulo não desinstala o módulo. 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 podem adicionar apenas os cmdlets e provedores.
Antes de remover um módulo da sua sessão, use os comandos a seguir para determinar qual módulo você deseja remover.
Por exemplo, use o seguinte comando para localizar a origem dos Get-Date cmdlets 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 Get-Help cmdlet está no snap-in Microsoft.PowerShell.Core . Esse 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. Uma é uma função e a outra é um cmdlet no módulo Microsoft.PowerShell.Utility . Você pode remover o módulo usando Remove-Module. Para remover a função, você pode excluí-la da Function: unidade.
Remove-Item Function:Get-Date
Para obter mais informações sobre a unidade, consulte about_Function_ProviderFunction:.
Gerenciar conflitos de nome
Os conflitos de nome ocorrem quando mais de um comando na sessão tem o mesmo nome. Importar um módulo provoca um conflito de nome quando os comandos no módulo têm os mesmos nomes de comandos ou itens na sessão.
Import-Module pode adicionar comandos que ocultam e substituem comandos na sessão atual. Os conflitos de nome podem resultar em comandos sendo ocultados ou substituídos. A substituição de comando 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 substitui 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 que foi 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 Get-Date com o prefixo do nome do módulo garante que a versão do módulo Microsoft.PowerShell.Utility esteja sendo executada.
Para detectar conflitos de nome, use o parâmetro All do Get-Command cmdlet. Por padrão, Get-Command obtém apenas os comandos executados quando você digita o nome do comando. O parâmetro All obtém todos os comandos com o nome específico na sessão.
Para evitar conflitos de nome, use os parâmetros NoClobber ou Prefix do Import-Module cmdlet. 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 nenhum comando que oculte ou substitua comandos existentes na sessão.
Você também pode usar os parâmetros Alias, Cmdlet, Function e Variable para selecionar apenas os comandos que deseja importar e pode excluir comandos que causam conflitos de Import-Module nome em sua sessão.
Os autores de 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.
