Noções básicas sobre um módulo do Windows PowerShell

Um módulo é um conjunto de funcionalidades relacionadas do Windows PowerShell, agrupadas como uma unidade conveniente (geralmente salvas em um único diretório). Ao definir um conjunto de arquivos de script relacionados, assemblies e recursos relacionados como um módulo, você pode fazer referência, carregar, persistir e compartilhar seu código muito mais facilmente do que faria de outra forma.

O principal objetivo de um módulo é permitir a modularização (ou seja, reutilização e abstração) do código do Windows PowerShell. Por exemplo, a maneira mais básica de criar um módulo é simplesmente salvar um script do Windows PowerShell como um arquivo .psm1. Isso permite que você controle (ou seja, torne públicas ou privadas) as funções e variáveis contidas no script. Salvar o script como um arquivo de .psm1 também permite controlar o escopo de determinadas variáveis. Finalmente, você também pode usar cmdlets como Install-Module para organizar, instalar e usar seu script como blocos de construção para soluções maiores.

Componentes e tipos de módulos

Um módulo é composto por quatro componentes básicos:

1. Algum tipo de arquivo de código - geralmente um script do PowerShell ou um assembly de cmdlet gerenciado.

2. Qualquer outra coisa que o arquivo de código acima possa precisar, como assemblies adicionais, arquivos de ajuda ou scripts.

3. Um arquivo de manifesto que descreve os arquivos acima, bem como armazena metadados, como informações de autor e controle de versão.

4. Um diretório que contém todo o conteúdo acima e está localizado onde o PowerShell pode encontrá-lo razoavelmente.

   Observação

   Nenhum destes componentes, por si só, é realmente necessário. Por exemplo, tecnicamente um módulo pode ser apenas um script armazenado em um arquivo .psm1. Você também pode ter um módulo que nada mais é do que um arquivo de manifesto, que é usado principalmente para fins organizacionais. Você também pode escrever um script que cria dinamicamente um módulo e, como tal, não precisa de um diretório para armazenar nada. As seções a seguir descrevem os tipos de módulos que você pode obter misturando e combinando as diferentes partes possíveis de um módulo juntas.

Módulos de script

Como o nome indica, um módulo de script é um arquivo (.psm1) que contém qualquer código válido do Windows PowerShell. Os desenvolvedores e administradores de scripts podem usar esse tipo de módulo para criar módulos cujos membros incluem funções, variáveis e muito mais. No fundo, um módulo de script é simplesmente um script do Windows PowerShell com uma extensão diferente, que permite que os administradores usem funções de importação, exportação e gerenciamento nele.

Além disso, você pode usar um arquivo de manifesto para incluir outros recursos em seu módulo, como arquivos de dados, outros módulos dependentes ou scripts de tempo de execução. Os arquivos de manifesto também são úteis para rastrear metadados, como informações de criação e controle de versão.

Finalmente, um módulo de script, como qualquer outro módulo que não é criado dinamicamente, precisa ser salvo em uma pasta que o PowerShell possa razoavelmente descobrir. Normalmente, isso ocorre no caminho do módulo do PowerShell; mas, se necessário, você pode descrever explicitamente onde o módulo está instalado. Para obter mais informações, consulte Como escrever um módulo de script do PowerShell.

Módulos binários

Um de módulo binário é um assembly do .NET Framework (.dll) que contém código compilado, como C#. Os desenvolvedores de cmdlets podem usar esse tipo de módulo para compartilhar cmdlets, provedores e muito mais. (Os snap-ins existentes também podem ser usados como módulos binários.) Em comparação com um módulo de script, um módulo binário permite criar cmdlets mais rápidos ou usar recursos (como multithreading) que não são tão fáceis de codificar em scripts do Windows PowerShell.

Assim como nos módulos de script, você pode incluir um arquivo de manifesto para descrever recursos adicionais que o módulo usa e para controlar metadados sobre o módulo. Da mesma forma, você provavelmente deve instalar seu módulo binário em uma pasta em algum lugar ao longo do caminho do módulo do PowerShell. Para obter mais informações, consulte Como Como escrever um módulo binário do PowerShell.

Módulos de manifesto

Um de módulo de manifesto é um módulo que usa um arquivo de manifesto para descrever todos os seus componentes, mas não tem nenhum tipo de assembly ou script principal. (Formalmente, um módulo de manifesto deixa o elemento ModuleToProcess ou RootModule do manifesto vazio.) No entanto, você ainda pode usar os outros recursos de um módulo, como a capacidade de carregar assemblies dependentes ou executar automaticamente determinados scripts de pré-processamento. Você também pode usar um módulo de manifesto como uma maneira conveniente de empacotar recursos que outros módulos usarão, como módulos aninhados, assemblies, tipos ou formatos. Para obter mais informações, consulte Como escrever um manifesto do módulo PowerShell.

Módulos dinâmicos

Um módulo dinâmico é um módulo que não é carregado ou salvo em um arquivo. Em vez disso, eles são criados dinamicamente por um script, usando o cmdlet New-Module. Esse tipo de módulo permite que um script crie um módulo sob demanda que não precisa ser carregado ou salvo no armazenamento persistente. Por sua natureza, um módulo dinâmico destina-se a ser de curta duração e, portanto, não pode ser acessado pelo cmdlet Get-Module. Da mesma forma, eles geralmente não precisam de manifestos de módulo, nem provavelmente precisam de pastas permanentes para armazenar seus assemblies relacionados.

Manifestos do módulo

Um manifesto de módulo é um arquivo de .psd1 que contém uma tabela de hash. As chaves e os valores na tabela de hash fazem o seguinte:

• Descreva o conteúdo e os atributos do módulo.

• Defina os pré-requisitos.

• Determine como os componentes são processados.

  Os manifestos não são necessários para um módulo. Os módulos podem fazer referência a arquivos de script (.ps1), arquivos de módulo de script (.psm1), arquivos de manifesto (.psd1), formatação e arquivos de tipo (.ps1xml), assemblies de cmdlet e provedor (.dll), arquivos de recursos, arquivos de Ajuda, arquivos de localização ou qualquer outro tipo de arquivo ou recurso que seja empacotado como parte do módulo. Para um script internacionalizado, a pasta do módulo também contém um conjunto de arquivos de catálogo de mensagens. Se você adicionar um arquivo de manifesto à pasta do módulo, poderá fazer referência aos vários arquivos como uma única unidade fazendo referência ao manifesto.

  O próprio manifesto descreve as seguintes categorias de informações:

• Metadados sobre o módulo, como o número da versão do módulo, o autor e a descrição.

• Pré-requisitos necessários para importar o módulo, como a versão do Windows PowerShell, a versão CLR (Common Language Runtime) e os módulos necessários.

• Diretivas de processamento, como scripts, formatos e tipos a serem processados.

• Restrições sobre os membros do módulo a serem exportados, como aliases, funções, variáveis e cmdlets a serem exportados.

  Para obter mais informações, consulte Como escrever um manifesto do módulo PowerShell.

Armazenando e instalando um módulo

Depois de criar um módulo de script, binário ou manifesto, você pode salvar seu trabalho em um local que outras pessoas possam acessá-lo. Por exemplo, seu módulo pode ser armazenado na pasta do sistema onde o Windows PowerShell está instalado ou pode ser armazenado em uma pasta de usuário.

De um modo geral, você pode determinar onde deve instalar o módulo usando um dos caminhos armazenados na variável $Env:PSModulePath. Usar um desses caminhos significa que o PowerShell pode localizar e carregar automaticamente seu módulo quando um usuário faz uma chamada para ele em seu código. Se você armazenar seu módulo em outro lugar, poderá informar explicitamente o PowerShell passando o local do módulo como um parâmetro quando chamar Install-Module.

Independentemente disso, o caminho da pasta é referido como o base do módulo (ModuleBase), e o nome do arquivo de módulo de script, binário ou manifesto deve ser o mesmo que o nome da pasta do módulo, com as seguintes exceções:

• Os módulos dinâmicos criados pelo cmdlet New-Module podem ser nomeados usando o parâmetro Name do cmdlet.

• Os módulos importados de objetos assembly pelo comando Import-Module -Assembly são nomeados de acordo com a seguinte sintaxe: "dynamic_code_module_" + assembly.GetName().

  Para obter mais informações, consulte Instalando um módulo do PowerShell e about_PSModulePath.

Cmdlets e variáveis do módulo

Os cmdlets e variáveis a seguir são fornecidos pelo Windows PowerShell para a criação e o gerenciamento de módulos.

cmdlet New-Module Este cmdlet cria um novo módulo dinâmico que existe apenas na memória. O módulo é criado a partir de um bloco de script, e seus membros exportados, como suas funções e variáveis, ficam imediatamente disponíveis na sessão e permanecem disponíveis até que a sessão seja encerrada.

cmdlet New-ModuleManifest Este cmdlet cria um novo arquivo de manifesto de módulo (.psd1), preenche seus valores e salva o arquivo de manifesto no caminho especificado. Esse cmdlet também pode ser usado para criar um modelo de manifesto de módulo que pode ser preenchido manualmente.

cmdlet Import-Module Este cmdlet adiciona um ou mais módulos à sessão atual.

cmdlet Get-Module Este cmdlet recupera informações sobre os módulos que foram ou podem ser importados para a sessão atual.

cmdlet Export-ModuleMember Este cmdlet especifica os membros do módulo (como cmdlets, funções, variáveis e aliases) que são exportados de um arquivo de módulo de script (.psm1) ou de um módulo dinâmico criado usando o cmdlet New-Module.

cmdlet Remove-Module Este cmdlet remove módulos da sessão atual.

cmdlet Test-ModuleManifest Este cmdlet verifica se um manifesto de módulo descreve com precisão os componentes de um módulo, verificando se os arquivos listados no arquivo de manifesto do módulo (.psd1) realmente existem nos caminhos especificados.

$PSScriptRoot Esta variável contém o diretório a partir do qual o módulo de script está sendo executado. Ele permite que os scripts usem o caminho do módulo para acessar outros recursos.

$Env:PSModulePath Essa variável de ambiente contém uma lista dos diretórios nos quais os módulos do Windows PowerShell estão armazenados. O Windows PowerShell usa o valor dessa variável ao importar módulos automaticamente e atualizar tópicos da Ajuda para módulos.

Ver também

Escrevendo um módulo do Windows PowerShell