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 salva em um único diretório). Ao definir um conjunto de arquivos de script relacionados, assemblies e recursos relacionados como um módulo, você pode referenciar, carregar, persistir e compartilhar seu código muito mais fácil do que faria de outra forma.

A principal finalidade 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 controlar (ou seja, tornar público ou privado) as funções e variáveis contidas no script. Salvar o script como um arquivo .psm1 também permite controlar o escopo de determinadas variáveis. Por fim, 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ódulo

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 desses componentes, por si só, são realmente necessários. 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 não passa de 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 combinando e combinando as diferentes partes possíveis de um módulo.

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 script 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 runtime. Os arquivos de manifesto também são úteis para acompanhar metadados, como informações de criação e controle de versão.

Por fim, um módulo de script, como qualquer outro módulo que não é criado dinamicamente, precisa ser salvo em uma pasta que o PowerShell pode descobrir razoavelmente. Normalmente, isso está 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 módulo binário é um assembly do .NET Framework (.dll) que contém código compilado, como C#. Os desenvolvedores de cmdlet podem usar esse tipo de módulo para compartilhar cmdlets, provedores e muito mais. (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 que você crie cmdlets que sejam mais rápidos ou usem recursos (como multithreading) que não são tão fáceis de codificar em scripts do Windows PowerShell.

Assim como acontece com os módulos de script, você pode incluir um arquivo de manifesto para descrever recursos adicionais usados pelo módulo e acompanhar 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 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 de módulo do PowerShell.

Módulos dinâmicos

Um módulo dinâmico é um módulo do qual 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 precise 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 do módulo é um arquivo .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.

  Manifestos não são necessários para um módulo. Os módulos podem referenciar arquivos de script (.ps1), arquivos de módulo de script (.psm1), arquivos de manifesto (.psd1), arquivos de formatação e tipo (.ps1xml), assemblies de cmdlet e provedor (.dll), arquivos de recurso, arquivos de ajuda, arquivos de localização ou qualquer outro tipo de arquivo ou recurso que seja agrupado 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á referenciar os vários arquivos como uma única unidade fazendo referência ao manifesto.

  O manifesto em si 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 aos 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 de módulo do PowerShell.

Armazenando e instalando um módulo

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

De 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 ao chamar Install-Module.

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

• 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 de 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.

novo módulo cmdlet Esse 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, estão imediatamente disponíveis na sessão e permanecem disponíveis até que a sessão seja fechada.

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 que podem ser importados para a sessão atual.

Export-ModuleMember cmdlet Este cmdlet especifica os membros do módulo (como cmdlets, funções, variáveis e aliases) 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 os módulos da sessão atual.

Test-ModuleManifest cmdlet 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 Essa variável contém o diretório 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 Esta variável de ambiente contém uma lista dos diretórios nos quais os módulos do Windows PowerShell sã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.

Consulte Também

escrevendo um módulo do Windows PowerShell