Sobre os módulos

Breve Descrição

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 como os comandos internos.

Este tópico explica como usar 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.

Carregamento automático do módulo

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 configuração ou perfil, portanto, não há necessidade de gerenciar módulos depois de instalá-los no seu computador.

Os comandos em um módulo também são mais fáceis de encontrar. O Get-Command cmdlet agora recebe todos os comandos em todos os módulos instalados, mesmo que eles 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 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 Os comandos que incluem um caractere curinga (*) são considerados para descoberta, não para uso e não importam nenhum módulo.

Somente os módulos armazenados no local especificado pela variável de ambiente PSModulePath são importados automaticamente. 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 variável para habilitar, desabilitar e configurar a $PSModuleAutoloadingPreference importação automática de módulos. Para obter mais informações, consulte sobre_Variáveis_de_Preferência.

Como usar um módulo

Para usar um módulo, execute as seguintes tarefas:

Instale o módulo. (Isso geralmente é feito para você.)
Encontre 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 nele, precisará instalá-lo em seu computador antes de poder usá-lo no PowerShell.

A maioria dos módulos são instalados para você. O PowerShell vem com vários módulos pré-instalados, às vezes chamados de módulos "principais". 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 para 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 vêm em um instalador ou programa de instalação que instala o módulo.

Use o seguinte comando para criar um diretório Modules para o usuário atual:

New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules

Copie toda a pasta do módulo para o diretório Modules. Você pode usar qualquer método para copiar a pasta, incluindo o Windows Explorer e o Cmd.exe, bem como o PowerShell. No PowerShell, use o Copy-Item cmdlet. Por exemplo, para copiar a pasta MyModule do C:\ps-test\MyModule 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 seus módulos em um local de módulo padrão os torna mais fáceis de gerenciar. Para obter mais informações sobre os locais de módulo padrão, consulte a seção Module and DSC Resource Locations e PSModulePath .

Como encontrar módulos instalados

Para localizar módulos instalados em um local de módulo padrão, mas ainda não importados para sua sessão, digite:

Get-Module -ListAvailable

Para localizar os módulos que já foram importados para sua sessão, no prompt do PowerShell, digite:

Get-Module

Para obter mais informações sobre o Get-Module cmdlet, consulte Get-Module.

Como encontrar 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 BitsTransfer, digite:

Get-Command -Module BitsTransfer

Para obter mais informações sobre o cmdlet Get-Command, 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 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 fiquem obsoletos.

Para obter ajuda para um comando 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

Talvez seja necessário importar um módulo ou 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:PSModulePathou o módulo consiste em arquivo, como um arquivo .dll ou .psm1, em vez do 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 distinto aos nomes substantivos de todos os comandos importados, ou o parâmetro NoClobber , que impede que o módulo adicione comandos que ocultariam ou substituiriam comandos existentes na sessão.

Para importar módulos, use o Import-Module cmdlet.

Para importar módulos em um local 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 esteja em um local de módulo padrão, use o caminho totalmente qualificado para a pasta do 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 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.

Como importar um módulo para 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.

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 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

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.

Locais de recursos de módulo e DSC e PSModulePath

A seguir estão os locais padrão para módulos do PowerShell. A partir do PowerShell 4.0, com a introdução do DSC, um novo módulo padrão e uma pasta de recursos DSC foram introduzidos. Para obter mais informações sobre DSC, consulte about_DesiredStateConfiguration.

Sistema: $PSHOME\Modules ou ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Os módulos do sistema são aqueles fornecidos com o Windows e o PowerShell.

A partir do PowerShell 4.0, quando a Configuração de Estado Desejado (DSC) do PowerShell foi introduzida, os $PSHOME\Modules recursos do DSC incluídos no PowerShell também são armazenados no $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources, na 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 DSC são armazenados no C:\Program Files\WindowsPowerShell\Modules. Módulos e recursos DSC neste local são acessíveis por todos os usuários do computador. Essa alteração foi necessária porque o mecanismo 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 da Galeria do PowerShell de recursos criados pela comunidade e pela Microsoft, o Install-Module comando instala módulos e recursos DSC por C:\Program Files\WindowsPowerShell\Modules padrão.

Nota: Para adicionar ou alterar arquivos no diretório, inicie o $env:Windir\System32 PowerShell com a opção "Executar como administrador".

Você pode alterar os locais de módulo padrão em seu 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 de módulo padrão, digite:

$Env:PSModulePath

Para adicionar um local de módulo padrão, use o seguinte formato de comando.

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

O ponto-e-vírgula (;) no comando separa o novo caminho do caminho que o precede 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 PSModulePathGet-Module e Import-Module os comandos incluem módulos nesse caminho.

O valor definido afeta apenas a sessão atual. Para tornar a alteração persistente, adicione o comando ao seu perfil do PowerShell ou use Sistema no Painel de Controle para alterar o valor da variável de ambiente PSModulePath no Registro.

Além disso, para tornar a alteração persistente, você também pode usar o método SetEnvironmentVariable da classe System.Environment para adicionar um Path à variável de ambiente PSModulePath .

Para obter mais informações sobre a variável PSModulePath , consulte about_Environment_Variables.

Módulos e conflitos de nome

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.

Os conflitos de nomes podem resultar em comandos ocultos ou substituídos.

Escondido

Um comando fica oculto quando não é o comando que é executado quando você digita o nome do comando, mas você pode executá-lo usando outro método, como qualificando o nome do comando com o nome do módulo ou snap-in no qual ele se originou.

Substituído

Um comando é substituído quando não é possível executá-lo porque foi substituído por um comando com o mesmo nome. Mesmo quando você remove o módulo que causou o conflito, você não pode executar um comando substituído, a menos que reinicie a sessão.

Import-Module pode adicionar comandos que ocultam e substituem comandos na sessão atual. Além disso, os comandos na sua sessão podem ocultar comandos que o módulo adicionou.

Para detetar conflitos de nome, use o parâmetro All do cmdlet Get-Command. A partir do PowerShell 3.0, 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 nenhum comando que oculte ou substitua 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.

Mesmo que um comando esteja oculto, você pode executá-lo qualificando o nome do comando com o nome do módulo ou snap-in no qual ele se originou.

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

Pode adicionar comandos à 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 ou snap-in da sessão, use os seguintes comandos 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 cmdlet Get-Date, digite:

Get-Command Get-Date | Format-List -Property verb,noun,module

Para obter mais informações sobre snap-ins do PowerShell, consulte about_PSSnapins.

Os comandos que um módulo exporta devem seguir as regras de nomenclatura de comandos do PowerShell. Se o módulo importado exportar cmdlets ou funções com verbos não aprovados em seus nomes, o Import-Module cmdlet exibirá a seguinte mensagem de aviso.

AVISO: Alguns nomes de comandos importados incluem verbos não aprovados que podem torná-los menos detetáveis. Use o parâmetro Verbose para obter mais detalhes ou digite Get-Verb para ver a lista de verbos aprovados.

Esta mensagem é apenas um aviso. O módulo completo ainda é importado, incluindo os comandos não conformes. Embora a mensagem seja exibida para os 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 e snap-ins integrados

No PowerShell 2.0 e em programas de host de estilo mais antigo no PowerShell 3.0 e posterior, os comandos principais instalados com o PowerShell são empacotados em snap-ins que são adicionados automaticamente a cada sessão do PowerShell.

A partir do PowerShell 3.0, para programas de host que implementam a API de estado de InitialSessionState.CreateDefault2 sessão inicial, o snap-in Microsoft.PowerShell.Core é adicionado a cada sessão por padrão. Os módulos são carregados automaticamente na primeira utilização.

Observação

Sessões remotas, incluindo sessões iniciadas usando o New-PSSession cmdlet, são sessões de estilo mais antigo 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.Arquivo
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ODataUtils
Microsoft.PowerShell.Segurança
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
Gestão de Pacotes
PowerShellObter
PSDesiredStateConfiguration
PSReadline
PSScheduledJob
PSWorkflow
PSWorkflowUtility
ISE

Registrando 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 dos módulos e snap-ins como $True. Você também pode usar uma configuração de Política de Grupo, Ativar 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.