Compartilhar via


about_Modules

TÓPICO
    about_Modules

DESCRIÇÃO RESUMIDA
    Explica como instalar, importar e usar módulos do Windows PowerShell.

DESCRIÇÃO LONGA
    Um módulo é um pacote que contém comandos do Windows PowerShell, 
    como cmdlets, provedores, funções, variáveis e aliases. 

    As pessoas que escrevem comandos podem usar módulos para organizar os 
    comandos e compartilhá-los com outros. As pessoas que recebem módulos 
podem adicionar os comandos nos módulos às sessões do Windows 
PowerShell e usá-los como os comandos internos.

    Este tópico explica como usar os módulos do Windows PowerShell. 
    Para obter informações sobre como escrever módulos do Windows 
    PowerShell, consulte " Writing a Windows PowerShell Module" na 
    biblioteca do MSDN (Microsoft Developer Network) em 
    https://go.microsoft.com/fwlink/?LinkId=144916 (site em inglês).
    

 COMO USAR UM MÓDULO
    Para usar um módulo, execute as tarefas a seguir:

        1. Instale o módulo. (Isso normalmente é feito para você.) 2. 
        Importe o módulo para a sua sessão do Windows PowerShell.
        3. Localize os comandos que o módulo adicionou.
        4. Use os comandos que o módulo adicionou.
     
    Este tópico explica como executar essas tarefas. Ela também 
    inclui outras informações úteis sobre como gerenciar módulos.


 COMO INSTALAR UM MÓDULO
    Se você receber um módulo como uma pasta com arquivos, precisará 
    instalá-lo em seu computador antes de importá-lo para o Windows 
    PowerShell.

    A maioria dos módulos é instalado para você. O Windows PowerShell 
    é fornecido com vários módulos pré-instalados. No Windows Server 
    2008 R2, o Assistente para Adicionar Recursos no Gerenciador de 
    Servidor instala automaticamente os módulos de recurso que você 
    seleciona. Muitos outros módulos são fornecidos com um instalador 
    ou 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 houver um. 

           Para criar um diretório Modules, digite:

               new-item -type directory -path $home\Documents\WindowsPowerShell\Modules                             

        2. Copie a pasta de módulo inteira no diretório Modules.

           Você pode usar qualquer método para copiar a pasta, inclusive o 
           Windows Explorer e 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\MyModul
           e para o diretório Modules, digite:

               copy-item -path c:\ps-test\MyModule -dest $home\Documents\WindowsPowerShell\Modules

    Você pode instalar um módulo em qualquer local, mas fica mais 
    fácil gerenciar os módulos se os instalar em um local de módulo 
    padrão. Para obter mais informações sobre os locais de módulo padrão, 
    consulte a seção "Locais de módulo e PSModulePath".



 COMO LOCALIZAR OS MÓDULOS INSTALADOS
      Quando um módulo é instalado, você pode importá-lo para a sua 
      sessão do Windows PowerShell. 

      Para localizar módulos que são instalados em um local de módulo 
      padrão, no prompt do Windows PowerShell, digite:

         get-module -listAvailable


      Para localizar os módulos que já foram importados para 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 IMPORTAR UM MÓDULO
    Para usar os comandos em um módulo, importe o módulo para uma 
    sessão do Windows PowerShell.

    Para importar módulos de um local de módulo padrão para a sessão 
    atual, use o formato de comando a seguir.

        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 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 diretório 
    C:\ps-test a sua sessão, digite:

        import-module c:\ps-test\TestCmdlets

    Para obter mais informações sobre como adicionar módulos à 
    sessão, consulte Import-Module.
    


 COMO IMPORTAR TODOS OS MÓDULOS PARA SUA SESSÃO DO WINDOWS POWERSHELL 
    No Windows 7 e no Windows Server 2008 R2, a tarefa "Importar todos 
    os módulos" abre uma sessão do Windows PowerShell que inclui todos 
    os módulos e snap-ins disponíveis do Windows PowerShell.

    Para iniciar uma sessão do Windows PowerShell com todos os 
    módulos e snap-ins disponíveis do Windows PowerShell, use o 
    procedimento a seguir.

    -- Clique com o botão direito do mouse no ícone Windows 
       PowerShell na barra de tarefas e, em seguida, clique em 
       "Importar todos os módulos".

    Observação: No Windows Server 2008 R2, o ícone Windows PowerShell 
                é fixo por padrão à barra de tarefas. Contudo, você deve 
                iniciar o Windows PowerShell uma vez para que a tarefa 
                "Importar todos os módulos" seja exibida.

    Em outras versões do Windows, para todos os módulos disponíveis para 
    importação em sua sessão, no prompt do Windows PowerShell, digite:

        get-module -listAvailable | import-module


   
 COMO LOCALIZAR OS COMANDOS EM UM MÓDULO
    Depois de importar um módulo para a sua sessão do Windows 
    PowerShell, você pode usar os comandos no módulo.

    Para localizar os comandos adicionados por um módulo, no prompt 
    do Windows PowerShell, digite:

        get-command -module <module-name>

    Por exemplo, para localizar os comandos que o módulo BitsTransfer 
    adiciona, digite:

        get-command -module BitsTransfer

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



 COMO LOCALIZAR A AJUDA PARA OS COMANDOS EM UM MÓDULO
    Se o módulo contiver tópicos de Ajuda para os comandos que ele 
    exporta, o cmdlet Get-Help exibirá os tópicos de Ajuda. Use o 
    mesmo formato de comando que você usaria para qualquer tópico de 
    Ajuda no Windows PowerShell. 

    Para localizar os tópicos de Ajuda para os comandos em um módulo, 
    no prompt do Windows PowerShell, digite:

        get-help <command-name> 

    Para obter Ajuda mais detalhada, digite:

        get-help <command-name> -detailed

    Por exemplo, para localizar a Ajuda detalhada para o cmdlet Start-
    BitsTransfer, digite:
       
        get-help Start-BitsTransfer -detailed

    Para obter mais informações sobre o módulo Get-Help, consulte 
    Get-Help.




 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 formato de comando a 
    seguir.

        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 inverte 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 sobre o cmdlet Remove-Module, consulte Remove-Module.



 COMO IMPORTAR UM MÓDULO PARA CADA SESSÃO
    O comando Import-Module importa módulos para a sessão atual do Windows 
    PowerShell. Esse comando afeta somente a sessão atual.

    Para importar um módulo para cada sessão do Windows PowerShell 
    que você inicia, adicione um comando Import-Module a seu perfil 
    do Windows PowerShell.

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

  
 LOCAIS DE MÓDULO E PSMODULEPATH
    Há dois locais padrão para módulos do Windows PowerShell, um para 
    o sistema e um para o usuário atual.

        Sistema:        $pshome\Modules 
                           (%windir%\System32\WindowsPowerShell\v1.0\Modules)

        Usuário atual: $home\Documents\WindowsPowerShell\Modules 
                   (%UserProfile%\Documents\WindowsPowerShell\Modules)

                       - ou -

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



        Observação: No Windows Vista, Windows Server 2008 e versões 
                    posteriores de Windows, para adicionar ou alterar 
                    arquivos no diretório %Windir%\System32, inicie o 
                    Windows 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 de 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 formato de 
    comando a seguir.

        $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 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 naquele caminho.
       
    O valor definido afeta apenas a sessão atual. Para tornar a alteração 
    persistente, adicione o comando a seu perfil do Windows PowerShell ou 
    use o item Sistema no Painel de Controle para alterar o valor da variável de 
    ambiente PSModulePath no Registro.

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


 MÓDULOS E CONFLITOS DE NOMES
    Os conflitos de nomes ocorrem quando mais de um comando na sessão 
    tem o mesmo nome. A importação de um módulo causa um conflito de 
    nome quando os comandos no módulo têm os mesmos nomes que os 
    comandos ou itens na sessão. 

    Os conflitos de nome podem resultar em comandos que ficam ocultos 
    ou são substituídos.
        -- Oculto. Um comando fica oculto quando ele não é executado 
           quando você digita o nome de comando, mas você pode 
           executá-lo usando outro método, como a qualificação do 
           nome de comando com o nome do módulo ou snap-in no 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. Até mesmo quando você remover 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 impedir conflitos de nome, use o parâmetro Prefix de 
    Import-Command para criar nomes exclusivos para os comandos 
    importados.

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

    Mesmo que um comando esteja oculto, você pode executá-lo por meio da 
    qualificação do nome de comando com o nome do módulo ou snap-in no 
    qual ele se originou. 
    As regras de precedência de comando do Windows PowerShell 
    determinam quais comandos são executados 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, ele executa o comando 
    mais recente adicionado. 

    Para obter mais informações, inclusive 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 a sua sessão de módulos e snap-ins. 
    Os módulos podem adicionar todos os tipos de comandos, inclusive 
    cmdlets, provedores, funções e itens, como variáveis, aliases e 
    unidades do Windows PowerShell. Os snap-ins podem adicionar 
    somente cmdlets e provedores.

    Na verdade, embora você possa adicionar funções, aliases, variáveis e 
    unidades a sua sessão digitando-os ou executando um script que os 
    adiciona, todos os cmdlets e provedores na sua sessão vêm de um 
    módulo ou um snap-in.

    Antes de remover um módulo ou snap-in de sua sessão, use os 
    comandos a seguir para determinar quais comandos serão removidos. 

    Para localizar a origem de um cmdlet na sua sessão, use o formato 
    de comando a seguir:

        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.


CONSULTE TAMBÉM
    about_Command_Precedence
    about_PSSnapins
    Get-Command
    Get-Help
    Get-Module
    Import-Module
    Remove-Module