Compartilhar via

Instalar um módulo do PowerShell

Depois de criar o módulo do PowerShell, você provavelmente desejará instalar o módulo em um sistema, para que você ou outras pessoas possam usá-lo. De modo geral, isso consiste em copiar os arquivos do módulo (ou seja, o .psm1ou o assembly binário, o manifesto do módulo e quaisquer outros arquivos associados) em um diretório nesse computador. Para um projeto muito pequeno, isso pode ser tão simples quanto copiar e colar os arquivos com o Windows Explorer em um único computador remoto; no entanto, para soluções maiores, talvez você queira usar um processo de instalação mais sofisticado. Independentemente de como você colocar seu módulo no sistema, o PowerShell pode usar várias técnicas que permitirão que os usuários encontrem e usem seus módulos. Portanto, o principal problema para a instalação é garantir que o PowerShell seja capaz de localizar seu módulo. Para obter mais informações, consulte Importando um módulo do PowerShell.

Regras para instalar módulos

As informações a seguir pertencem a todos os módulos, incluindo módulos que você cria para seu próprio uso, módulos que você obtém de outras partes e módulos que você distribui para outras pessoas.

Instalar módulos no PSModulePath

Sempre que possível, instale todos os módulos em um caminho listado na variável de ambiente PSModulePath ou adicione o caminho do módulo ao PSModulePath valor da variável de ambiente.

A variável de ambiente PSModulePath ($Env:PSModulePath) contém os locais dos módulos do Windows PowerShell. Os cmdlets dependem do valor dessa variável de ambiente para localizar módulos.

Por padrão, o PSModulePath valor de variável de ambiente contém os diretórios de módulo do sistema e do usuário a seguir, mas você pode adicionar e editar o valor.

  • $PSHOME\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules)

    Aviso

    Esse local é reservado para módulos que são fornecidos com o Windows. Não instale módulos neste local.

  • $HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)

  • $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

    Para obter o valor da variável de ambiente PSModulePath, use um dos comandos a seguir.

    $Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")

    Para adicionar um caminho de módulo ao valor do PSModulePath valor de variável de ambiente, use o seguinte formato de comando. Esse formato usa o método SetEnvironmentVariable da classe System.Environment para fazer uma alteração independente de sessão para a variável de ambiente PSModulePath.

    #Save the current value in the $p variable.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")

#Add the new path to the $p variable. Begin with a semi-colon separator.
$p += ";C:\Program Files (x86)\MyCompany\Modules\"

#Add the paths in $p to the PSModulePath value.
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

    Importante

    Depois de adicionar o caminho para PSModulePath, você deverá transmitir uma mensagem de ambiente sobre a alteração. A transmissão da alteração permite que outros aplicativos, como o shell, peguem a alteração. Para transmitir a alteração, faça com que o código de instalação do produto envie uma mensagem WM_SETTINGCHANGE com lParam definido como a cadeia de caracteres "Ambiente". Envie a mensagem depois que o código de instalação do módulo for atualizado PSModulePath.

Usar o nome correto do diretório do módulo

Um módulo bem formado é um módulo armazenado em um diretório que tem o mesmo nome que o nome base de pelo menos um arquivo no diretório do módulo. Se um módulo não estiver bem formado, o Windows PowerShell não o reconhecerá como um módulo.

O "nome base" de um arquivo é o nome sem a extensão de nome de arquivo. Em um módulo bem formado, o nome do diretório que contém os arquivos de módulo deve corresponder ao nome base de pelo menos um arquivo no módulo.

Por exemplo, no módulo fabrikam de exemplo, o diretório que contém os arquivos do módulo é chamado "Fabrikam" e pelo menos um arquivo tem o nome base "Fabrikam". Nesse caso, tanto Fabrikam.psd1 quanto Fabrikam.dll têm o nome base "Fabrikam".

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Efeito da instalação incorreta

Se o módulo não estiver bem formado e sua localização não estiver incluída no valor do PSModulePath variável de ambiente, os recursos básicos de descoberta do Windows PowerShell, como o seguinte, não funcionarão.

  • O recurso de Carregamento Automático do Módulo não pode importar o módulo automaticamente.

  • O parâmetro ListAvailable do cmdlet do Get-Module não pode localizar o módulo.

  • O cmdlet Import-Module não pode localizar o módulo. Para importar o módulo, você deve fornecer o caminho completo para o arquivo de módulo raiz ou o arquivo de manifesto do módulo.

    Recursos adicionais, como o seguinte, não funcionam a menos que o módulo seja importado para a sessão. Em módulos bem formados na variável de ambiente PSModulePath, esses recursos funcionam mesmo quando o módulo não é importado para a sessão.

  • O cmdlet Get-Command não pode encontrar comandos no módulo.

  • Os cmdlets de Ajuda de Atualização e save-help não podem atualizar nem salvar ajuda para o módulo.

  • O cmdlet Show-Command não pode localizar e exibir os comandos no módulo.

    Os comandos no módulo estão ausentes na janela Show-Command no ISE (Ambiente de Script Integrado) do Windows PowerShell.

Onde instalar módulos

Esta seção explica onde no sistema de arquivos instalar módulos do Windows PowerShell. O local depende de como o módulo é usado.

Instalando módulos para um usuário específico

Se você criar seu próprio módulo ou obter um módulo de outra parte, como um site da comunidade do Windows PowerShell, e quiser que o módulo esteja disponível apenas para sua conta de usuário, instale o módulo no diretório módulos específicos do usuário.

$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

O diretório módulos específicos do usuário é adicionado ao valor da variável de ambiente PSModulePath por padrão.

Instalando módulos para todos os usuários em arquivos de programas

Se você quiser que um módulo esteja disponível para todas as contas de usuário no computador, instale o módulo no local dos Arquivos de Programas.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Observação

O local dos Arquivos de Programas é adicionado ao valor da variável de ambiente PSModulePath por padrão no Windows PowerShell 4.0 e posterior. Para versões anteriores do Windows PowerShell, você pode criar manualmente o local dos Arquivos de Programas (%ProgramFiles%\WindowsPowerShell\Modules) e adicionar esse caminho à variável de ambiente PSModulePath, conforme descrito acima.

Instalando módulos em um diretório de produtos

Se você estiver distribuindo o módulo para outras partes, use o local padrão de Arquivos de Programas descrito acima ou crie seu próprio subdiretório específico da empresa ou específico do produto do diretório %ProgramFiles%.

Por exemplo, a Fabrikam Technologies, uma empresa fictícia, está enviando um módulo do Windows PowerShell para seu produto Fabrikam Manager. O instalador de módulo cria um subdiretório módulos no subdiretório de produtos do Fabrikam Manager.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Para habilitar os recursos de descoberta do módulo do Windows PowerShell para localizar o módulo Fabrikam, o instalador do módulo Fabrikam adiciona o local do módulo ao valor da variável de ambiente PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Instalando módulos no Common Files Directory

Se um módulo for usado por vários componentes de um produto ou por várias versões de um produto, instale o módulo em um subdiretório específico do módulo do subdiretório %ProgramFiles%\Common Files\Modules.

No exemplo a seguir, o módulo Fabrikam é instalado em um subdiretório Fabrikam do subdiretório %ProgramFiles%\Common Files\Modules. Observe que cada módulo reside em seu próprio subdiretório no subdiretório Módulos.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

Em seguida, o instalador garante o valor da variável de ambiente PSModulePath inclui o caminho do subdiretório Common Files\Modules.

$m = $Env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notcontains $m) {
    $q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)

Instalando várias versões de um módulo

Para instalar várias versões do mesmo módulo, use o procedimento a seguir.

  1. Crie um diretório para cada versão do módulo. Inclua o número da versão no nome do diretório.
  2. Crie um manifesto de módulo para cada versão do módulo. No valor da chave ModuleVersion no manifesto, insira o número da versão do módulo. Salve o arquivo de manifesto (.psd1) no diretório específico da versão do módulo.
  3. Adicione o caminho da pasta raiz do módulo ao valor da variável de ambiente PSModulePath, conforme mostrado nos exemplos a seguir.

Para importar uma versão específica do módulo, o usuário final pode usar os parâmetros MinimumVersion ou RequiredVersion do cmdlet Import-Module.

Por exemplo, se o módulo Fabrikam estiver disponível nas versões 8.0 e 9.0, a estrutura do diretório do módulo Fabrikam poderá ser semelhante à seguinte.

C:\Program Files
Fabrikam Manager
 Fabrikam8
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
     Fabrikam.dll (module assembly)
 Fabrikam9
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
     Fabrikam.dll (module assembly)

O instalador adiciona os dois caminhos do módulo ao valor da variável de ambiente PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Quando essas etapas são concluídas, o parâmetro ListAvailable do cmdlet get-module obtém os dois módulos da Fabrikam. Para importar um módulo específico, use os parâmetros MinimumVersion ou RequiredVersion do cmdlet Import-Module.

Se ambos os módulos forem importados para a mesma sessão e os módulos contiverem cmdlets com os mesmos nomes, os cmdlets importados por último entrarão em vigor na sessão.

Manipulando conflitos de nome de comando

Conflitos de nome de comando podem ocorrer quando os comandos exportados por um módulo têm o mesmo nome que os comandos na sessão do usuário.

Quando uma sessão contém dois comandos que têm o mesmo nome, o Windows PowerShell executa o tipo de comando que tem precedência. Quando uma sessão contém dois comandos que têm o mesmo nome e o mesmo tipo, o Windows PowerShell executa o comando que foi adicionado à sessão mais recentemente. Para executar um comando que não é executado por padrão, os usuários podem qualificar o nome do comando com o nome do módulo.

Por exemplo, se a sessão contiver uma função Get-Date e o cmdlet Get-Date, o Windows PowerShell executará a função por padrão. Para executar o cmdlet, preceda o comando com o nome do módulo, como:

Microsoft.PowerShell.Utility\Get-Date

Para evitar conflitos de nome, os autores do módulo podem usar a chave DefaultCommandPrefix no manifesto do módulo para especificar um prefixo substantivo para todos os comandos exportados do módulo.

Os usuários podem usar o parâmetro Prefixo do cmdlet Import-Module para usar um prefixo alternativo. O valor do parâmetro prefixo tem precedência sobre o valor da chave DefaultCommandPrefix.

Caminhos de suporte em sistemas que não são do Windows

Plataformas não Windows usam o caractere dois-pontos (:) como separador de caminho e um caractere de barra (/) como separador de diretório. A classe [System.IO.Path] tem membros estáticos que podem ser usados para fazer seu código funcionar em qualquer plataforma:

  • [System.IO.Path]::PathSeparator - retorna o caractere usado para separar caminhos em uma variável de ambiente PATH para a plataforma de host
  • [System.IO.Path]::DirectorySeparatorChar - retorna o caractere usado para separar nomes de diretório com um caminho para a plataforma de host

Use essas propriedades estáticas no lugar dos caracteres ; e \ ao construir cadeias de caracteres de caminho.

Consulte Também

about_Command_Precedence

escrevendo um módulo do Windows PowerShell