Portabla moduler

Artikel
08/03/2022
7 minuter för att läsa

Windows PowerShell skrivs för .NET Framework medan PowerShell Core är skrivet för .NET Core. Portabla moduler är moduler som fungerar i både Windows PowerShell och PowerShell Core. Även om .NET Framework och .NET Core är mycket kompatibla finns det skillnader i tillgängliga API:er mellan de två. Det finns också skillnader i api:erna som är tillgängliga i Windows PowerShell och PowerShell Core. Moduler som är avsedda att användas i båda miljöerna måste vara medvetna om dessa skillnader.

Porta en befintlig modul

Porta en PSSnapIn

PowerShell SnapIns stöds inte i PowerShell Core. Det är dock enkelt att konvertera en PSSnapIn till en PowerShell-modul. Vanligtvis finns PSSnapIn-registreringskoden i en enda källfil i en klass som härleds från PSSnapIn. Ta bort den här källfilen från bygget. det behövs inte längre.

Använd New-ModuleManifest för att skapa ett nytt modulmanifest som ersätter behovet av PSSnapIn-registreringskoden. Några av värdena från PSSnapIn (till exempel Beskrivning) kan återanvändas i modulmanifestet.

Egenskapen RootModule i modulmanifestet ska anges till namnet på sammansättningen (dll) som implementerar cmdletarna.

.NET Portability Analyzer (även kallat APIPort)

Om du vill portmoduler som skrivits för Windows PowerShell att arbeta med PowerShell Core börjar du med .NET Portability Analyzer. Kör det här verktyget mot din kompilerade sammansättning för att avgöra om de .NET-API:er som används i modulen är kompatibla med .NET Framework, .NET Core och andra .NET-körningsmiljöer. Verktyget föreslår alternativa API:er om de finns. Annars kan du behöva lägga till körningskontroller och begränsa funktioner som inte är tillgängliga i vissa körningsmiljöer.

Skapa en ny modul

Om du skapar en ny modul rekommenderar vi att du använder .NET CLI.

Installera PowerShell Standard-modulmallen

När .NET CLI har installerats installerar du ett mallbibliotek för att generera en enkel PowerShell-modul. Modulen är kompatibel med Windows PowerShell, PowerShell Core, Windows, Linux och macOS.

I följande exempel visas hur du installerar mallen:

dotnet new -i Microsoft.PowerShell.Standard.Module.Template

  Restoring packages for C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\restore.csproj...
  Installing Microsoft.PowerShell.Standard.Module.Template 0.1.3.
  Generating MSBuild file C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\obj\restore.csproj.nuget.g.props.
  Generating MSBuild file C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\obj\restore.csproj.nuget.g.targets.
  Restore completed in 1.66 sec for C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\restore.csproj.

Usage: new [options]

Options:
  -h, --help          Displays help for this command.
  -l, --list          Lists templates containing the specified name. If no name is specified, lists all templates.
  -n, --name          The name for the output being created. If no name is specified, the name of the current directory is used.
  -o, --output        Location to place the generated output.
  -i, --install       Installs a source or a template pack.
  -u, --uninstall     Uninstalls a source or a template pack.
  --nuget-source      Specifies a NuGet source to use during install.
  --type              Filters templates based on available types. Predefined values are "project", "item" or "other".
  --force             Forces content to be generated even if it would change existing files.
  -lang, --language   Filters templates based on language and specifies the language of the template to create.


Templates                        Short Name         Language          Tags
-----------------------------------------------------------------------------------------------
Console Application              console            [C#], F#, VB      Common/Console
Class library                    classlib           [C#], F#, VB      Common/Library
PowerShell Standard Module       psmodule           [C#]              Library/PowerShell/Module
...

Skapa ett nytt modulprojekt

När mallen har installerats kan du skapa ett nytt PowerShell-modulprojekt med den mallen. I det här exemplet kallas exempelmodulen "myModule".

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...
Running 'dotnet restore' on C:\Users\Steve\myModule\myModule.csproj...
  Restoring packages for C:\Users\Steve\myModule\myModule.csproj...
  Installing PowerShellStandard.Library 5.1.0.
  Generating MSBuild file C:\Users\Steve\myModule\obj\myModule.csproj.nuget.g.props.
  Generating MSBuild file C:\Users\Steve\myModule\obj\myModule.csproj.nuget.g.targets.
  Restore completed in 1.76 sec for C:\Users\Steve\myModule\myModule.csproj.

Restore succeeded.

Skapa modulen

Använd .NET CLI-standardkommandon för att skapa projektet.

dotnet build

PS C:\Users\Steve\myModule> dotnet build
Microsoft (R) Build Engine version 15.7.179.6572 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 76.85 ms for C:\Users\Steve\myModule\myModule.csproj.
  myModule -> C:\Users\Steve\myModule\bin\Debug\netstandard2.0\myModule.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:05.40

Testa modulen

När du har skapat modulen kan du importera den och köra exempel-cmdleten.

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

Felsöka modulen

En guide om hur du konfigurerar Visual Studio Code för att felsöka modulen finns i Använda Visual Studio Code för felsökning av kompilerade cmdletar.

Stödtekniker

I följande avsnitt beskrivs i detalj några av de tekniker som används av den här mallen.

.NET-standardbibliotek

.NET Standard är en formell specifikation av .NET-API:er som är tillgängliga i alla .NET-implementeringar. Hanterad kod för .NET Standard fungerar med de .NET Framework- och .NET Core-versioner som är kompatibla med den versionen av .NET Standard.

Anteckning

Även om det kan finnas ett API i .NET Standard kan API-implementeringen i .NET Core utlösa en PlatformNotSupportedException vid körning, så för att verifiera kompatibiliteten med Windows PowerShell och PowerShell Core är bästa praxis att köra tester för din modul i båda miljöerna. Kör även tester på Linux och macOS om modulen är avsedd att vara plattformsoberoende.

Om du riktar in dig på .NET Standard ser du till att inkompatibla API:er inte oavsiktligt introduceras i modulen när modulen utvecklas. Inkompatibiliteter identifieras vid kompilering i stället för körning.

Det krävs dock inte att .NET Standard används för att en modul ska fungera med både Windows PowerShell och PowerShell Core, förutsatt att du använder kompatibla API:er. Mellanliggande språk (IL) är kompatibelt mellan de två körningarna. Du kan rikta .NET Framework 4.6.1, som är kompatibel med .NET Standard 2.0. Om du inte använder API:er utanför .NET Standard 2.0 fungerar modulen med PowerShell Core 6 utan omkompilering.

PowerShell-standardbibliotek

PowerShell Standard-biblioteket är en formell specifikation av PowerShell-API:er som är tillgängliga i alla PowerShell-versioner som är större än eller lika med versionen av den standarden.

PowerShell Standard 5.1 är till exempel kompatibelt med både Windows PowerShell 5.1 och PowerShell Core 6.0 eller senare.

Vi rekommenderar att du kompilerar modulen med powershell-standardbiblioteket. Biblioteket säkerställer att API:erna är tillgängliga och implementerade i både Windows PowerShell och PowerShell Core 6. PowerShell Standard är avsett att alltid vara framåtkompatibelt. En modul som skapats med PowerShell Standard Library 5.1 är alltid kompatibel med framtida versioner av PowerShell.

Modulmanifest

Anger kompatibilitet med Windows PowerShell och PowerShell Core

När du har verifierat att modulen fungerar med både Windows PowerShell och PowerShell Core bör modulmanifestet uttryckligen ange kompatibilitet med egenskapen CompatiblePSEditions. Värdet Desktop innebär att modulen är kompatibel med Windows PowerShell, medan värdet Core innebär att modulen är kompatibel med PowerShell Core. Att inkludera både Desktop och Core innebär att modulen är kompatibel med både Windows PowerShell och PowerShell Core.

Anteckning

Core innebär inte automatiskt att modulen är kompatibel med Windows, Linux och macOS. Egenskapen CompatiblePSEditions introducerades i PowerShell v5. Modulmanifest som använder egenskapen CompatiblePSEditions kan inte läsas in i versioner före PowerShell v5.

Anger OS-kompatibilitet

Kontrollera först att modulen fungerar i Linux och macOS. Ange sedan kompatibilitet med dessa operativsystem i modulmanifestet. Det gör det enklare för användarna att hitta modulen för sitt operativsystem när de publiceras till PowerShell-galleriet.

I modulmanifestet har egenskapen PrivateData en PSData underegenskap. Den valfria Tags egenskapen för PSData tar en matris med värden som visas i PowerShell-galleriet. PowerShell-galleriet stöder följande kompatibilitetsvärden:

Tagg	Description
PSEdition_Core	Kompatibel med PowerShell Core 6
PSEdition_Desktop	Kompatibel med Windows PowerShell
Windows	Kompatibel med Windows
Linux	Kompatibel med Linux (ingen specifik distribution)
macOS	Kompatibel med macOS

Exempel:

@{
    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 is 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'
        }
    }
}

Beroende av interna bibliotek

Moduler som är avsedda att användas i olika operativsystem eller processorarkitekturer kan vara beroende av ett hanterat bibliotek som i sig är beroende av vissa inbyggda bibliotek.

Före PowerShell 7 måste man ha anpassad kod för att läsa in lämplig intern dll-fil så att det hanterade biblioteket kan hitta den korrekt.

Med PowerShell 7 genomsöks interna binärfiler som ska läsas in i undermappar på det hanterade bibliotekets plats efter en delmängd av .NET RID-katalognotationen .

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