Partilhar via

Installing a PowerShell Module (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 um modo geral, isso consiste em copiar os arquivos do módulo (ou seja, o .psm1, ou o assembly binário, o manifesto do módulo e quaisquer outros arquivos associados) para 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, você pode querer usar um processo de instalação mais sofisticado. Independentemente de como você coloca 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 encontrar seu módulo. Para obter mais informações, consulte Importando um módulo do PowerShell.

Regras para instalação de módulos

As informações a seguir referem-se 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 valor da variável de ambiente PSModulePath.

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 valor da variável de ambiente PSModulePath contém os seguintes diretórios de módulo de sistema e usuário, mas você pode adicionar e editar o valor.

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

    Advertência

    Este local é reservado para módulos 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 do 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 da variável de ambiente PSModulePath, use o seguinte formato de comando. Esse formato usa o método SetEnvironmentVariable da classe System.Environment do 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ê deve transmitir uma mensagem de ambiente sobre a alteração. A transmissão da mudança permite que outros aplicativos, como o shell, peguem a mudança. Para difundir a alteração, peça ao código de instalação do produto que envie uma mensagem de WM_SETTINGCHANGE com lParam definida como a cadeia de caracteres "Ambiente". Certifique-se de enviar a mensagem após a atualização do código de instalação do módulo PSModulePath.

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

Um módulo bem formado é um módulo que é 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 do 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, Fabrikam.psd1 e 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 da variável de ambiente PSModulePath, os recursos básicos de descoberta do Windows PowerShell, como os seguintes, 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 Get-Module não consegue localizar o módulo.

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

    Recursos adicionais, como os seguintes, 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 consegue localizar comandos no módulo.

  • Os cmdlets Update-Help e Save-Help não podem atualizar ou salvar a ajuda do módulo.

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

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

Onde instalar módulos

Esta seção explica onde instalar os módulos do Windows PowerShell no sistema de arquivos. A localização 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 Modules específico do usuário.

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

O diretório Modules específico 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 desejar que um módulo esteja disponível para todas as contas de usuário no computador, instale o módulo no local Arquivos de Programas.

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

Observação

O local 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 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 Arquivos de Programas descrito acima ou crie seu próprio subdiretório específico da empresa ou 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 do módulo cria um subdiretório Modules no subdiretório do produto Fabrikam Manager.

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

Para permitir que os recursos de descoberta de módulo do Windows PowerShell localizem 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 diretório Common Files

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

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

Em seguida, o instalador garante o valor do PSModulePath variável de ambiente 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 de diretórios 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 ambos os caminhos do módulo ao PSModulePath valor da variável de ambiente.

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

Quando essas etapas estiverem concluídas, o parâmetro ListAvailable do cmdlet Get-Module obterá ambos os 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 contiverem cmdlets com os mesmos nomes, os cmdlets importados por último entrarão em vigor na sessão.

Manipulando conflitos de nome de comando

Os 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 com 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, prefacie 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 tecla DefaultCommandPrefix no manifesto do módulo para especificar um prefixo de substantivo para todos os comandos exportados do módulo.

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

Caminhos de suporte em sistemas que não sejam Windows

As plataformas que não são Windows usam o caractere dois pontos (:) como um separador de caminho e um caractere de barra (/) como um 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 host
  • [System.IO.Path]::DirectorySeparatorChar - retorna o caractere usado para separar nomes de diretório com um caminho para a plataforma host

Use essas propriedades estáticas para substituir os ; e \ caracteres quando estiver construindo cadeias de caracteres de caminho.

Ver também

sobre_Prioridade_de_Comandos

Escrevendo um módulo do Windows PowerShell

  • Last updated on