Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Descrição breve
Explica como instalar, importar e usar módulos do PowerShell.
Descrição longa
Um módulo é um pacote que contém comandos do PowerShell, como cmdlets, provedores, funções, fluxos de trabalho, variáveis e aliases.
As pessoas que escrevem comandos podem usar módulos para organizar seus comandos e compartilhá-los com outras pessoas. As pessoas que recebem módulos podem adicionar os comandos nos módulos às suas sessões do PowerShell e usá-los exatamente como os comandos internos.
Este tópico explica como usar os módulos do PowerShell. Para obter informações sobre como escrever módulos do PowerShell, consulte escrevendo um módulo do PowerShell.
O que é um módulo?
Um módulo é um pacote de comandos. Todos os cmdlets e provedores em sua sessão são adicionados por um módulo ou um snap-in.
Módulo de carregamento automático
A partir do PowerShell 3,0, o PowerShell importa módulos automaticamente na primeira vez que você executa qualquer comando em um módulo instalado. Agora você pode usar os comandos em um módulo sem qualquer configuração de instalação ou perfil; portanto, não é necessário gerenciar módulos depois de instalá-los em seu computador.
Os comandos em um módulo também são mais fáceis de localizar. O Get-Command
cmdlet agora Obtém todos os comandos em todos os módulos instalados, mesmo que ainda não estejam na sessão, para que você possa encontrar um comando e usá-lo sem importar.
Cada um dos exemplos a seguir faz com que o módulo que contém Get-Mailbox
a seja importado para sua sessão.
Execute o comando
Get-Mailbox -Identity Chris
Obter o comando
Get-Command Get-Mailbox
Obter ajuda para o comando
Get-Help Get-Mailbox
Get-Command
comandos que incluem um caractere curinga (*) são considerados para descoberta, não uso e não importam nenhum módulo.
Somente os módulos armazenados no local especificado pela variável de ambiente PSModulePath são automaticamente importados. Os módulos em outros locais devem ser importados executando o Import-Module
cmdlet.
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 WSMan:, 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.
Você ainda pode executar o Import-Module
comando para importar um módulo e usar a $PSModuleAutoloadingPreference
variável para habilitar, desabilitar e configurar a importação automática de módulos. Para obter mais informações, consulte about_Preference_Variables.
Como usar um módulo
Para usar um módulo, execute as seguintes tarefas:
- Instale o módulo. (Isso é geralmente feito para você.)
- Localize os comandos que o módulo adicionou.
- Use os comandos que o módulo adicionou.
Este tópico explica como executar essas tarefas. Ele também inclui outras informações úteis sobre o gerenciamento de módulos.
Como instalar um módulo
Se você receber um módulo como uma pasta com arquivos, será necessário instalá-lo em seu computador antes de poder usá-lo no PowerShell.
A maioria dos módulos é instalada por você. O PowerShell vem com vários módulos pré-instalados, às vezes chamados de módulos "Core". Em computadores baseados no Windows, se os recursos incluídos no sistema operacional tiverem cmdlets para gerenciá-los, esses módulos serão pré-instalados. Quando você instala um recurso do Windows, usando, por exemplo, o assistente Adicionar funções e recursos no Gerenciador do Servidor ou a caixa de diálogo ativar ou desativar recursos do Windows no painel de controle, todos os módulos do PowerShell que fazem parte do recurso são instalados. Muitos outros módulos têm um instalador ou um programa de Instalação que instala o módulo.
Use o seguinte comando para criar um diretório de módulos para o usuário atual:
New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules
Copie a pasta de módulo inteira para o diretório Modules. Você pode usar qualquer método para copiar a pasta, incluindo o Windows Explorer e Cmd.exe, bem como o PowerShell. No PowerShell, use o Copy-Item
cmdlet. Por exemplo, para copiar a pasta MyModule de C:\ps-test\MyModule
para o diretório Modules, digite:
Copy-Item -Path C:\ps-test\MyModule -Destination `
$HOME\Documents\WindowsPowerShell\Modules
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 o módulo e os locais de recursos de DSC e a seção PSModulePath.
Como localizar os módulos instalados
Para localizar os módulos que são instalados em um local de módulo padrão, mas ainda não foram importados para a sessão, digite:
Get-Module -ListAvailable
Para localizar os módulos que já foram importados para a sessão, no prompt do PowerShell, digite:
Get-Module
Para obter mais informações sobre o Get-Module
cmdlet, consulte obter-módulo.
Como localizar 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.
Como obter ajuda para os comandos em um módulo
Se o módulo contiver arquivos de ajuda para os comandos que ele exporta, o Get-Help
cmdlet exibirá os tópicos da ajuda. Use o mesmo Get-Help
formato de comando que você usaria para obter ajuda para qualquer comando no PowerShell.
A partir do PowerShell 3,0, você pode baixar arquivos de ajuda para um módulo e baixar atualizações para os arquivos de ajuda para que eles nunca sejam obsoletos.
Para obter ajuda para os comandos em um módulo, digite:
Get-Help <command-name>
Para obter ajuda online para o comando em um módulo, digite:
Get-Help <command-name> -Online
Para baixar e instalar os arquivos de ajuda para os comandos em um módulo, digite:
Update-Help -Module <module-name>
Para obter mais informações, consulte Get-Help e Update-Help.
Como importar um módulo
Você pode precisar importar um módulo ou importar um arquivo de módulo. A importação é necessária quando um módulo não está instalado nos locais especificados pela variável de ambiente PSModulePath , $env:PSModulePath
ou o módulo consiste em um arquivo, como um arquivo. dll ou. psm1, em vez de um módulo típico que é entregue como uma pasta.
Você também pode optar por importar um módulo para que possa usar os parâmetros do Import-Module
comando, como o parâmetro Prefix, que adiciona um prefixo distintivo aos nomes de substantivo de todos os comandos importados, ou o parâmetro NoClobber , que impede que o módulo adicione comandos que ocultam ou substituem os comandos existentes na sessão.
Para importar módulos, use o Import-Module
cmdlet.
Para importar os módulos em um local de PSModulePath para a sessão atual, use o seguinte formato de comando.
Import-Module <module-name>
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á em um local padrão de módulo, use o caminho totalmente qualificado para a pasta de módulo no comando.
Por exemplo, para adicionar o módulo TestCmdlets no C:\ps-test
diretório à 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 C:\ps-test
diretório à 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.
Como importar um módulo para 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 Import-Module
comando ao seu perfil do PowerShell.
Para obter mais informações sobre perfis, consulte about_Profiles.
Como remover um módulo
Quando você remove um módulo, os comandos que o módulo adicionou são excluídos da sessão.
Para remover um módulo da sua sessão, use o seguinte formato de comando.
Remove-Module <module-name>
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. Remover um módulo não desinstala o módulo. Para obter mais informações, consulte Remove-Module.
Locais de recursos de módulo e DSC e PSModulePath
A seguir estão os locais padrão para os módulos do PowerShell. A partir do PowerShell 4,0, com a introdução do DSC, um novo módulo padrão e a pasta de recursos de DSC foram introduzidos. Para obter mais informações sobre o DSC, consulte about_DesiredStateConfiguration.
$PSHOME\Modules
Os módulos do sistema System: ou ($env:windir\System32\WindowsPowerShell\v1.0\Modules
) são aqueles que acompanham o Windows e o PowerShell.A partir do PowerShell 4,0, quando a DSC (configuração de estado desejado) do PowerShell foi introduzida, os recursos de DSC incluídos com o PowerShell também são armazenados no
$PSHOME\Modules
, na$PSHOME\Modules\PSDesiredStateConfiguration\DSCResources
pasta.Usuário atual:
$HOME\Documents\WindowsPowerShell\Modules
($env:UserProfile\Documents\WindowsPowerShell\Modules
)ou
$HOME\My Documents\WindowsPowerShell\Modules
($env:UserProfile\My Documents\WindowsPowerShell\Modules
)Este é o local para módulos adicionados pelo usuário antes do PowerShell 4,0.
No PowerShell 4,0 e versões posteriores do PowerShell, os módulos adicionados pelo usuário e os recursos de DSC são armazenados no C:\Program Files\WindowsPowerShell\Modules
. Os módulos e os recursos de DSC nesse local podem ser acessados por todos os usuários do computador. Essa alteração era necessária porque o mecanismo de DSC é executado como sistema local e não pôde acessar caminhos específicos do usuário, como $home\Documents\WindowsPowerShell\Modules
.
A partir do PowerShell 5,0, com a adição do módulo PowerShellGet e a Galeria do PowerShell de recursos criados pela Comunidade e pela Microsoft, o Install-Module
comando instala módulos e recursos de DSC para, C:\Program Files\WindowsPowerShell\Modules
por padrão.
Observação: para adicionar ou alterar arquivos no $env:Windir\System32
diretório, inicie o PowerShell com a opção "executar como administrador".
Você pode alterar os locais de módulo padrão no sistema alterando o valor da variável de ambiente PSModulePath , $Env:PSModulePath
. A variável de ambiente PSModulePath é modelada na variável de ambiente Path e tem o mesmo formato.
Para exibir os locais padrão de módulo, digite:
$Env:PSModulePath
Para adicionar um local padrão de módulo, use o seguinte formato de comando.
$Env:PSModulePath = $Env:PSModulePath + ";<path>"
O ponto e vírgula (;) no comando separa o novo caminho do caminho anterior na lista.
Por exemplo, para adicionar o C:\ps-test\Modules
diretório, digite:
$Env:PSModulePath + ";C:\ps-test\Modules"
Quando você adiciona um caminho ao PSModulePath Get-Module
e os Import-Module
comandos incluem módulos nesse caminho.
O valor que você define afeta apenas a sessão atual. Para fazer a alteração persistente, adicione o comando ao seu perfil do PowerShell ou use o sistema no painel de controle para alterar o valor da variável de ambiente PSModulePath no registro.
Além disso, para fazer a alteração persistente, você também pode usar o método SetEnvironmentVariable não da classe System. Environment para adicionar um caminho à variável de ambiente PSModulePath .
Para obter mais informações sobre a variável PSModulePath , consulte about_Environment_Variables.
Conflitos de módulos e nomes
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.
Os conflitos de nome podem resultar em comandos sendo ocultados ou substituídos.
Hidden
Um comando é ocultado quando ele não é o comando que é executado quando você digita o nome do comando, mas você pode executá-lo usando outro método, como qualificar o nome do comando com o nome do módulo ou snap-in na qual ele se originou.
Substituído
Um comando é substituído quando você não pode executá-lo porque ele foi substituído por um comando com o mesmo nome. Mesmo quando você remove o módulo que causou o conflito, não é possível executar um comando substituído, a menos que você reinicie a sessão.
Import-Module
pode adicionar comandos que ocultam e substituem comandos na sessão atual. Além disso, os comandos na sessão podem ocultar os comandos que o módulo adicionou.
Para detectar conflitos de nome, use o parâmetro All do Get-Command
cmdlet. A partir do PowerShell 3,0, Get-Command
obtém somente os comandos que são 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 os comandos existentes na sessão.
Você também pode usar o alias, o cmdlet, a funçãoe os parâmetros variáveis do Import-Module
para selecionar apenas os comandos que deseja importar e pode excluir comandos que causam conflitos de 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.
Mesmo se um comando estiver oculto, você poderá executá-lo qualificando o nome de comando com o nome do módulo ou snap-in no qual ele foi originado.
As regras de precedência de comando do PowerShell determinam qual comando é executado quando a sessão inclui comandos com o mesmo nome.
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.
Módulos e snap-ins
Você pode adicionar comandos à sua sessão 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 ou snap-in da sessão, use os comandos a seguir para determinar quais comandos serão removidos.
Para localizar a origem de um cmdlet em sua sessão, use o seguinte formato de comando:
Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module
Por exemplo, para localizar a origem do Get-Date
cmdlet, digite:
Get-Command Get-Date | Format-List -Property verb,noun,module
Para obter mais informações sobre snap-ins do PowerShell, consulte about_Pssnapins.
Avisos e erros relacionados ao módulo
Os comandos exportados por um módulo devem seguir as regras de nomenclatura de comando do PowerShell. Se o módulo que você importar exporta cmdlets ou funções que têm verbos não aprovados em seus nomes, o Import-Module
cmdlet exibe a seguinte mensagem de aviso.
Aviso: alguns nomes de comando importados incluem verbos não aprovados que podem torná-los menos detectáveis. Use o parâmetro Verbose para obter mais detalhes ou digite Get-Verb para ver a lista de verbos aprovados."
A mensagem é apenas um aviso. O módulo completo ainda é importado, incluindo os comandos não autorizados. Embora a mensagem seja exibida para usuários do módulo, o problema de nomenclatura deve ser corrigido pelo autor do módulo.
Para suprimir a mensagem de aviso, use o parâmetro DisableNameChecking do Import-Module
cmdlet.
Módulos internos e snap-ins
No PowerShell 2,0 e em programas de host de estilo mais antigo no PowerShell 3,0 e posteriores, os comandos principais instalados com o PowerShell são empacotados em snap-ins que são adicionados automaticamente a todas as sessões do PowerShell.
A partir do PowerShell 3,0, para programas de host que implementam a InitialSessionState.CreateDefault2
API de estado de sessão inicial, o snap-in do Microsoft. PowerShell. Core é adicionado a cada sessão por padrão. Os módulos são carregados automaticamente no primeiro uso.
Observação
Sessões remotas, incluindo sessões que são iniciadas usando o New-PSSession
cmdlet, são sessões de estilo mais antigas nas quais os comandos internos são empacotados em snap-ins.
Os seguintes módulos (ou snap-ins) são instalados com o PowerShell.
- Microsoft.PowerShell.Archive
- Microsoft.PowerShell.Core
- Microsoft.PowerShell.Diagnostics
- Microsoft.PowerShell.Host
- Microsoft.PowerShell.Management
- Microsoft.PowerShell.ODataUtils
- Microsoft.PowerShell.Security
- Microsoft.PowerShell.Utility
- Microsoft.WSMan.Management
- PackageManagement
- PowerShellGet
- PSDesiredStateConfiguration
- PSReadline
- PSScheduledJob
- PSWorkflow
- PSWorkflowUtility
- ISE
Log de eventos do módulo
A partir do PowerShell 3,0, você pode registrar eventos de execução para os cmdlets e funções nos módulos e snap-ins do PowerShell definindo a propriedade LogPipelineExecutionDetails de módulos e snap-ins no $True
.
Você também pode usar uma configuração de Política de Grupo, ativar o registro em log de módulo para habilitar o log de módulo em todas as sessões do PowerShell. Para obter mais informações, consulte about_EventLogs e about_Group_Policy_Settings.
Consulte Também
about_DesiredStateConfiguration