Module mit kompatiblen PowerShell-Editionen

Artikel
06/26/2023

Ab Version 5.1 steht PowerShell in verschiedenen Editionen zur Verfügung, die unterschiedliche Funktionsgruppen und Plattformkompatibilität bieten.

Desktop-Edition: Basiert auf .NET Framework, gilt für Windows PowerShell v4.0 und niedriger sowie Windows PowerShell 5.1 für Windows Desktop, Windows Server, Windows Server Core und die meisten anderen Editionen von Windows.
Core-Edition: Basiert auf .NET Core, gilt für PowerShell 6.0 und höher sowie Windows PowerShell 5.1 auf reduzierten Editionen von Windows wie z. B. Windows IoT und Windows Nano Server.

Weitere Informationen zu den PowerShell-Editionen finden Sie unter about_PowerShell_Editions.

Deklarieren von kompatiblen Editionen

Mithilfe des Modulmanifestschlüssels CompatiblePSEditions können Modulautoren ihre Module als kompatibel mit einer oder mehreren PowerShell-Editionen deklarieren. Dieser Schlüssel wird nur auf PowerShell 5.1 oder höher unterstützt.

Hinweis

Sobald mit dem Schlüssel CompatiblePSEditions ein Modulmanifest angegeben wurde oder dieses die Variable $PSEdition verwendet, kann es nicht in PowerShell-Version v4 oder niedriger importiert werden.

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

Beim Abrufen einer Liste der verfügbaren Module können Sie sie nach PowerShell-Editionen filtern.

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

Ab PowerShell 6 wird anhand des Werts CompatiblePSEditions entschieden, ob ein Modul beim Import aus $env:windir\System32\WindowsPowerShell\v1.0\Modules kompatibel ist. Dieses Verhalten gilt nur für Windows. Ansonsten wird der Wert nur als Metadaten verwendet.

Suchen nach kompatiblen Modulen

Benutzer des PowerShell-Katalogs finden mithilfe der Tags PSEdition_Desktop und PSEdition_Core eine Liste der in einer bestimmten PowerShell-Edition unterstützten Module.

Module ohne die Tags PSEdition_Desktop und PSEditon_Core sollten in PowerShell Desktop-Editionen keine Probleme bereiten.

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

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

Festlegen von mehreren Editionen als Ziel

Modulautoren können ein einzelnes Modul veröffentlichen, bei dem eine oder beide PowerShell-Editionen (Desktop und Core) als Ziel festgelegt sind.

Ein einzelnes Modul kann sowohl in der Desktop- als auch in der Core-Edition funktionieren, wenn der Modulautor die dafür benötigte Logik mithilfe der Variable $PSEdition zu „RootModule“ oder dem Modulmanifest hinzufügt. Module können über zwei Gruppen kompilierter DLLs verfügen, die beide CoreCLR und FullCLR als Ziel verwenden. Die folgenden Paketoptionen enthalten Logik zum Laden der korrekten DLLs:

Option 1: Packen eines Moduls für die Adressierung mehrerer Versionen und Editionen von PowerShell

Inhalt des Modulordners

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
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
Settings\CmdletDesign.psd1
Settings\DSC.psd1
Settings\ScriptFunctions.psd1
Settings\ScriptingStyle.psd1
Settings\ScriptSecurity.psd1

Inhalt der Datei 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'

# ---
}

Die nachstehende Logik lädt die erforderlichen Assemblys abhängig von der aktuellen Edition oder Version.

Inhalt der Datei 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
}

Option 2: Verwenden der Variable „$PSEdition“ in der PSD1-Datei zum Laden der korrekten DLLs

In PS 5.1 oder höher ist die globale Variable $PSEdition in der Modulmanifestdatei zulässig. Durch die Verwendung dieser Variable kann der Modulautor die bedingten Werte in der Modulmanifestdatei angeben. Auf die Variable $PSEdition kann im eingeschränkten Sprachmodus oder in einem Data-Abschnitt verwiesen werden.

Beispiel für eine Modulmanifestdatei mit dem Schlüssel 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'
    }
}

Modulinhalte