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

Um módulo é um conjunto de funcionalidades Windows PowerShell relacionadas, 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 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 Windows PowerShell código. Por exemplo, a maneira mais básica de criar um módulo é simplesmente salvar um script Windows PowerShell como um arquivo .psm1. Isso permite controlar (ou seja, tornar públicas ou privadas) as funções e as 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 do módulo

Um módulo é feito de 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 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ó, é realmente necessário. Por exemplo, um módulo pode tecnicamente ser apenas um script armazenado em um arquivo .psm1. Você também pode ter um módulo que não é nada além 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 no qual armazenar nada. As seções a seguir descrevem os tipos de módulos que você pode obter combinando e correspondendo 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 ( ) que contém qualquer código Windows PowerShell .psm1 válido. 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 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 controle de versão e de autor.

Por fim, um módulo de script, como qualquer outro módulo que não seja criado dinamicamente, precisa ser salvo em uma pasta que o PowerShell possa 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 How to Write a PowerShell Script Module.

Módulos binários

Um módulo binário é um assembly .NET Framework ( ) que contém código .dll 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 que você crie cmdlets mais rápidos ou use recursos (como multithreading) que não são tão fáceis de codificar em scripts Windows PowerShell.

Assim como nos módulos de script, você pode incluir um arquivo de manifesto para descrever recursos adicionais que seu módulo usa e acompanhar metadados sobre seu 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 How to How to Write a PowerShell Binary Module.

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 ModuleToProcess o elemento ou do manifesto RootModule 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 agrupar recursos que outros módulos usarão, como módulos aninhados, assemblies, tipos ou formatos. Para obter mais informações, consulte How to Write a PowerShell Module Manifest.

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 Get-Module cmdlet . 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 de módulo

Um manifesto do módulo é um arquivo que contém uma tabela de .psd1 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 ( ), arquivos de módulo de script ( ), arquivos de manifesto ( ), arquivos de formatação e de tipo .ps1 .psm1 ( ), .psd1 .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 module 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 referenciando o manifesto.

    O manifesto em si descreve as seguintes categorias de informações:

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

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

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

  • Restrições aos membros do módulo a exportar, como aliases, funções, variáveis e cmdlets a exportar.

    Para obter mais informações, consulte How to Write a PowerShell Module Manifest.

Armazenar e instalar 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 em que Windows PowerShell está instalado ou pode ser armazenado em uma pasta de usuário.

Em termos gerais, você pode determinar onde deve instalar seu módulo usando um dos caminhos armazenados na $ENV:PSModulePath variável . Usar um desses caminhos significa que o PowerShell pode encontrar 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á explicitamente permitir que o PowerShell saiba passando o local do módulo como um parâmetro ao chamar Install-Module .

Independentemente disso, o caminho da pasta é conhecido como a 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 New-Module cmdlet podem ser nomeados Name usando o parâmetro do cmdlet .

  • Os módulos importados de objetos de assembly Import-Module -Assembly pelo comando 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 as 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 fechada.

Cmdlet New-ModuleManifest Esse cmdlet cria um novo arquivo de manifesto do módulo (.psd1), popula 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.

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 New-Module cmdlet .

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

Cmdlet Test-ModuleManifest Esse cmdlet verifica se um manifesto do 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 Essa variável de ambiente contém uma lista dos diretórios nos quais Windows PowerShell módulos são armazenados. 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

Escrever um módulo do Windows PowerShell