Descripción de un módulo de Windows PowerShell

2025-03-25

Un módulo es un conjunto de funcionalidades relacionadas de Windows PowerShell, agrupadas como una unidad cómoda (normalmente guardada en un único directorio). Al definir un conjunto de archivos de script relacionados, ensamblados y recursos relacionados como módulo, puede hacer referencia, cargar, conservar y compartir el código mucho más fácil de lo que lo haría.

El propósito principal de un módulo es permitir la modularización (es decir, reutilización y 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. Si lo hace, puede controlar (es decir, hacer público o privado) las funciones y variables contenidas en el script. Guardar el script como un archivo .psm1 también permite controlar el ámbito de determinadas variables. Por último, también puede usar cmdlets como Install-Module para organizar, instalar y usar el script como bloques de creación para soluciones más grandes.

Componentes y tipos del módulo

Un módulo consta 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 adicionales, archivos de ayuda o scripts.
Un archivo de manifiesto que describe los archivos anteriores, así como almacena metadatos como información de creación y control de versiones.
Directorio que contiene todo el contenido anterior y se encuentra donde PowerShell puede encontrarlo razonablemente.

Nota:

Ninguno de estos componentes, por sí mismos, es realmente necesario. Por ejemplo, un módulo puede ser técnicamente solo 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 usa principalmente para fines organizativos. También puede escribir un script que cree dinámicamente un módulo y, como tal, no necesita realmente un directorio para almacenar nada. En las secciones siguientes se describen los tipos de módulos que puede obtener mediante la combinación y la coincidencia de las distintas partes posibles de un módulo.

Módulos de script

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

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

Por último, un módulo de script, como cualquier otro módulo que no se cree dinámicamente, debe guardarse en una carpeta que PowerShell pueda detectar razonablemente. Normalmente, esto se encuentra en la ruta de acceso del módulo de PowerShell; pero si es necesario, puede describir explícitamente dónde está instalado el 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 usar este tipo de módulo para compartir cmdlets, proveedores y mucho más. (Los complementos existentes también se pueden usar como módulos binarios). En comparación con un módulo de script, un módulo binario permite crear cmdlets más rápidos o usar características (como multithreading) que no son tan fáciles de codificar en scripts de Windows PowerShell.

Al igual que con los módulos de script, puede incluir un archivo de manifiesto para describir recursos adicionales que usa el módulo y realizar un seguimiento de los metadatos sobre el módulo. Del mismo modo, es probable que deba instalar el módulo binario en una carpeta en algún lugar de la ruta de acceso del módulo de PowerShell. Para obtener más información, vea How to How to Write a PowerShell Binary Module.

Módulos de manifiesto

Un módulo de manifiesto es un módulo que usa un archivo de manifiesto para describir todos sus componentes, pero no tiene ningún tipo de ensamblado principal o script. (Formalmente, un módulo de manifiesto deja vacío el ModuleToProcess o RootModule elemento del manifiesto). Sin embargo, todavía puede usar las otras características de un módulo, como la capacidad de cargar ensamblados dependientes o ejecutar automáticamente determinados scripts de preprocesamiento. También puede usar un módulo de manifiesto como una manera cómoda de empaquetar recursos que usarán otros módulos, como módulos anidados, ensamblados, tipos o formatos. 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 desde un archivo o se guarda en él. En su lugar, se crean dinámicamente mediante un script mediante el cmdlet New-Module . Este tipo de módulo permite a un script crear un módulo a petición que no es necesario cargar ni guardar en el almacenamiento persistente. Por su naturaleza, un módulo dinámico está pensado para ser de corta duración y, por lo tanto, el cmdlet Get-Module no puede acceder a él. Del mismo modo, normalmente no necesitan manifiestos de módulo ni probablemente necesiten carpetas permanentes para almacenar sus ensamblados relacionados.

Manifiestos de 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 el contenido y los atributos del módulo.
Defina los requisitos previos.
Determine cómo se procesan los componentes.

Los manifiestos no son necesarios 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 que se agrupa 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 los 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, los formatos y los tipos que se van a procesar.
Restricciones en los miembros del módulo que se van a exportar, como los alias, las funciones, las variables y los cmdlets que se van 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 archivo binario o un módulo de manifiesto, puede guardar el trabajo en una ubicación a la que otros usuarios puedan acceder a él. Por ejemplo, el módulo se puede almacenar en la carpeta del sistema donde está instalado Windows PowerShell o se puede almacenar en una carpeta de usuario.

Por lo general, puede determinar dónde debe instalar el módulo mediante una de las rutas de acceso almacenadas en la variable $Env:PSModulePath. El uso de una de estas rutas de acceso significa que PowerShell puede buscar y cargar automáticamente el módulo cuando un usuario realiza una llamada a él en su código. Si almacena el módulo en otro lugar, puede informar explícitamente a PowerShell pasando la ubicación del módulo como parámetro al llamar a Install-Module.

Independientemente de la ruta de acceso de la carpeta se conoce como la base del módulo (ModuleBase) y el nombre del archivo de script, binario o 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 ensamblado por el comando Import-Module -Assembly se denominan según la sintaxis siguiente: "dynamic_code_module_" + assembly.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 solo existe 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 cierre la sesión.

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

cmdlet Import-Module Este cmdlet agrega uno o varios 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 en 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 script (.psm1) o desde un módulo dinámico creado mediante el cmdlet New-Module.

cmdlet Remove-Module Este cmdlet quita los módulos de la sesión actual.

Test-ModuleManifest cmdlet Este cmdlet comprueba que un manifiesto de módulo describe con precisión los componentes de un módulo comprobando que los archivos que aparecen en el archivo de manifiesto del módulo (.psd1) existen realmente en las rutas de acceso especificadas.

$PSScriptRoot Esta variable contiene el directorio desde el que se ejecuta el módulo de script. Permite que los scripts usen la ruta de acceso 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 temas de Ayuda para módulos.

Véase también

escribir un módulo de Windows PowerShell