Comprender un módulo de Windows PowerShell

Un módulo es un conjunto de funcionalidades relacionadas de Windows PowerShell, agrupadas como una unidad conveniente (normalmente guardadas en un único directorio). Al definir un conjunto de archivos de script relacionados, ensamblados y recursos relacionados como un módulo, puede hacer referencia, cargar, persistir y compartir su código mucho más fácilmente que de otra manera.

El objetivo principal de un módulo es permitir la modularización (es decir, la reutilización y la abstracción) del código de Windows PowerShell. Por ejemplo, la forma más básica de crear un módulo es simplemente guardar un script de Windows PowerShell como un archivo .psm1. Hacerlo le permite controlar (es decir, hacer públicas o privadas) las funciones y variables contenidas en el script. Guardar el script como un archivo .psm1 también le permite controlar el alcance de ciertas variables. Finalmente, también puede usar cmdlets como Install-Module para organizar, instalar y usar su script como bloques de construcción para soluciones más grandes.

Componentes y tipos de módulos

Un módulo se compone de cuatro componentes básicos:

Algún tipo de archivo de código, normalmente un script de PowerShell o un ensamblado de cmdlet administrado.
Cualquier otra cosa que el archivo de código anterior pueda necesitar, como ensamblados, archivos de ayuda o scripts adicionales.
Un archivo de manifiesto que describe los archivos anteriores, además de almacenar metadatos, como información de autor y de versiones.
Un directorio que contiene todo el contenido anterior y está ubicado donde PowerShell pueda encontrarlo razonablemente.
Nota
Ninguno de estos componentes, por sí solos, es realmente necesario. Por ejemplo, técnicamente un módulo puede ser sólo un script almacenado en un archivo .psm1. También puede tener un módulo que no sea más que un archivo de manifiesto, que se utiliza principalmente con fines organizativos. También puede escribir un script que cree dinámicamente un módulo y, como tal, en realidad no necesita un directorio para almacenar nada. Las siguientes secciones describen los tipos de módulos que puede obtener mezclando y combinando las diferentes partes posibles de un módulo. .

Módulos de secuencias de comandos

Como su nombre lo indica, un módulo de script es un archivo (.psm1) que contiene cualquier código válido de Windows PowerShell. Los desarrolladores y administradores de scripts pueden utilizar este tipo de módulo para crear módulos cuyos miembros incluyan funciones, variables y más. En esencia, un módulo de secuencia de comandos es simplemente una secuencia de comandos de Windows PowerShell con una extensión diferente, que permite a los administradores utilizar funciones de importación, exportación y administración en él.

Además, puede utilizar un archivo de manifiesto para incluir otros recursos en su módulo, como archivos de datos, otros módulos dependientes o scripts de ejecución. Los archivos de manifiesto también son útiles para rastrear metadatos, como información de creación y control de versiones.

Finalmente, un módulo de secuencia de comandos, como cualquier otro módulo que no se crea dinámicamente, debe guardarse en una carpeta que PowerShell pueda descubrir razonablemente. Por lo general, se encuentra en la ruta del módulo de PowerShell; pero si es necesario, puede describir explícitamente dónde está instalado su módulo. Para obtener más información, consulte Cómo escribir un módulo de script de PowerShell.

Módulos binarios

Un módulo binario es un ensamblado de .NET Framework (.dll) que contiene código compilado, como C#. Los desarrolladores de cmdlets pueden utilizar este tipo de módulo para compartir cmdlets, proveedores y más. (Los complementos existentes también se pueden usar como módulos binarios). En comparación con un módulo de secuencia de comandos, un módulo binario le permite crear cmdlets que son más rápidos o usar características (como subprocesos múltiples) que no son tan fáciles de codificar en las secuencias de comandos de Windows PowerShell. .

Al igual que con los módulos de script, puede incluir un archivo de manifiesto para describir los recursos adicionales que utiliza su módulo y realizar un seguimiento de los metadatos sobre su módulo. De manera similar, probablemente debería instalar su módulo binario en una carpeta en algún lugar de la ruta del módulo de PowerShell. Para obtener más información, consulte Cómo escribir un módulo binario de PowerShell.

Módulos de manifiesto

Un módulo de manifiesto es un módulo que utiliza un archivo de manifiesto para describir todos sus componentes, pero no tiene ningún tipo de ensamblaje o secuencia de comandos principal. (Formalmente, un módulo de manifiesto deja vacío el elemento ModuleToProcess o RootModule del manifiesto). Sin embargo, aún puede utilizar las otras características de un módulo, como la capacidad de cargar ensamblajes dependientes o ejecutar automáticamente ciertos scripts de preprocesamiento. También puede usar un módulo de manifiesto como una forma conveniente de empaquetar recursos que usarán otros módulos, como módulos, ensamblados, tipos o formatos anidados. Para obtener más información, consulte Cómo escribir un manifiesto de módulo de PowerShell.

Módulos dinámicos

Un módulo dinámico es un módulo que no se carga ni se guarda en un archivo. En su lugar, se crean dinámicamente mediante un script mediante el cmdlet New-Module. Este tipo de módulo permite que un script cree un módulo bajo demanda que no necesita cargarse ni guardarse en un almacenamiento persistente. Por su naturaleza, un módulo dinámico está diseñado para ser de corta duración y, por lo tanto, el cmdlet Get-Module no puede acceder a él. De manera similar, generalmente no necesitan manifiestos de módulo, ni probablemente necesiten carpetas permanentes para almacenar sus ensamblados relacionados.

Manifiestos del módulo

Un manifiesto de módulo es un archivo .psd1 que contiene una tabla hash. Las claves y los valores de la tabla hash hacen lo siguiente:

Describir los contenidos y atributos del módulo.
Defina los requisitos previos.
Determine cómo se procesan los componentes.
No se requieren manifiestos para un módulo. Los módulos pueden hacer referencia a archivos de script (.ps1), archivos de módulo de script (.psm1), archivos de manifiesto (.psd1), archivos de formato y tipo. (.ps1xml), ensamblados de cmdlet y proveedor (.dll), archivos de recursos, archivos de ayuda, archivos de localización o cualquier otro tipo de archivo o recurso incluido como parte del módulo. Para un script internacionalizado, la carpeta del módulo también contiene un conjunto de archivos de catálogo de mensajes. Si agrega un archivo de manifiesto a la carpeta del módulo, puede hacer referencia a varios archivos como una sola unidad haciendo referencia al manifiesto.
El manifiesto en sí describe las siguientes categorías de información:
Metadatos sobre el módulo, como el número de versión del módulo, el autor y la descripción.
Requisitos previos necesarios para importar el módulo, como la versión de Windows PowerShell, la versión de Common Language Runtime (CLR) y los módulos necesarios.
Directivas de procesamiento, como los scripts, formatos y tipos a procesar.
Restricciones sobre los miembros del módulo a exportar, como los alias, funciones, variables y cmdlets a exportar.
Para obtener más información, consulte Cómo escribir un manifiesto de módulo de PowerShell.

Almacenamiento e instalación de un módulo

Una vez que haya creado un script, un binario o un módulo de manifiesto, puede guardar su trabajo en una ubicación a la que otros puedan acceder. Por ejemplo, su módulo puede almacenarse en la carpeta del sistema donde está instalado Windows PowerShell o puede almacenarse en una carpeta de usuario.

En términos generales, puede determinar dónde debe instalar su módulo utilizando una de las rutas almacenadas en la variable $ENV:PSModulePath. Usar una de estas rutas significa que PowerShell puede encontrar y cargar automáticamente su módulo cuando un usuario lo llama en su código. Si almacena su módulo en otro lugar, puede informar explícitamente a PowerShell pasando la ubicación de su módulo como parámetro cuando llame a Install-Module.

Independientemente, la ruta de la carpeta se conoce como la base del módulo (ModuleBase) y el nombre del script, binario o archivo del módulo de manifiesto debe ser el mismo que el nombre de la carpeta del módulo. con las siguientes excepciones:

Los módulos dinámicos creados por el cmdlet New-Module se pueden denominar mediante el parámetro Name del cmdlet.
Los módulos importados desde objetos de ensamblaje mediante el comando Import-Module -Assembly reciben nombres de acuerdo con la siguiente sintaxis: "dynamic_code_module_" + ensamblado.GetName().
Para obtener más información, consulte Instalación de un módulo de PowerShell y about_PSModulePath.

Cmdlets y variables del módulo

Windows PowerShell proporciona los siguientes cmdlets y variables para la creación y administración de módulos.

Cmdlet New-Module Este cmdlet crea un nuevo módulo dinámico que existe solo en la memoria. El módulo se crea a partir de un bloque de script y sus miembros exportados, como sus funciones y variables, están disponibles inmediatamente en la sesión y permanecen disponibles hasta que se cierra la sesión.

Cmdlet New-ModuleManifest Este cmdlet crea un nuevo archivo de manifiesto de módulo (.psd1), completa sus valores y guarda el archivo de manifiesto en la ruta especificada. Este cmdlet también se puede usar para crear una plantilla de manifiesto de módulo que se puede completar manualmente.

Cmdlet Import-Module Este cmdlet agrega uno o más módulos a la sesión actual.

Cmdlet Get-Module Este cmdlet recupera información sobre los módulos que se han importado o que se pueden importar a la sesión actual.

Cmdlet Export-ModuleMember Este cmdlet especifica los miembros del módulo (como cmdlets, funciones, variables y alias) que se exportan desde un archivo de módulo de secuencia de comandos (.psm1) o desde un módulo dinámico creado mediante Nuevo-Módulo cmdlet.

Cmdlet Remove-Module Este cmdlet elimina módulos de la sesión actual.

Cmdlet Test-ModuleManifest Este cmdlet verifica que un manifiesto de módulo describa con precisión los componentes de un módulo verificando que los archivos que se enumeran en el archivo de manifiesto del módulo (.psd1) realmente existan en las rutas especificadas.

$PSScriptRoot Esta variable contiene el directorio desde el que se ejecuta el módulo de script. Permite que los scripts utilicen la ruta del módulo para acceder a otros recursos.

$env:PSModulePath Esta variable de entorno contiene una lista de los directorios en los que se almacenan los módulos de Windows PowerShell. Windows PowerShell usa el valor de esta variable al importar módulos automáticamente y actualizar los temas de Ayuda de los módulos.

Ver también

Escribir un módulo de Windows PowerShell