Sobre Módulos

Descrição Breve

Explica como instalar, importar e utilizar módulos PowerShell.

Descrição longa

Um módulo é um pacote que contém comandos PowerShell, tais como cmdlets, fornecedores, funções, fluxos de trabalho, variáveis e pseudónimos.

As pessoas que escrevem comandos podem usar módulos para organizar os seus comandos e partilhá-los com outros. As pessoas que recebem módulos podem adicionar os comandos nos módulos às suas sessões PowerShell e usá-los tal como os comandos incorporados.

Este tópico explica como usar módulos PowerShell. Para obter informações sobre como escrever módulos PowerShell, consulte escrever um Módulo PowerShell.

O que é um módulo?

Um módulo é um pacote de comandos. Todos os cmdlets e fornecedores da sua sessão são adicionados por um módulo ou um snap-in.

Módulo de Carregamento Automático

A partir de PowerShell 3.0, a PowerShell importa automaticamente os módulos da primeira vez que executar qualquer comando num módulo instalado. Agora pode utilizar os comandos num módulo sem qualquer configuração de configuração ou perfil, pelo que não é necessário gerir os módulos depois de os instalar no computador.

Os comandos num módulo também são mais fáceis de encontrar. O Get-Command cmdlet recebe agora todos os comandos em todos os módulos instalados, mesmo que ainda não estejam na sessão, para que possa encontrar um comando e usá-lo sem importar.

Cada um dos seguintes exemplos faz com que o módulo que contém Get-Mailbox seja importado para a sua sessão.

Executar o Comando
```
Get-Mailbox -Identity Chris
```
Obter o Comando
```
Get-Command Get-Mailbox
```
Obter ajuda para o comando
```
Get-Help Get-Mailbox
```

Get-Commandcomandos que incluem um caráter wildcard (*) são considerados para descoberta, não para uso, e não importam quaisquer módulos.

Apenas os módulos que são armazenados no local especificado pela variável ambiente PSModulePath são automaticamente importados. Os módulos noutros locais devem ser importados com a execução do Import-Module cmdlet.

Além disso, os comandos que utilizam fornecedores PowerShell não importam automaticamente um módulo. Por exemplo, se utilizar um comando que exija o WSMan: unidade, como o Get-PSSessionConfiguration cmdlet, poderá ter de executar o Import-Module cmdlet para importar o módulo Microsoft.WSMan.Management que inclui a WSMan: unidade.

Ainda é possível executar o Import-Module comando para importar um módulo e utilizar a $PSModuleAutoloadingPreference variável para ativar, desativar e configurar a importação automática de módulos. Para mais informações, consulte about_Preference_Variables.

Como usar um módulo

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

Instale o módulo. (Isto é muitas vezes feito para si.)
Encontre os comandos que o módulo acrescentou.
Utilize os comandos que o módulo adicionou.

Este tópico explica como executar estas tarefas. Também inclui outras informações úteis sobre a gestão de módulos.

Como instalar um módulo

Se receber um módulo como pasta com ficheiros, tem de o instalar no computador antes de o poder utilizar no PowerShell.

A maioria dos módulos estão instalados para si. PowerShell vem com vários módulos pré-instalados, por vezes chamados de módulos "núcleo". Nos computadores baseados no Windows, se as funcionalidades incluídas no sistema operativo tiverem cmdlets para os gerir, esses módulos estão pré-instalados. Quando instala uma funcionalidade do Windows, utilizando, por exemplo, o Assistente de Funcionalidades e Funcionalidades adicionais no Gestor do Servidor, ou as funcionalidades Turn Windows no painel de controlo ou desligado, estão instalados quaisquer módulos PowerShell que fazem parte da funcionalidade. Muitos outros módulos vêm num programa de instalação ou configuração que instala o módulo.

Utilize o seguinte comando para criar um diretório de módulos para o utilizador atual:

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

Copie toda a pasta do módulo no diretório de módulos. Pode utilizar 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 C:\ps-test\MyModule do diretório de Módulos, escreva:

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\WindowsPowerShell\Modules

Pode instalar um módulo em qualquer local, mas instalar os seus módulos numa localização de módulos predefinido torna-os mais fáceis de gerir. Para obter mais informações sobre as localizações do módulo predefinido, consulte as localizações de recursos do Módulo e DSC e a secção PSModulePath.

Como encontrar módulos instalados

Para encontrar módulos instalados numa localização padrão do módulo, mas ainda não importados para a sua sessão, escreva:

Get-Module -ListAvailable

Para encontrar os módulos que já foram importados para a sua sessão, na origem powerShell, escreva:

Get-Module

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

Como encontrar os comandos num módulo

Utilize o Get-Command cmdlet para encontrar todos os comandos disponíveis. Pode utilizar os parâmetros do Get-Command cmdlet para filtrar comandos como por módulo, nome e substantivo.

Para encontrar todos os comandos num módulo, escreva:

Get-Command -Module <module-name>

Por exemplo, para encontrar os comandos no módulo BitsTransfer, escreva:

Get-Command -Module BitsTransfer

Para obter mais informações sobre o Get-Command cmdlet, consulte o Comando De-Comando.

Como obter ajuda para os comandos num módulo

Se o módulo contiver ficheiros de ajuda para os comandos que exporta, o Get-Help cmdlet apresentará os tópicos de Ajuda. Utilize o mesmo Get-Help formato de comando que usaria para obter ajuda para qualquer comando em PowerShell.

A partir do PowerShell 3.0, pode descarregar ficheiros de Ajuda para um módulo e descarregar atualizações para os ficheiros de Ajuda para que nunca sejam obsoletos.

Para obter ajuda para um comando num módulo, escreva:

Get-Help <command-name>

Para obter ajuda on-line para o comando em um módulo, escreva:

Get-Help <command-name> -Online

Para descarregar e instalar os ficheiros de ajuda para os comandos num módulo, escreva:

Update-Help -Module <module-name>

Para obter mais informações, consulte Get-Help e Update-Help.

Como importar um módulo

Pode ter de importar um módulo ou importar um ficheiro de módulo. A importação é necessária quando um módulo não é instalado nos locais especificados pela variável ambiente PSModulePath, $env:PSModulePath ou o módulo é composto por ficheiro, como um ficheiro .dll ou .psm1, em vez de um módulo típico que é entregue como uma pasta.

Pode também optar por importar um módulo para que possa utilizar os parâmetros do Import-Module comando, como o parâmetro Prefix, que adiciona um prefixo distinto aos nomes de substantivos de todos os comandos importados, ou o parâmetro NoClobber, que impede o módulo de adicionar comandos que ocultariam ou substituiriam os comandos existentes na sessão.

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

Para importar módulos numa localização PSModulePath para a sessão atual, utilize o seguinte formato de comando.

Import-Module <module-name>

Por exemplo, o seguinte comando importa o módulo BitsTransfer para a sessão atual.

Import-Module BitsTransfer

Para importar um módulo que não esteja numa localização de módulo predefinido, utilize 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, escreva:

Import-Module C:\ps-test\TestCmdlets

Para importar um ficheiro de módulo que não esteja contido numa pasta de módulos, utilize o caminho totalmente qualificado para o ficheiro do módulo no comando.

Por exemplo, para adicionar o módulo TestCmdlets.dll no C:\ps-test diretório à sua sessão, escreva:

Import-Module C:\ps-test\TestCmdlets.dll

Para obter mais informações sobre a adição de módulos à sua sessão, consulte o Módulo de Importação.

Como importar um módulo em cada sessão

O Import-Module comando importa módulos para a sua atual sessão PowerShell. Para importar um módulo em todas as sessões powerShell que iniciar, adicione o Import-Module comando ao seu perfil PowerShell.

Para obter mais informações sobre perfis, consulte about_Profiles.

Como remover um módulo

Quando remove um módulo, os comandos que o módulo adicionado são eliminados da sessão.

Para remover um módulo da sua sessão, utilize o seguinte formato de comando.

Remove-Module <module-name>

Por exemplo, o seguinte comando remove o módulo BitsTransfer da sessão atual.

Remove-Module BitsTransfer

A remoção de um módulo inverte o funcionamento da 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 Remover-Module.

Localizações de Recursos módulos e DSC e PSModulePath

Seguem-se localizações predefinidoras para módulos PowerShell. A partir de PowerShell 4.0, com a introdução do DSC, foi introduzido um novo módulo padrão e uma pasta de recursos DSC. Para mais informações sobre a DSC, consulte about_DesiredStateConfiguration.

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

A partir de PowerShell 4.0, quando a Configuração do Estado Desejado (DSC) da PowerShell foi introduzida, os recursos DSC que estão incluídos com PowerShell também são armazenados em $PSHOME\Modules , na $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources pasta.
Utilizador atual: $HOME\Documents\WindowsPowerShell\Modules ( $env:UserProfile\Documents\WindowsPowerShell\Modules )

ou

$HOME\My Documents\WindowsPowerShell\Modules ($env:UserProfile\My Documents\WindowsPowerShell\Modules)

Esta é a localização para módulos adicionados ao utilizador antes do PowerShell 4.0.

No PowerShell 4.0 e posteriormente lançamentos de PowerShell, os módulos adicionados ao utilizador e os recursos DSC são armazenados em C:\Program Files\WindowsPowerShell\Modules . Os módulos e os recursos DSC neste local são acessíveis por todos os utilizadores do computador. Esta alteração foi necessária porque o motor DSC funciona como sistema local, e não conseguiu aceder a caminhos específicos do utilizador, tais como $home\Documents\WindowsPowerShell\Modules .

A partir do PowerShell 5.0, com a adição do módulo PowerShellGet, e da PowerShell Gallery da comunidade e recursos criados 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 ficheiros no $env:Windir\System32 diretório, inicie o PowerShell com a opção "Executar como administrador".

Pode alterar as localizações do módulo predefinido no seu sistema alterando o valor da variável ambiente PSModulePath, $Env:PSModulePath . A variável ambiente PSModulePath é modelada na variável ambiente Path e tem o mesmo formato.

Para visualizar as localizações do módulo predefinido, escreva:

$Env:PSModulePath

Para adicionar uma localização padrão do módulo, utilize 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, escreva:

$Env:PSModulePath + ";C:\ps-test\Modules"

Quando adicionas um caminho ao PSModulePath, Get-Module e os Import-Module comandos incluem módulos nesse caminho.

O valor que definiu afeta apenas a sessão atual. Para tornar a alteração persistente, adicione o comando ao seu perfil PowerShell ou utilize o Sistema no Painel de Controlo para alterar o valor da variável ambiente PSModulePath no registo.

Além disso, para tornar a mudança persistente, também pode utilizar o método SetEnvironmentVariable da classe System.Environment para adicionar um Caminho à variável 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. Importar um módulo causa um conflito de nomes quando os comandos no módulo têm os mesmos nomes que comandos ou itens na sessão.

Conflitos de nomes podem resultar em comandos escondidos ou substituídos.

Oculto

Um comando é escondido quando não é o comando que funciona quando escreve o nome de comando, mas pode executá-lo usando outro método, como por exemplo, qualificando o nome de comando com o nome do módulo ou encaixe no qual se originou.

Substituído

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

Import-Modulepode adicionar comandos que escondem e substituem comandos na sessão atual. Além disso, os comandos na sua sessão podem ocultar comandos que o módulo acrescentou.

Para detetar conflitos de nomes, utilize o parâmetro All do Get-Command cmdlet. A partir de PowerShell 3.0, Get-Command obtém-se apenas os comandos que funcionam quando escreve o nome de comando. O parâmetro All obtém todos os comandos com o nome específico na sessão.

Para evitar conflitos de nomes, utilize os parâmetros NoClobber ou Prefixo do Import-Module cmdlet. O parâmetro Prefix adiciona um prefixo aos nomes dos comandos importados para que sejam únicos na sessão. O parâmetro NoClobber não importa quaisquer comandos que ocultassem ou substituíssem os comandos existentes na sessão.

Também pode utilizar os parâmetros Alias, Cmdlet, Functione Variable de Import-Module selecionar apenas os comandos que pretende importar, e pode excluir comandos que causem conflitos de nomes na sua sessão.

Os autores do módulo podem prevenir conflitos de nomes utilizando a propriedade DefaultCommandPrefix do manifesto do módulo para adicionar um prefixo prefixo prefixo prefixo padrão a todos os nomes de comando. O valor do parâmetro prefixo prevalece sobre o valor do DefaultCommandPrefix.

Mesmo que um comando esteja escondido, pode executá-lo qualificando o nome de comando com o nome do módulo ou encaixe no qual se originou.

As regras de precedência do comando PowerShell determinam qual o comando que funciona 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 predefinição. Quando a sessão inclui comandos do mesmo tipo com o mesmo nome, como dois cmdlets com o mesmo nome, por padrão, executa o comando mais recentemente adicionado.

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.

Modules and Snap-ins (Módulos e Snap-ins)

Pode adicionar comandos à sua sessão a partir de módulos e snap-ins. Os módulos podem adicionar todo o tipo de comandos, incluindo cmdlets, fornecedores e funções, e itens, tais como variáveis, pseudónimos e unidades PowerShell. Os snap-ins podem adicionar apenas cmdlets e fornecedores.

Antes de remover um módulo ou encaixe da sua sessão, utilize os seguintes comandos para determinar quais os comandos que serão removidos.

Para encontrar a origem de um cmdlet na sua sessão, utilize o seguinte formato de comando:

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

Por exemplo, para encontrar a fonte do Get-Date cmdlet, escreva:

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

Para obter mais informações sobre os snap-ins powerShell, consulte about_PSSnapins.

Os comandos de que uma exportação de módulos deve seguir as regras de nomeação do comando PowerShell. Se o módulo que importa exportar cmdlets ou funções que não tenham verbos não aprovados nos seus Import-Module nomes, o cmdlet apresenta a seguinte mensagem de aviso.

AVISO: Alguns nomes de comando importados incluem verbos não aprovados que podem torná-los menos detetáveis. Utilize o parâmetro Verbose para obter mais detalhes ou digite Get-Verbo 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 apresentada aos utilizadores do módulo, o problema de nomeação deve ser corrigido pelo autor do módulo.

Para suprimir a mensagem de aviso, utilize o parâmetro de verificação de disableNameChecking do Import-Module cmdlet.

Módulos incorporados e Snap-ins

No PowerShell 2.0 e em programas de anfitriões de estilo mais antigo no PowerShell 3.0 e mais tarde, os comandos centrais que são instalados com PowerShell são embalados em snap-ins que são adicionados automaticamente a todas as sessãos powerShell.

A partir de PowerShell 3.0, para os programas de anfitrião que implementem a InitialSessionState.CreateDefault2 API do estado da sessão inicial, o snap-in Microsoft.PowerShell.Core é adicionado a todas as sessões por padrão. Os módulos são carregados automaticamente na primeira utilização.

Nota

Sessões remotas, incluindo sessões que são iniciadas usando o New-PSSession cmdlet, são sessões de estilo mais antigo em que os comandos incorporados são embalados 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
PSScheduldJob
Fluxo PSWork
PSWorkflowutility
ISE

Eventos do Módulo de Registo

A partir de PowerShell 3.0, pode gravar eventos de execução para os cmdlets e funções em módulos e snap-ins PowerShell, definindo a propriedade LogPipelineExecutionDetails de módulos e snap-ins para $True . Também pode utilizar uma definição de Política de Grupo, ativar o registo do módulo, para permitir a sessão de registo de módulos em todas as sessões PowerShell. Para mais informações, consulte about_EventLogs e about_Group_Policy_Settings.