about_Modules

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0

TÓPICO

about_Modules

DESCRIÇÃO BREVE

Explica como instalar, importar e usar os módulos Windows PowerShell.

DESCRIÇÃO LONGA

Um módulo é um pacote que contém os comandos Windows 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 Windows PowerShell e usá-los assim como os comandos internos.

Este tópico explica como usar módulos do Windows PowerShell. Para obter informações sobre como criar módulos do Windows PowerShell, consulte "Escrevendo um módulo do Windows PowerShell" na biblioteca MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkId=144916.

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.

O QUE HÁ DE NOVO NOS MÓDULOS: CARREGAMENTO AUTOMÁTICO DE MÓDULOS

A partir de Windows PowerShell 3.0, Windows PowerShell importa módulos automaticamente na primeira vez que você executar qualquer comando em um módulo instalado. Agora você pode executar 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. Agora, o cmdlet Get-Command obtém todos os comandos em todos os módulos instalados, mesmo se não estiverem ainda na sessão, assim você pode encontrar um comando e usá-lo sem importá-lo.

Qualquer um dos comandos a seguir importará um módulo para sua sessão.

        #Run the command
        Get-Mailbox –Identity Chris  

        #Get the command
        Get-Command Get-Mailbox

        #Get help for the command
        Get-Help Get-Mailbox

Os comandos Get-Command que incluem um caractere curinga (*) são considerados descobertos, não usam e não importam nenhum módulo.

Apenas o módulo que é armazenado no local especificado pela variável de ambiente PSModulePath é importado automaticamente. Os módulos em outros locais devem ser importados executando o cmdlet Import-Module.

Além disso, os comandos que usam provedores do Windows PowerShell não importam automaticamente um módulo. Por exemplo, se você usar um comando que requer o WSMan: unidade, como o cmdlet Get-PSSessionConfiguration, talvez seja necessário executar o cmdlet Import-Module para importar o módulo Microsoft.WSMan.Management que inclui o WSMan: drive.

Você ainda pode executar o comando Import-Module para importar um módulo e usar a variável $PSModuleAutoloadingPreference para habilitar, desabilitar e configurar a importação automática dos 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:

1. Instale o módulo. (Isso é geralmente feito para você.)

2. Localize os comandos que o módulo adicionou.

3. 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 que possa usá-lo no Windows PowerShell.

A maioria dos módulos é instalada por você. Windows PowerShell vem com vários módulos pré-instalado, às vezes chamados de módulos "principal". Em computadores baseados no Windows, se os recursos que estão incluídos com o sistema operacional tem cmdlets para gerenciá-los, esses módulos são pré-instalados. Quando você instala um recurso do Windows, usando, por exemplo, o Assistente de Adição de Funções e Recursos no Gerenciador do Servidor, ou a caixa de diálogo ativar ou desativar recursos do Windows no painel de controle, quaisquer módulos Windows 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.

Para instalar uma pasta de módulo:

1. Crie um diretório Modules para o usuário atual, se ainda não existir.

Para criar um diretório Modules, digite:

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

2. 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 o Cmd.exe, bem como o Windows PowerShell.

No Windows PowerShell, use o cmdlet Copy-Item. 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 padrão de módulo, consulte a seção "LOCAIS DE RECURSOS DO MÓDULO E DSC E 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 sua sessão, no prompt do Windows PowerShell, digite:

         Get-Module

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

COMO LOCALIZAR 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 os comandos de filtragem, 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 do módulo BitsTransfer, digite:

        Get-Command -Module BitsTransfer

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

COMO OBTER AJUDA PARA OS COMANDOS EM UM MÓDULO

Se o módulo contém arquivos de ajuda para os comandos que são exportados, o cmdlet Get-Help exibe os tópicos da Ajuda. Use o mesmo formato de comando Get-Help que você usaria para obter ajuda sobre qualquer comando no Windows PowerShell.

A partir do Windows PowerShell 3.0, você pode baixar arquivos de ajuda para um módulo e baixar atualizações para que os arquivos de ajuda nunca fiquem obsoletos.

Para obter ajuda para os comandos em um módulo, digite:

        Get-Help <command-name> 

Para obter ajuda online para os comandos 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 o 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 o módulo típico que é fornecido como uma pasta.

Você também pode optar por importar um módulo para que você possa usar os parâmetros do comando Import-Module, como o parâmetro Prefix, que adiciona um prefixo diferente aos nomes substantivos de todos os comandos importados ou o parâmetro NoClobber, que impede que o módulo adicione comandos que ocultam ou substituem comandos existentes na sessão.

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

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

COMO IMPORTAR UM MÓDULO PARA CADA SESSÃO

O comando Import-Module importa os módulos para a sua sessão atual do Windows PowerShell. Esse comando afeta apenas a sessão atual.

Para importar um módulo para cada sessão do Windows PowerShell que você inicia, adicione o comando Import-Module ao seu perfil do Windows 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 de 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 sobre o cmdlet Remove-Module, consulte Remove-Module.

LOCAIS DE RECURSOS DO MÓDULO E DSC E PSMODULEPATH

Estes são os locais padrão para módulos Windows PowerShell. Iniciando em Windows PowerShell 4.0, com a introdução do DSC, um novo módulo padrão e da pasta de recurso DSC foi introduzido. Para obter mais informações sobre DSC, consulte about_DesiredStateConfiguration.

Sistema:

módulos do sistema $pshome\Modules (% windir%\System32\WindowsPowerShell\v1.0\Modules) são aqueles que acompanham o Windows e Windows PowerShell.

Iniciando em Windows PowerShell 4.0, quando Windows PowerShell configuração de estado desejado (DSC) foi introduzida, recursos de DSC que estão incluídos Windows PowerShell também são armazenados em pshome\Modules $, na pasta pshome\Modules\PSDesiredStateConfiguration\DSCResources $.

Usuário atual:

$home\Documents\WindowsPowerShell\Modules (% UserProfile%\Documents\WindowsPowerShell\Modules)

- ou -

$home\My Documents\WindowsPowerShell\Modules (%UserProfile%\My Documents\WindowsPowerShell\Modules) esse é o local dos módulos adicionados pelo usuário antes de Windows PowerShell 4.0.

Em Windows PowerShell versões 4.0 e posteriores do Windows PowerShell, módulos e recursos DSC são armazenados em 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 de DSC é executado como sistema local e não foi possível acessar caminhos específicos do usuário, como $home\Documents\WindowsPowerShell\Modules.

Observação:

Para adicionar ou alterar os arquivos no diretório %Windir%\System32, inicie o Windows PowerShell com a opção "Executar como administrador".

Você pode alterar os locais padrão de módulo 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 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 diretório "C:\ps-test\Modules", digite:

        $env:psmodulepath + ";c:\ps-test\Modules"

Quando você adiciona um caminho a PSModulePath, os comandos Get-Module e Import-Module incluem módulos nesse caminho.

O valor que você define afeta apenas a sessão atual. Para tornar a alteração persistente, adicione o comando ao seu perfil do Windows 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 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. 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.

-- Replaced. 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 os 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 cmdlet Get-Command. A partir do Windows PowerShell 3.0, o Get-Command obtém apenas aqueles 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 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 quaisquer comandos que ocultam ou substituem comandos existentes na sessão.

Você também pode usar os parâmetros Alias, Cmdlet, Function e Variable de Import-Module para selecionar apenas os comandos que você deseja importar, e você pode excluir os comandos que causam conflitos de nome em sua sessão.

Os autores de módulo podem evitar conflitos de nomes 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 Windows PowerShell determinam qual comando será 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 Windows 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 sobre as 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 por meio de módulos e snap-ins. OS Módulos podem adicionar todos os tipos de comandos, incluindo cmdlets, provedores, funções e itens, como variáveis, aliases e unidades do Windows 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 cmdlet Get-Date, digite:

        get-command get-date | format-list -property verb, noun, pssnapin, module

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

ERROS E AVISOS RELACIONADOS AO MÓDULO

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

AVISO: Alguns nomes de comando importados incluem verbos não aprovados que podem torná-los menos identificá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 cmdlet Import-Module.

MÓDULOS INTERNOS E SNAP-INS

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

Começando no Windows PowerShell 3.0, em programas de host com estilo mais novo — aqueles que implementam a API de estado de sessão inicial InitialSessionState.CreateDefault2 – os principais comandos são empacotados em módulos. O padrão é Microsoft.PowerShell.Core, que é sempre um snap-in.

O snap-in Microsoft.PowerShell.Core é adicionado para cada sessão, por padrão. Os módulos são carregados automaticamente no primeiro uso.

OBSERVAÇÃO: As sessões remotas, inclusive as sessões iniciadas usando o cmdlet New-PSSession, são sessões de estilo antigo no qual os comandos internos são empacotados em snap-ins.

Os seguintes módulos (ou snap-ins) são instalados com o Windows PowerShell.

        Microsoft.PowerShell.Core
        Microsoft.PowerShell.Diagnostics
        Microsoft.PowerShell.Host
        Microsoft.PowerShell.Management
        Microsoft.PowerShell.ScheduledJob
        Microsoft.PowerShell.Security
        Microsoft.PowerShell.Utility
        Microsoft.WSMan.Management
        PSDesiredStateConfiguration
        PSWorkflow
        PSWorkflowUtility
        ISE

LOG DE EVENTOS DO MÓDULO

A partir do Windows PowerShell 3.0, você pode registrar eventos de execução para os cmdlets e as funções em módulos Windows PowerShell e snap-ins, definindo a propriedade LogPipelineExecutionDetails dos módulos e snap-ins para $True. Você também pode usar uma configuração de Política de Grupo (ativar o log de módulo) para habilitar o módulo de log em todas as sessões Windows PowerShell. Para obter mais informações, consulte about_EventLogs (https://go.microsoft.com/fwlink/?LinkID=113224) e about_Group_Policy_Settings (https://go.microsoft.com/fwlink/?LinkID=251696).

CONSULTE TAMBÉM

about_Command_Precedence

about_DesiredStateConfiguration

about_EventLogs

about_Group_Policy_Settings

about_PSSnapins

Get-Command

Get-Help

Get-Module

Import-Module

Remove-Module