Módulos con las ediciones compatibles de PowerShell

Artículo
06/26/2023

A partir de la versión 5.1, PowerShell está disponible en diferentes ediciones, las cuales denotan distintos conjuntos de características y compatibilidad con varias plataformas.

Desktop Edition: basada en .NET Framework, se aplica a Windows PowerShell 4.0 y versiones anteriores, así como Windows PowerShell 5.1 en escritorio de Windows, Windows Server, Windows Server Core y muchas otras ediciones de Windows.
Core Edition: basada en .NET Core, se aplica a PowerShell 6.0 y versiones posteriores, así como Windows PowerShell 5.1 en ediciones de Windows de superficie reducida, como Windows IoT y Windows Nano Server.

Para más información sobre las ediciones de PowerShell, consulte about_PowerShell_Editions.

Declaración de las ediciones compatibles

Los autores de módulos pueden declarar sus módulos para hacerlos compatibles con una o varias ediciones de PowerShell mediante la clave de manifiesto del módulo CompatiblePSEditions. Esta clave solo se admite en PowerShell 5.1 o versiones posteriores.

Nota

Una vez que se especifica un manifiesto de módulo con la clave CompatiblePSEditions (o cuando usa la variable $PSEdition), no se puede importar en PowerShell v4 o versiones anteriores.

New-ModuleManifest -Path .\TestModuleWithEdition.psd1 -CompatiblePSEditions Desktop,Core -PowerShellVersion 5.1
$ModuleInfo = Test-ModuleManifest -Path .\TestModuleWithEdition.psd1
$ModuleInfo.CompatiblePSEditions

Desktop
Core

$ModuleInfo | Get-Member CompatiblePSEditions

   TypeName: System.Management.Automation.PSModuleInfo

Name                 MemberType Definition
----                 ---------- ----------
CompatiblePSEditions Property   System.Collections.Generic.IEnumerable[string] CompatiblePSEditions {get;}

Al obtener una lista de los módulos disponibles, puede filtrarla según la edición de PowerShell.

Get-Module -ListAvailable -PSEdition Desktop

    Directory: C:\Program Files\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Manifest   1.0        ModuleWithPSEditions

Get-Module -ListAvailable -PSEdition Core | % CompatiblePSEditions

Desktop
Core

A partir de PowerShell 6, el valor CompatiblePSEditions se usa para decidir si un módulo es compatible cuando los módulos se importan desde $env:windir\System32\WindowsPowerShell\v1.0\Modules. Este comportamiento solo se aplica a Windows. Fuera de este escenario, el valor solo se usa como metadatos.

Búsqueda de módulos compatibles

Los usuarios de la Galería de PowerShell pueden encontrar la lista de los módulos admitidos para una edición específica de PowerShell mediante las etiquetas PSEdition_Desktop y PSEdition_Core.

Se considera que los módulos que no tienen las etiquetas PSEdition_Desktop o PSEdition_Core funcionan correctamente en las ediciones de PowerShell Desktop.

# Find modules supported on PowerShell Desktop edition
Find-Module -Tag PSEdition_Desktop

# Find modules supported on PowerShell Core editions
Find-Module -Tag PSEdition_Core

Varias ediciones como destino

Los autores de módulos pueden publicar un único módulo destinado a una de las ediciones de PowerShell o a ambas (Core o Desktop).

Un único módulo puede trabajar tanto en la edición Desktop como en Core; en este módulo, el autor tiene que agregar la lógica necesaria en RootModule o en el manifiesto del módulo mediante la variable $PSEdition. Los módulos pueden tener dos conjuntos de archivos .dll compilados que tengan como destino CoreCLR y FullCLR. Estas son las opciones de empaquetado con lógica para cargar los archivos .dll adecuados.

Opción 1: empaquetar un módulo para dirigirlo a varias versiones y varias ediciones de PowerShell

Contenido de la carpeta del módulo

Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll
Microsoft.Windows.PowerShell.ScriptAnalyzer.dll
PSScriptAnalyzer.psd1
PSScriptAnalyzer.psm1
ScriptAnalyzer.format.ps1xml
ScriptAnalyzer.types.ps1xml
coreclr\Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll
coreclr\Microsoft.Windows.PowerShell.ScriptAnalyzer.dll
es-ES\about_PSScriptAnalyzer.help.txt
es-ES\Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
PSv3\Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll
PSv3\Microsoft.Windows.PowerShell.ScriptAnalyzer.dll
Settings\CmdletDesign.psd1
Settings\DSC.psd1
Settings\ScriptFunctions.psd1
Settings\ScriptingStyle.psd1
Settings\ScriptSecurity.psd1

Contenido del archivo PSScriptAnalyzer.psd1

@{

# Author of this module
Author = 'Microsoft Corporation'

# Script module or binary module file associated with this manifest.
RootModule = 'PSScriptAnalyzer.psm1'

# Version number of this module.
ModuleVersion = '1.6.1'

# ---
}

A continuación, la lógica carga los ensamblados necesarios en función de la edición o la versión actual.

Contenido del archivo PSScriptAnalyzer.psm1:

#
# Script module for module 'PSScriptAnalyzer'
#
Set-StrictMode -Version Latest

# Set up some helper variables to make it easier to work with the module
$PSModule = $ExecutionContext.SessionState.Module
$PSModuleRoot = $PSModule.ModuleBase

# Import the appropriate nested binary module based on the current PowerShell version
$binaryModuleRoot = $PSModuleRoot


if (($PSVersionTable.Keys -contains "PSEdition") -and ($PSVersionTable.PSEdition -ne 'Desktop')) {
    $binaryModuleRoot = Join-Path -Path $PSModuleRoot -ChildPath 'coreclr'
}
else
{
    if ($PSVersionTable.PSVersion -lt [Version]'5.0')
    {
        $binaryModuleRoot = Join-Path -Path $PSModuleRoot -ChildPath 'PSv3'
    }
}

$binaryModulePath = Join-Path -Path $binaryModuleRoot -ChildPath 'Microsoft.Windows.PowerShell.ScriptAnalyzer.dll'
$binaryModule = Import-Module -Name $binaryModulePath -PassThru

# When the module is unloaded, remove the nested binary module that was loaded with it
$PSModule.OnRemove = {
    Remove-Module -ModuleInfo $binaryModule
}

Opción 2: Uso de la variable $PSEdition en el archivo PSD1 para cargar los archivos .dll adecuados

En PS 5.1 y versiones posteriores, se permite usar la variable global $PSEdition en el archivo de manifiesto del módulo. Mediante esta variable el autor del módulo puede especificar los valores condicionales en el archivo de manifiesto de módulo. Se puede hacer referencia a la variable $PSEdition en el modo de lenguaje restringido o en una sección de datos.

Ejemplo de archivo de manifiesto de módulo con la clave CompatiblePSEditions.

@{
    # Script module or binary module file associated with this manifest.
    RootModule = if($PSEdition -eq 'Core')
    {
        'coreclr\MyCoreClrRM.dll'
    }
    else # Desktop
    {
        'clr\MyFullClrRM.dll'
    }

    # Supported PSEditions
    CompatiblePSEditions = 'Desktop', 'Core'

    # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
    NestedModules = if($PSEdition -eq 'Core')
    {
        'coreclr\MyCoreClrNM1.dll',
        'coreclr\MyCoreClrNM2.dll'
    }
    else # Desktop
    {
        'clr\MyFullClrNM1.dll',
        'clr\MyFullClrNM2.dll'
    }
}

Contenido del módulo

ModuleWithEditions\ModuleWithEditions.psd1
ModuleWithEditions\clr\MyFullClrNM1.dll
ModuleWithEditions\clr\MyFullClrNM2.dll
ModuleWithEditions\clr\MyFullClrRM.dll
ModuleWithEditions\coreclr\MyCoreClrNM1.dll
ModuleWithEditions\coreclr\MyCoreClrNM2.dll
ModuleWithEditions\coreclr\MyCoreClrRM.dll

Más detalles

Scripts con PSEditions

Compatibilidad con PSEditions en la Galería de PowerShell

Actualizar el manifiesto de módulo

about_PowerShell_Editions

Compartir a través de