Draagbare modules

Artikel
08/03/2022
8 minuten om te lezen

Windows PowerShell is geschreven voor .NET Framework terwijl PowerShell Core is geschreven voor .NET Core. Draagbare modules zijn modules die werken in zowel Windows PowerShell als PowerShell Core. Hoewel .NET Framework en .NET Core zeer compatibel zijn, zijn er verschillen in de beschikbare API's tussen de twee. Er zijn ook verschillen in de API's die beschikbaar zijn in Windows PowerShell en PowerShell Core. Modules die in beide omgevingen moeten worden gebruikt, moeten rekening houden met deze verschillen.

Een bestaande module overzetten

Een PSSnapIn overzetten

PowerShell SnapIns worden niet ondersteund in PowerShell Core. Het is echter triviaal om een PSSnapIn te converteren naar een PowerShell-module. Normaal gesproken bevindt de PSSnapIn-registratiecode zich in één bronbestand van een klasse die is afgeleid van PSSnapIn. Verwijder dit bronbestand uit de build; Het is niet meer nodig.

Gebruik New-ModuleManifest om een nieuw modulemanifest te maken dat de noodzaak voor de PSSnapIn-registratiecode vervangt. Sommige van de waarden van de PSSnapIn (zoals Beschrijving) kunnen opnieuw worden gebruikt in het modulemanifest.

De eigenschap RootModule in het modulemanifest moet worden ingesteld op de naam van de assembly (dll) die de cmdlets implementeert.

De .NET Portability Analyzer (ook wel APIPort genoemd)

Als u modules wilt overzetten die zijn geschreven voor Windows PowerShell om te werken met PowerShell Core, begint u met .NET Portability Analyzer. Voer dit hulpprogramma uit op uw gecompileerde assembly om te bepalen of de .NET API's die in de module worden gebruikt compatibel zijn met .NET Framework, .NET Core en andere .NET-runtimes. Het hulpprogramma stelt alternatieve API's voor als deze bestaan. Anders moet u mogelijk runtimecontroles toevoegen en mogelijkheden beperken die niet beschikbaar zijn in specifieke runtimes.

Een nieuwe module maken

Als u een nieuwe module maakt, wordt aangeraden de .NET CLI te gebruiken.

De PowerShell Standard-modulesjabloon installeren

Zodra de .NET CLI is geïnstalleerd, installeert u een sjabloonbibliotheek om een eenvoudige PowerShell-module te genereren. De module is compatibel met Windows PowerShell, PowerShell Core, Windows, Linux en macOS.

In het volgende voorbeeld ziet u hoe u de sjabloon installeert:

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
...

Een nieuw moduleproject maken

Nadat de sjabloon is geïnstalleerd, kunt u een nieuw PowerShell-moduleproject maken met behulp van die sjabloon. In dit voorbeeld wordt de voorbeeldmodule 'myModule' genoemd.

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.

De module bouwen

Gebruik standaard .NET CLI-opdrachten om het project te bouwen.

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

De module testen

Nadat u de module hebt gemaakt, kunt u deze importeren en de voorbeeld-cmdlet uitvoeren.

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

Fouten opsporen in de module

Zie Visual Studio Code gebruiken voor het opsporen van fouten in gecompileerde cmdlets voor informatie over het instellen van Visual Studio Code voor het opsporen van fouten in de module.

Ondersteunende technologieën

In de volgende secties worden enkele technologieën beschreven die door deze sjabloon worden gebruikt.

.NET Standard-bibliotheek

.NET Standard is een formele specificatie van .NET API's die beschikbaar zijn in alle .NET-implementaties. Beheerde code die gericht is op .NET Standard, werkt met de .NET Framework- en .NET Core-versies die compatibel zijn met die versie van .NET Standard.

Notitie

Hoewel er mogelijk een API bestaat in .NET Standard, kan de API-implementatie in .NET Core tijdens runtime worden PlatformNotSupportedException gegenereerd, dus om de compatibiliteit met Windows PowerShell en PowerShell Core te controleren, is het raadzaam om tests voor uw module in beide omgevingen uit te voeren. Voer ook tests uit op Linux en macOS als uw module bedoeld is om platformoverschrijdend te zijn.

Door .NET Standard te gebruiken, zorgt u ervoor dat, naarmate de module zich ontwikkelt, niet-compatibele API's niet per ongeluk in de module worden geïntroduceerd. Incompatibiliteit wordt gedetecteerd tijdens het compileren in plaats van runtime.

Het is echter niet vereist om .NET Standard te gebruiken voor een module om te werken met zowel Windows PowerShell als PowerShell Core, zolang u compatibele API's gebruikt. De tussenliggende taal (IL) is compatibel tussen de twee runtimes. U kunt zich richten op .NET Framework 4.6.1, dat compatibel is met .NET Standard 2.0. Als u geen API's buiten .NET Standard 2.0 gebruikt, werkt uw module met PowerShell Core 6 zonder opnieuw te compileren.

Standaardbibliotheek voor PowerShell

De PowerShell Standard-bibliotheek is een formele specificatie van PowerShell-API's die beschikbaar zijn in alle PowerShell-versies die groter zijn dan of gelijk zijn aan de versie van die standaard.

PowerShell Standard 5.1 is bijvoorbeeld compatibel met zowel Windows PowerShell 5.1 als PowerShell Core 6.0 of hoger.

U wordt aangeraden uw module te compileren met behulp van de Standaardbibliotheek van PowerShell. De bibliotheek zorgt ervoor dat de API's beschikbaar en geïmplementeerd zijn in zowel Windows PowerShell als PowerShell Core 6. PowerShell Standard is bedoeld om altijd compatibel te zijn met doorsturen. Een module die is gebouwd met PowerShell Standard Library 5.1, is altijd compatibel met toekomstige versies van PowerShell.

Modulemanifest

Compatibiliteit met Windows PowerShell en PowerShell Core aangeven

Nadat u hebt geverifieerd dat uw module werkt met zowel Windows PowerShell als PowerShell Core, moet het modulemanifest expliciet de compatibiliteit aangeven met behulp van de eigenschap CompatiblePSEditions. Een waarde van Desktop betekent dat de module compatibel is met Windows PowerShell, terwijl een waarde van Core betekent dat de module compatibel is met PowerShell Core. Inclusief beide Desktop en Core betekent dat de module compatibel is met zowel Windows PowerShell als PowerShell Core.

Notitie

Core betekent niet automatisch dat de module compatibel is met Windows, Linux en macOS. De eigenschap CompatiblePSEditions is geïntroduceerd in PowerShell v5. Modulemanifesten die gebruikmaken van de eigenschap CompatiblePSEditions kunnen niet worden geladen in versies vóór PowerShell v5.

Compatibiliteit van besturingssysteem aangeven

Controleer eerst of uw module werkt in Linux en macOS. Geef vervolgens de compatibiliteit met die besturingssystemen in het modulemanifest aan. Hierdoor kunnen gebruikers uw module gemakkelijker vinden voor hun besturingssysteem wanneer ze naar de PowerShell Gallery worden gepubliceerd.

Binnen het modulemanifest heeft de PrivateData eigenschap een PSData subeigenschap. De optionele Tags eigenschap van PSData neemt een matrix met waarden die worden weergegeven in PowerShell Gallery. De PowerShell Gallery ondersteunt de volgende compatibiliteitswaarden:

Tag	Description
PSEdition_Core	Compatibel met PowerShell Core 6
PSEdition_Desktop	Compatibel met Windows PowerShell
Windows	Compatibel met Windows
Linux	Compatibel met Linux (geen specifieke distributie)
macOS	Compatibel met macOS

Voorbeeld:

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

Afhankelijkheid van systeemeigen bibliotheken

Modules die zijn bedoeld voor gebruik in verschillende besturingssystemen of processorarchitecturen kunnen afhankelijk zijn van een beheerde bibliotheek die zelf afhankelijk is van sommige systeemeigen bibliotheken.

Vóór PowerShell 7 zou men aangepaste code moeten hebben om de juiste systeemeigen DLL te laden, zodat de beheerde bibliotheek deze correct kan vinden.

Met PowerShell 7 worden systeemeigen binaire bestanden die moeten worden geladen, doorzocht in submappen binnen de locatie van de beheerde bibliotheek na een subset van de .NET RID-catalogusnotatie .

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