Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Windows PowerShell wird für .NET Framework- geschrieben, während PowerShell Core für .NET Core-geschrieben wird. Tragbare Module sind Module, die sowohl in Windows PowerShell als auch in PowerShell Core funktionieren. Während .NET Framework und .NET Core hochkompatibel sind, gibt es Unterschiede in den verfügbaren APIs zwischen den beiden. Es gibt auch Unterschiede in den APIs, die in Windows PowerShell und PowerShell Core verfügbar sind. Module, die in beiden Umgebungen verwendet werden sollen, müssen diese Unterschiede berücksichtigen.
Portieren eines vorhandenen Moduls
Portieren eines PSSnapIn
PowerShell SnapIns werden in PowerShell Core nicht unterstützt. Es ist jedoch trivial, ein PSSnapIn in ein PowerShell-Modul zu konvertieren. Normalerweise befindet sich der PSSnapIn-Registrierungscode in einer einzigen Quelldatei einer Klasse, die von PSSnapInabgeleitet wird. Entfernen Sie diese Quelldatei aus dem Build; es ist nicht mehr erforderlich.
Verwenden Sie New-ModuleManifest-, um ein neues Modulmanifest zu erstellen, das die Notwendigkeit des PSSnapIn-Registrierungscodes ersetzt. Einige Werte aus dem PSSnapIn- (z. B. Beschreibung) können innerhalb des Modulmanifests wiederverwendet werden.
Die RootModule--Eigenschaft im Modulmanifest sollte auf den Namen der Assembly (.dll) festgelegt werden, die die Cmdlets implementiert.
The .NET Portability Analyzer (aka APIPort)
Um Module, die für Windows PowerShell geschrieben wurden, so zu portieren, dass sie mit PowerShell Core funktionieren, beginnen Sie mit dem .NET Portability Analyzer. Führen Sie dieses Tool für die kompilierte Assembly aus, um zu ermitteln, ob die im Modul verwendeten .NET-APIs mit .NET Framework, .NET Core und anderen .NET-Runtimes kompatibel sind. Das Tool schlägt alternative APIs vor, falls vorhanden. Andernfalls müssen Sie unter Umständen Runtimeüberprüfungen hinzufügen und in bestimmten Runtimes nicht verfügbare Funktionen einschränken.
Erstellen eines neuen Moduls
Wenn Sie ein neues Modul erstellen, empfiehlt es sich, die .NET CLI-zu verwenden.
Installieren der PowerShell Standard-Modulvorlage
Installieren Sie nach der Installation der .NET CLI eine Vorlagenbibliothek, um ein einfaches PowerShell-Modul zu generieren. Das Modul ist mit Windows PowerShell, PowerShell Core, Windows, Linux und macOS kompatibel.
Das folgende Beispiel zeigt, wie Sie die Vorlage installieren:
dotnet new install Microsoft.PowerShell.Standard.Module.Template
The following template packages will be installed:
Microsoft.PowerShell.Standard.Module.Template
Success: Microsoft.PowerShell.Standard.Module.Template::0.1.3 installed the following templates:
Template Name Short Name Language Tags
-------------------------- ---------- -------- -------------------------
PowerShell Standard Module psmodule [C#] Library/PowerShell/Module
Erstellen eines neuen Modulprojekts
Nachdem die Vorlage installiert wurde, können Sie mithilfe dieser Vorlage ein neues PowerShell-Modulprojekt erstellen. In diesem Beispiel wird das Beispielmodul als "myModule" bezeichnet.
PS> mkdir myModule
Directory: C:\Users\Steve
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 8/3/2018 2:41 PM myModule
PS> cd myModule
PS C:\Users\Steve\myModule> dotnet new psmodule
The template "PowerShell Standard Module" was created successfully.
Processing post-creation actions...
Restoring C:\Users\Steve\myModule\myModule.csproj:
Determining projects to restore...
Restored C:\Users\Steve\myModule\myModule.csproj (in 184 ms).
Restore succeeded.
Erstellen des Moduls
Verwenden Sie standardmäßige .NET CLI-Befehle, um das Projekt zu erstellen.
dotnet build
PS C:\Users\Steve\myModule> dotnet build
MSBuild version 17.6.3+07e294721 for .NET
Determining projects to restore...
All projects are up-to-date for restore.
PowerShellPG -> C:\Users\Steve\myModule\bin\Debug\netstandard2.0\myModule.dll
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:02.36
Testen des Moduls
Nach dem Erstellen des Moduls können Sie es importieren und das Beispiel-Cmdlet ausführen.
Import-Module .\bin\Debug\netstandard2.0\myModule.dll
Test-SampleCmdlet -?
Test-SampleCmdlet -FavoriteNumber 7 -FavoritePet Cat
NAME
Test-SampleCmdlet
SYNTAX
Test-SampleCmdlet [-FavoriteNumber] <int> [[-FavoritePet] {Cat | Dog | Horse}] [<CommonParameters>]
ALIASES
None
REMARKS
None
FavoriteNumber FavoritePet
-------------- -----------
7 Cat
Debuggen des Moduls
Eine Anleitung zum Einrichten von Visual Studio Code zum Debuggen des Moduls finden Sie unter Verwenden von Visual Studio Code zum Debuggen kompilierter Cmdlets.
Unterstützende Technologien
In den folgenden Abschnitten werden einige der technologien beschrieben, die von dieser Vorlage verwendet werden.
.NET-Standardbibliothek
.NET Standard ist eine formale Spezifikation von .NET-APIs, die in allen .NET-Implementierungen verfügbar sind. Verwalteter Code für .NET Standard funktioniert mit den .NET Framework- und .NET Core-Versionen, die mit dieser Version von .NET Standard kompatibel sind.
Anmerkung
Obwohl eine API möglicherweise in .NET Standard vorhanden ist, löst die API-Implementierung in .NET Core möglicherweise eine PlatformNotSupportedException zur Laufzeit aus. Um die Kompatibilität mit Windows PowerShell und PowerShell Core zu überprüfen, besteht die bewährte Methode darin, Tests für Ihr Modul in beiden Umgebungen auszuführen.
Führen Sie auch Tests unter Linux und macOS aus, wenn Ihr Modul plattformübergreifend sein soll.
Durch die Ausrichtung von .NET Standard wird sichergestellt, dass inkompatible APIs, da sich das Modul weiterentwickelt, nicht versehentlich in das Modul eingeführt werden. Inkompatibilitäten werden zur Kompilierungszeit anstelle der Laufzeit ermittelt.
Es ist jedoch nicht erforderlich, .NET Standard für ein Modul für die Verwendung mit Windows PowerShell und PowerShell Core zu verwenden, solange Sie kompatible APIs verwenden. Die Zwischensprache (Intermediate Language, IL) ist zwischen den beiden Laufzeiten kompatibel. Sie können .NET Framework 4.6.1 als Ziel verwenden, das mit .NET Standard 2.0 kompatibel ist. Wenn Sie apIs außerhalb von .NET Standard 2.0 nicht verwenden, funktioniert Ihr Modul ohne erneute Kompilierung mit PowerShell Core 6.
PowerShell-Standardbibliothek
Die PowerShell Standard-Bibliothek ist eine formale Spezifikation von PowerShell-APIs, die in allen PowerShell-Versionen verfügbar sind, die größer oder gleich der Version dieses Standards sind.
Beispielsweise ist PowerShell Standard 5.1- sowohl mit Windows PowerShell 5.1 als auch mit PowerShell Core 6.0 oder höher kompatibel.
Es wird empfohlen, Ihr Modul mithilfe der PowerShell-Standardbibliothek zu kompilieren. Die Bibliothek stellt sicher, dass die APIs sowohl in Windows PowerShell als auch in PowerShell Core 6 verfügbar und implementiert sind. PowerShell Standard soll stets aufwärtskompatibel sein. Ein Modul, das mit powerShell Standard Library 5.1 erstellt wurde, ist immer mit zukünftigen Versionen von PowerShell kompatibel.
Modulmanifest
Angeben der Kompatibilität mit Windows PowerShell und PowerShell Core
Nach der Überprüfung, dass Ihr Modul sowohl mit Windows PowerShell als auch mit PowerShell Core funktioniert, sollte das Modulmanifest explizit die Kompatibilität angeben, indem die CompatiblePSEditions-Eigenschaft verwendet wird.
Ein Wert von Desktop bedeutet, dass das Modul mit Windows PowerShell kompatibel ist, während ein Wert von Core bedeutet, dass das Modul mit PowerShell Core kompatibel ist. Das Einschließen von Desktop und Core bedeutet, dass das Modul sowohl mit Windows PowerShell als auch mit PowerShell Core kompatibel ist.
Anmerkung
Core bedeutet nicht automatisch, dass das Modul mit Windows, Linux und macOS kompatibel ist.
Die CompatiblePSEditions-Eigenschaft wurde in PowerShell v5 eingeführt. Modulmanifeste, die die CompatiblePSEditions-Eigenschaft verwenden, können in Versionen vor PowerShell v5 nicht geladen werden.
Angeben der Betriebssystemkompatibilität
Überprüfen Sie zunächst, ob Ihr Modul unter Linux und macOS funktioniert. Geben Sie als Nächstes die Kompatibilität mit diesen Betriebssystemen im Modulmanifest an. Dies erleichtert Benutzern das Auffinden Ihres Moduls für ihr Betriebssystem, wenn es in die PowerShell-Galerieveröffentlicht wird.
Innerhalb des Modulmanifests verfügt die PrivateData-Eigenschaft über eine PSData Untereigenschaft. Die optionale Tags-Eigenschaft von PSData akzeptiert ein Array von Werten, die im PowerShell-Katalog angezeigt werden. Der PowerShell-Katalog unterstützt die folgenden Kompatibilitätswerte:
| Etikett | Beschreibung |
|---|---|
| PSEdition_Core | Kompatibel mit PowerShell Core 6 |
| PSEdition_Desktop | Kompatibel mit Windows PowerShell |
| Fenster | Kompatibel mit Windows |
| Linux | Kompatibel mit Linux (keine bestimmte Distro) |
| macOS | Kompatibel mit macOS |
Beispiel:
@{
GUID = "4ae9fd46-338a-459c-8186-07f910774cb8"
Author = "Microsoft Corporation"
CompanyName = "Microsoft Corporation"
Copyright = "(C) Microsoft Corporation. All rights reserved."
HelpInfoUri = "https://go.microsoft.com/fwlink/?linkid=855962"
ModuleVersion = "1.2.4"
PowerShellVersion = "3.0"
ClrVersion = "4.0"
RootModule = "PackageManagement.psm1"
Description = 'PackageManagement (a.k.a. OneGet) is a new way to discover and install software packages from around the web.
it's a manager or multiplexer of existing package managers (also called package providers) that unifies Windows package management with a single Windows PowerShell interface. With PackageManagement, you can do the following.
- Manage a list of software repositories in which packages can be searched, acquired and installed
- Discover software packages
- Seamlessly install, uninstall, and inventory packages from one or more software repositories'
CmdletsToExport = @(
'Find-Package',
'Get-Package',
'Get-PackageProvider',
'Get-PackageSource',
'Install-Package',
'Import-PackageProvider'
'Find-PackageProvider'
'Install-PackageProvider'
'Register-PackageSource',
'Set-PackageSource',
'Unregister-PackageSource',
'Uninstall-Package'
'Save-Package'
)
FormatsToProcess = @('PackageManagement.format.ps1xml')
PrivateData = @{
PSData = @{
Tags = @('PackageManagement', 'PSEdition_Core', 'PSEdition_Desktop', 'Windows', 'Linux', 'macOS')
ProjectUri = 'https://oneget.org'
}
}
}
Abhängigkeit von nativen Bibliotheken
Module, die für die Verwendung in verschiedenen Betriebssystemen oder Prozessorarchitekturen vorgesehen sind, hängen möglicherweise von einer verwalteten Bibliothek ab, die selbst von einigen systemeigenen Bibliotheken abhängt.
Vor PowerShell 7 müsste man benutzerdefinierten Code haben, um die entsprechende systemeigene DLL zu laden, damit die verwaltete Bibliothek sie richtig finden kann.
Ab PowerShell 7 wird in Unterordnern des Speicherorts der verwalteten Bibliothek nach nativen Binärdateien gesucht, die geladen werden sollen. Die Suche erfolgt gemäß einer Teilmenge der .NET-RID-Katalog-Notation.
managed.dll folder
|
|--- 'win-x64' folder
| |--- native.dll
|
|--- 'win-x86' folder
| |--- native.dll
|
|--- 'win-arm' folder
| |--- native.dll
|
|--- 'win-arm64' folder
| |--- native.dll
|
|--- 'linux-x64' folder
| |--- native.so
|
|--- 'linux-x86' folder
| |--- native.so
|
|--- 'linux-arm' folder
| |--- native.so
|
|--- 'linux-arm64' folder
| |--- native.so
|
|--- 'osx-x64' folder
| |--- native.dylib
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
