Como escrever um módulo binário do Windows 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ório e outras partes de 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 verifique se ela é executada corretamente.

   Do ponto de vista do 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 carregamento e descarregamento, sem esforço adicional por parte do desenvolvedor. Para obter mais informações sobre como escrever um cmdlet, consulte Escrever 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 seu módulo seja exportado e importado, quais cmdlets serão expostos e quais arquivos adicionais entrarão no módulo. Como indicado anteriormente, no entanto, o PowerShell pode tratar um cmdlet binário como um módulo sem esforço adicional. Dessa forma, um manifesto de módulo é útil principalmente para combinar vários arquivos em um único pacote ou para controlar explicitamente a publicação de um determinado assembly. Para obter mais informações, consulte Como escrever um manifesto de módulo do PowerShell.

   O código a seguir é um exemplo de C# simplificado 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 pacote 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. Crie uma pasta para salvar o módulo, pois talvez seja necessário que a pasta armazene vários assemblies e arquivos para sua solução.

   Tecnicamente, você não precisa instalar seu módulo em qualquer lugar no $env:PSModulePath – esses são simplesmente os locais padrão que o PowerShell procurará pelo módulo. No entanto, é considerado uma prática recomendada fazer isso, 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 o Import-Module carrega seu módulo na memória ativa. Se você estiver usando o PowerShell 3.0 e posterior, invocar um comando do módulo no código também o importará. Para obter mais informações, consulte Importar um módulo do PowerShell.

Código de inicialização e limpeza do módulo

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 o e IModuleAssemblyInitializer as IModuleAssemblyCleanup interfaces.

Observação

Esse 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 snap-in como módulos

Cmdlets e provedores que existem em assemblies snap-in podem ser carregados como módulos binários. Quando os assemblies snap-in são carregados como módulos binários, os cmdlets e provedores no snap-in estão disponíveis para o usuário, mas a classe 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 detectar 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 pode ser importado 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. Veja como gravar um manifesto do módulo do PowerShell.

Consulte Também

• escrevendo um módulo do Windows PowerShell