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