Cómo escribir un módulo binario de PowerShell

Un módulo binario puede ser cualquier ensamblado (.dll) que contenga clases de cmdlet. De forma predeterminada, todos los cmdlets del ensamblado se importan cuando se importa el módulo binario. Sin embargo, puede restringir los cmdlets importados mediante la creación de un manifiesto de módulo cuyo módulo raíz es el ensamblado. (Por ejemplo, la clave CmdletsToExport del manifiesto se puede usar para exportar solo los cmdlets necesarios). Además, un módulo binario puede contener archivos adicionales, una estructura de directorios y otras partes de información de administración útil que un único cmdlet no puede.

En el procedimiento siguiente se describe cómo crear e instalar un módulo binario de PowerShell.

Creación e instalación de un módulo binario de PowerShell

1. Cree una solución de PowerShell binaria (por ejemplo, un cmdlet escrito en C#), con las funcionalidades que necesita y asegúrese de que se ejecuta correctamente.

   Desde una perspectiva de código, el núcleo de un módulo binario es un ensamblado de cmdlet. De hecho, PowerShell trata un único ensamblado de cmdlet como módulo para cargar y descargar, sin ningún esfuerzo adicional por parte del desarrollador. Para obtener más información sobre cómo escribir un cmdlet, consulte Escritura de un cmdlet de Windows PowerShell.

2. Si es necesario, cree el resto de la solución: (cmdlets adicionales, archivos XML, etc.) y describa con un manifiesto de módulo.

   Además de describir los ensamblados de cmdlet de la solución, un manifiesto de módulo puede describir cómo desea que el módulo se exporte e importe, qué cmdlets se van a exponer y qué archivos adicionales se incluirán en el módulo. Como se indicó anteriormente, PowerShell puede tratar un cmdlet binario como un módulo sin esfuerzo adicional. Por lo tanto, un manifiesto de módulo es útil principalmente para combinar varios archivos en un único paquete o para controlar explícitamente la publicación de un ensamblado determinado. Para obtener más información, consulte Cómo escribir un manifiesto de módulo de PowerShell.

   El código siguiente es un ejemplo simplificado de C# que contiene tres cmdlets en el mismo archivo que se pueden usar como 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. Empaquete la solución y guarde el paquete en algún lugar de la ruta de acceso del módulo de PowerShell.

   La $env:PSModulePath variable de entorno global describe las rutas de acceso predeterminadas que Usa PowerShell para localizar el módulo. Por ejemplo, una ruta de acceso común para guardar un módulo en un sistema sería %SystemRoot%\Users\<user>\Documents\WindowsPowerShell\Modules\<moduleName>. Si no usa las rutas de acceso predeterminadas, debe indicar explícitamente la ubicación del módulo durante la instalación. Asegúrese de crear una carpeta en la que guardar el módulo, ya que es posible que necesite la carpeta para almacenar varios ensamblados y archivos para la solución.

   Técnicamente, no es necesario instalar el módulo en ningún lugar, $env:PSModulePath ya que son simplemente las ubicaciones predeterminadas que PowerShell buscará en el módulo. Sin embargo, se considera un procedimiento recomendado para hacerlo, a menos que tenga una buena razón para almacenar el módulo en otro lugar. Para obtener más información, consulte Instalación de un módulo de PowerShell y about_PSModulePath.

4. Importe el módulo en PowerShell con una llamada a Import-Module.

   Al llamar a Import-Module , se carga el módulo en la memoria activa. Si usa PowerShell 3.0 y versiones posteriores, invocar un comando desde el módulo en el código también lo importa. Para obtener más información, consulte Importación de un módulo de PowerShell.

Inicialización y limpieza del módulo

Si el módulo necesita hacer algo tras la importación o eliminación, como una tarea de detección o una inicialización, puede implementar las IModuleAssemblyInitializer interfaces y IModuleAssemblyCleanup .

Importación de ensamblados de complemento como módulos

Los cmdlets y proveedores que existen en los ensamblados de complemento se pueden cargar como módulos binarios. Cuando los ensamblados de complemento se cargan como módulos binarios, los cmdlets y proveedores del complemento están disponibles para el usuario, pero la clase de complemento del ensamblado se omite y el complemento no está registrado. Como resultado, los cmdlets de complemento proporcionados por Windows PowerShell no pueden detectar el complemento aunque los cmdlets y proveedores estén disponibles para la sesión.

Además, los archivos de formato o tipos a los que hace referencia el complemento no se pueden importar como parte de un módulo binario. Para importar los archivos de formato y tipos, debe crear un manifiesto de módulo. Consulte Cómo escribir un manifiesto de módulo de PowerShell.

Véase también

• escribir un módulo de Windows PowerShell