Moduli con versioni di PowerShell compatibili

Articolo
06/26/2023

A partire dalla versione 5.1, PowerShell è disponibile in diverse edizioni che corrispondono a vari set di funzionalità e compatibilità della piattaforma.

Desktop Edition: basata su .NET Framework, si applica a Windows PowerShell versione 4.0 e precedenti, nonché a Windows PowerShell 5.1 in Windows Desktop, Windows Server, Windows Server Core e la maggior parte delle altre edizioni di Windows.
Core Edition: Basato su .NET Core, si applica a PowerShell 6.0 e versioni successive, oltre a Windows PowerShell 5.1 su edizioni Windows con footprint ridotto, ad esempio Windows IoT e Windows Nano Server.

Per altre informazioni sulle edizioni di PowerShell, vedere about_PowerShell_Editions.

Dichiarazione delle edizioni compatibili

Gli autori di moduli possono dichiarare i propri moduli compatibili con una o più edizioni di PowerShell usando la chiave del manifesto del modulo CompatiblePSEditions. Questa chiave è supportata solo in PowerShell 5.1 o versioni successive.

Nota

Quando un manifesto del modulo viene specificato con la chiave CompatiblePSEditions o usa la variabile $PSEdition, non può essere importato in PowerShell v4 o versioni precedenti.

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;}

Quando si recupera un elenco dei moduli disponibili, è possibile filtrarlo in base all'edizione di 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 partire da PowerShell 6, il valore CompatiblePSEditions viene usato per decidere se un modulo è compatibile quando i moduli vengono importati da $env:windir\System32\WindowsPowerShell\v1.0\Modules. Questo comportamento si applica solo a Windows. Al di fuori di questo scenario, il valore viene usato solo come metadati.

Ricerca di moduli compatibili

Gli utenti di PowerShell Gallery possono visualizzare l'elenco dei moduli supportati in un'edizione specifica di PowerShell usando i tag PSEdition_Desktop e PSEdition_Core.

I moduli senza tag PSEdition_Desktop e PSEdition_Core sono considerati idonei per le edizioni Desktop di PowerShell.

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

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

Selezionare più edizioni di destinazione

Gli autori dei moduli possono pubblicare un singolo modulo destinato a una o entrambe le edizioni di PowerShell (Desktop e Core).

Un modulo singolo può essere usato sia nell'edizione Desktop che nell'edizione Core purché l'autore vi aggiunga la logica necessaria in RootModule o nel manifesto del modulo usando la variabile $PSEdition. I moduli possono avere due set di DLL compilate destinati a CoreCLR e FullCLR. Ecco le opzioni per la creazione di pacchetti con la logica per il caricamento delle DLL appropriate.

Opzione 1: creazione di un modulo destinabile a più versioni e più edizioni di PowerShell

Contenuto della cartella del modulo

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

Contenuto del file 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'

# ---
}

La logica riportata qui sotto carica gli assembly necessari in base all'edizione o alla versione corrente.

Contenuto del file 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
}

Opzione 2: Usare la variabile $PSEdition nel file PSD1 per caricare le DLL corrette

Nella versione PS 5.1 o successiva la variabile globale $PSEdition è consentita nel file manifesto del modulo. Usando questa variabile l'autore del modulo può specificare i valori condizionali nel file manifesto del modulo. È possibile fare riferimento alla variabile $PSEdition in modalità linguaggio con restrizioni o in una sezione di dati.

File manifesto del modulo di esempio con la chiave 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'
    }
}

Contenuto del modulo

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

Altre informazioni

Script con PSEditions

Supporto di PSEditions nella raccolta di PowerShell

Aggiornare il manifesto del modulo

about_PowerShell_Editions

Condividi tramite