Compartir a través de

11. Módulos

Nota editorial

Importante

La Especificación del Lenguaje de Windows PowerShell 3.0 se publicó en diciembre de 2012 y se basa en Windows PowerShell 3.0. Esta especificación no refleja el estado actual de PowerShell. No hay ningún plan para actualizar esta documentación para reflejar el estado actual. Esta documentación se presenta aquí para obtener referencia histórica.

El documento de especificación está disponible como un documento de Microsoft Word del Centro de descarga de Microsoft en: https://www.microsoft.com/download/details.aspx?id=36389 Ese documento de Word se ha convertido para su presentación aquí en Microsoft Learn. Durante la conversión, se han realizado algunos cambios editoriales para dar cabida al formato de la plataforma Docs. Se han corregido algunos errores tipográficos y menores.

11.1 Introducción

Como se indica en §3.14, un módulo es una unidad reutilizable autocontenida que permite crear particiones, organizar y abstraer código de PowerShell. Un módulo puede contener uno o varios miembros del módulo , que son comandos (como cmdlets y funciones) y elementos (como variables y alias). Los nombres de estos miembros se pueden mantener privados en el módulo o se pueden exportar a la sesión en la que se importa el módulo .

Hay tres tipos de módulos diferentes: manifiesto, script y binario. Un módulo de manifiesto es un archivo que contiene información sobre un módulo y controla determinados aspectos del uso de ese módulo. Un módulo de script de PowerShell es un archivo de script de PowerShell con una extensión de nombre de archivo de .psm1 en lugar de .ps1. Un módulo binario contiene tipos de clase que definen cmdlets y proveedores. A diferencia de los módulos de script, los módulos binarios se escriben en lenguajes compilados. Los módulos binarios no están cubiertos por esta especificación.

Un módulo binario es un ensamblado de .NET (es decir, un archivo DLL) que fue compilado contra las bibliotecas de PowerShell.

Los módulos se pueden anidar; es decir, un módulo puede importar otro módulo. Un módulo que tiene módulos anidados asociados es un módulo raíz .

Cuando se crea una sesión de PowerShell, de forma predeterminada, no se importa ningún módulo.

Cuando se importan módulos, la ruta de búsqueda que se usa para localizarlos se define mediante la variable de entorno PSModulePath.

Los siguientes cmdlets gestionan los módulos:

11.2 Escritura de un módulo de script

Un módulo de script es un archivo de script. Considere el siguiente módulo de script:

function Convert-CentigradeToFahrenheit ([double]$tempC) {
    return ($tempC * (9.0 / 5.0)) + 32.0
}
New-Alias c2f Convert-CentigradeToFahrenheit

function Convert-FahrenheitToCentigrade ([double]$tempF) {
    return ($tempF - 32.0) * (5.0 / 9.0)
}
New-Alias f2c Convert-FahrenheitToCentigrade

Export-ModuleMember -Function Convert-CentigradeToFahrenheit
Export-ModuleMember -Function Convert-FahrenheitToCentigrade
Export-ModuleMember -Alias c2f, f2c

Este módulo contiene dos funciones, cada una de las cuales tiene un alias. De forma predeterminada, se exportan todos los nombres de función y solo se exportan los nombres de función. Sin embargo, una vez que se haya usado el cmdlet Export-ModuleMember para exportar cualquier elemento, solo se exportarán explícitamente esas cosas. Se puede exportar una serie de comandos y elementos en una llamada o una serie de llamadas a este cmdlet; estas llamadas son acumulativas para la sesión actual.

11.3 Instalación de un módulo de script

Un módulo de script se define en un archivo de script y los módulos se pueden almacenar en cualquier directorio. La variable de entorno PSModulePath apunta a un conjunto de directorios en los que se buscará cuando los cmdlets relacionados con módulos busquen módulos cuyos nombres no incluyan una ruta de acceso absoluta. Se pueden proporcionar rutas de búsqueda adicionales; por ejemplo

$Env:PSModulepath = $Env:PSModulepath + ";<additional-path>"

Las rutas de acceso adicionales agregadas solo afectan a la sesión actual.

Como alternativa, se puede especificar una ruta de acceso completa cuando se importa un módulo.

11.4 Importación de un módulo de script

Para poder usar los recursos de un módulo, ese módulo debe importarse en la sesión actual mediante el cmdlet Import-Module. Import-Module puede restringir los recursos que importa realmente.

Cuando se importa un módulo, se ejecuta su archivo de script. Ese proceso se puede configurar definiendo uno o varios parámetros en el archivo de script y pasando los argumentos correspondientes a través del parámetro ArgumentList de Import-Module.

Tenga en cuenta el siguiente script que usa estas funciones y alias definidos en §11.2:

Import-Module "E:\Scripts\Modules\PSTest_Temperature" -Verbose

"0 degrees C is " + (Convert-CentigradeToFahrenheit 0) + " degrees F"
"100 degrees C is " + (c2f 100) + " degrees F"
"32 degrees F is " + (Convert-FahrenheitToCentigrade 32) + " degrees C"
"212 degrees F is " + (f2c 212) + " degrees C"

La importación de un módulo produce un conflicto de nombres cuando los comandos o elementos del módulo tienen los mismos nombres que los comandos o elementos de la sesión. Un conflicto de nombres provoca que un nombre se oculte o se reemplace. El parámetro Prefix de Import-Module se puede usar para evitar conflictos de nomenclatura. Además, los parámetros Alias, Cmdlet, Functiony Variable pueden limitar la selección de comandos que se van a importar, lo que reduce las posibilidades de conflicto de nombres.

Incluso si un comando está oculto, se puede ejecutar calificando su nombre con el nombre del módulo en el que se originó. Por ejemplo, & M\F 100 invoca la función F en el módulo My la pasa el argumento 100.

Cuando la sesión incluye comandos del mismo tipo con el mismo nombre, como dos cmdlets con el mismo nombre, de forma predeterminada ejecuta el comando agregado más recientemente.

Consulte §3.5.6 para obtener una explicación del ámbito en relación con los módulos.

11.5 Eliminación de un módulo de script

Se pueden quitar uno o varios módulos de una sesión a través del cmdlet Remove-Module.

Al quitar un módulo no se desinstala el módulo.

En un módulo de script, es posible especificar código que se va a ejecutar antes de la eliminación de ese módulo, como se indica a continuación:

$MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = { *on-removal-code* }

11.6 Manifiestos del módulo

Como se indica en §11.1, un módulo de manifiesto es un archivo que contiene información sobre un módulo y controla determinados aspectos del uso del módulo.

Un módulo no necesita tener un manifiesto correspondiente, pero si lo hace, ese manifiesto tiene el mismo nombre que el módulo que describe, pero con una extensión de archivo .psd1.

Un manifiesto contiene un subconjunto limitado del script de PowerShell, que devuelve una tabla Hash que contiene un conjunto de claves. Estas claves y sus valores especifican los elementos de manifiesto para ese módulo. Es decir, describen el contenido y los atributos del módulo, definen los requisitos previos y determinan cómo se procesan los componentes.

Básicamente, un manifiesto es un archivo de datos; sin embargo, puede contener referencias a tipos de datos, la instrucción if y los operadores aritméticos y de comparación. (No se permiten asignaciones, definiciones de función y bucles). Un manifiesto también tiene acceso de lectura a las variables de entorno y puede contener llamadas al cmdlet Join-Path, por lo que se pueden construir rutas de acceso.

Nota

Nota del editor: El documento original contiene una lista de claves permitidas en un archivo de manifiesto de módulo. Esa lista está obsoleta e incompleta. Para obtener una lista completa de las claves de un manifiesto de módulo, consulte New-ModuleManifest.

La única clave necesaria es ModuleVersion.

Este es un ejemplo de un manifiesto simple:

@{
ModuleVersion = '1.0'
Author = 'John Doe'
RequiredModules = @()
FunctionsToExport = 'Set*','Get*','Process*'
}

La clave GUID tiene un valor string. Esto especifica un identificador único global (GUID) para el módulo. El GUID se puede usar para distinguir entre módulos que tienen el mismo nombre. Para crear un nuevo GUID, llame al método [guid]::NewGuid().

11.7 Módulos dinámicos

Un módulo dinámico es un módulo creado en memoria en tiempo de ejecución por el cmdlet New-Module; no se carga desde el disco. Tenga en cuenta el ejemplo siguiente:

$sb = {
    function Convert-CentigradeToFahrenheit ([double]$tempC) {
        return ($tempC * (9.0 / 5.0)) + 32.0
    }

    New-Alias c2f Convert-CentigradeToFahrenheit

    function Convert-FahrenheitToCentigrade ([double]$tempF) {
        return ($tempF - 32.0) * (5.0 / 9.0)
    }

    New-Alias f2c Convert-FahrenheitToCentigrade

    Export-ModuleMember -Function Convert-CentigradeToFahrenheit
    Export-ModuleMember -Function Convert-FahrenheitToCentigrade
    Export-ModuleMember -Alias c2f, f2c
}

New-Module -Name MyDynMod -ScriptBlock $sb
Convert-CentigradeToFahrenheit 100
c2f 100

El bloque de script $sb define el contenido del módulo, en este caso, dos funciones y dos alias para esas funciones. Al igual que con un módulo en disco, solo las funciones se exportan de forma predeterminada, por lo que Export-ModuleMember las llamadas a cmdlets existen para exportar las funciones y los alias.

Una vez que se ejecuta New-Module, los cuatro nombres exportados están disponibles para su uso en la sesión, como se muestra en las llamadas a la Convert-CentigradeToFahrenheit y c2f.

Al igual que todos los módulos, los miembros de los módulos dinámicos se ejecutan en un ámbito de módulo privado que es un elemento secundario del ámbito global. Get-Module no puede obtener un módulo dinámico, pero Get-Command puede obtener los miembros exportados.

Para que un módulo dinámico esté disponible para Get-Module, canalice un comando New-Module para Import-Moduleo canalice el objeto de módulo que New-Module devuelve, a Import-Module. Esta acción agrega el módulo dinámico a la lista de Get-Module, pero no guarda el módulo en el disco ni lo hace persistente.

11.8 Cierres

Se puede usar un módulo dinámico para crear un cierre , una función con datos adjuntos. Tenga en cuenta el ejemplo siguiente:

function Get-NextID ([int]$startValue = 1) {
    $nextID = $startValue
    {
        ($script:nextID++)
    }.GetNewClosure()
}

$v1 = Get-NextID      # get a scriptblock with $startValue of 0
& $v1                 # invoke Get-NextID getting back 1
& $v1                 # invoke Get-NextID getting back 2

$v2 = Get-NextID 100  # get a scriptblock with $startValue of 100
& $v2                 # invoke Get-NextID getting back 100
& $v2                 # invoke Get-NextID getting back 101

La intención aquí es que Get-NextID devuelva el siguiente identificador en una secuencia cuyo valor inicial se puede especificar. Sin embargo, se deben admitir varias secuencias, cada una con su propio $startValue y $nextID contexto. Esto se logra mediante la llamada al método [scriptblock]::GetNewClosure (§4.3.7).

Cada vez que GetNewClosurecrea un nuevo cierre, se genera un nuevo módulo dinámico y las variables del entorno del que realiza la llamada (en este caso, el bloque de script que contiene el incremento) se copian en este nuevo módulo. Para asegurarse de que el nextId definido dentro de la función principal (pero fuera del bloque de script) se incremente, se necesita el prefijo explícito script: scope.

Por supuesto, el bloque de script no debe ser una función con nombre; por ejemplo:

$v3 = & {      # get a scriptblock with $startValue of 200
    param ([int]$startValue = 1)
    $nextID = $startValue
    {
        ($script:nextID++)
    }.GetNewClosure()
} 200

& $v3          # invoke script getting back 200
& $v3          # invoke script getting back 201