How to Write a PowerShell Binary Module (Como Escrever um Módulo Binário do PowerShell)

Um módulo binário pode ser qualquer assembly (.dll) que contenha classes de cmdlet. Por padrão, todos os cmdlets no assembly são importados quando o módulo binário é importado. No entanto, você pode restringir os cmdlets importados criando um manifesto de módulo cujo módulo raiz é o assembly. (Por exemplo, a chave CmdletsToExport do manifesto pode ser usada para exportar apenas os cmdlets necessários.) Além disso, um módulo binário pode conter arquivos adicionais, uma estrutura de diretórios e outras informações de gerenciamento úteis que um único cmdlet não pode.

O procedimento a seguir descreve como criar e instalar um módulo binário do PowerShell.

Como criar e instalar um módulo binário do PowerShell

1. Crie uma solução binária do PowerShell (como um cmdlet escrito em C#), com os recursos necessários, e certifique-se de que ela seja executada corretamente.

   De uma perspetiva de código, o núcleo de um módulo binário é um assembly de cmdlet. Na verdade, o PowerShell trata um único assembly de cmdlet como um módulo para carga e descarga, sem esforço adicional por parte do desenvolvedor. Para obter mais informações sobre como escrever um cmdlet, consulte Escrevendo um cmdlet do Windows PowerShell.

2. Se necessário, crie o restante da solução: (cmdlets adicionais, arquivos XML e assim por diante) e descreva-os com um manifesto de módulo.

   Além de descrever os assemblies de cmdlet em sua solução, um manifesto de módulo pode descrever como você deseja que o módulo seja exportado e importado, quais cmdlets serão expostos e quais arquivos adicionais entrarão no módulo. No entanto, como dito anteriormente, o PowerShell pode tratar um cmdlet binário como um módulo sem esforço adicional. Como tal, um manifesto de módulo é útil principalmente para combinar vários arquivos em um único pacote, ou para controlar explicitamente a publicação para um determinado assembly. Para obter mais informações, consulte Como escrever um manifesto do módulo PowerShell.

   O código a seguir é um exemplo simplificado de C# que contém três cmdlets no mesmo arquivo que podem ser usados como um módulo.

   using System.Management.Automation;           // Windows PowerShell namespace.
   
   namespace ModuleCmdlets
   {
     [Cmdlet(VerbsDiagnostic.Test,"BinaryModuleCmdlet1")]
     public class TestBinaryModuleCmdlet1Command : Cmdlet
     {
       protected override void BeginProcessing()
       {
         WriteObject("BinaryModuleCmdlet1 exported by the ModuleCmdlets module.");
       }
     }
   
     [Cmdlet(VerbsDiagnostic.Test, "BinaryModuleCmdlet2")]
     public class TestBinaryModuleCmdlet2Command : Cmdlet
     {
         protected override void BeginProcessing()
         {
             WriteObject("BinaryModuleCmdlet2 exported by the ModuleCmdlets module.");
         }
     }
   
     [Cmdlet(VerbsDiagnostic.Test, "BinaryModuleCmdlet3")]
     public class TestBinaryModuleCmdlet3Command : Cmdlet
     {
         protected override void BeginProcessing()
         {
             WriteObject("BinaryModuleCmdlet3 exported by the ModuleCmdlets module.");
         }
     }
   
   }
   

3. Empacote sua solução e salve-o em algum lugar no caminho do módulo do PowerShell.

   A $env:PSModulePath variável de ambiente global descreve os caminhos padrão que o PowerShell usa para localizar seu módulo. Por exemplo, um caminho comum para salvar um módulo em um sistema seria %SystemRoot%\Users\<user>\Documents\WindowsPowerShell\Modules\<moduleName>. Se você não usar os caminhos padrão, precisará declarar explicitamente o local do módulo durante a instalação. Certifique-se de criar uma pasta para salvar o módulo, pois você pode precisar da pasta para armazenar vários assemblies e arquivos para sua solução.

   Tecnicamente, você não precisa instalar seu módulo em nenhum lugar no - esses são simplesmente os locais padrão que o $env:PSModulePath PowerShell procurará por seu módulo. No entanto, é considerado uma boa prática fazê-lo, a menos que você tenha um bom motivo para armazenar seu módulo em outro lugar. Para obter mais informações, consulte Instalando um módulo do PowerShell e about_PSModulePath.

4. Importe seu módulo para o PowerShell com uma chamada para Import-Module.

   Chamar para Import-Module carrega o módulo na memória ativa. Se você estiver usando o PowerShell 3.0 e posterior, invocar um comando do seu módulo no código também o importa. Para obter mais informações, consulte Importando um módulo do PowerShell.

Inicialização do módulo e código de limpeza

Se o módulo precisar fazer algo após a importação ou remoção, como uma tarefa de descoberta ou inicialização, você poderá implementar as IModuleAssemblyInitializer interfaces e IModuleAssemblyCleanup .

Observação

Este padrão é desencorajado, a menos que seja absolutamente necessário. Para manter o desempenho do PowerShell, você deve carregar preguiçosamente as coisas no ponto em que seus comandos são chamados, em vez de na importação.

Importando assemblies de snap-in como módulos

Os cmdlets e provedores que existem em assemblies de snap-in podem ser carregados como módulos binários. Quando os assemblies de snap-in são carregados como módulos binários, os cmdlets e provedores no snap-in ficam disponíveis para o usuário, mas a classe de snap-in no assembly é ignorada e o snap-in não é registrado. Como resultado, os cmdlets de snap-in fornecidos pelo Windows PowerShell não podem detetar o snap-in, mesmo que os cmdlets e provedores estejam disponíveis para a sessão.

Além disso, qualquer formatação ou tipos de arquivos referenciados pelo snap-in não podem ser importados como parte de um módulo binário. Para importar os arquivos de formatação e tipos, você deve criar um manifesto de módulo. Consulte Como escrever um manifesto do módulo PowerShell.

Ver também

• Escrevendo um módulo do Windows PowerShell