Přenosné moduly

Článek
2025-02-05

Windows PowerShell je napsaný pro .NET Framework, zatímco PowerShell Core je napsaný pro .NET Core. Přenosné moduly jsou moduly, které fungují v prostředí Windows PowerShell i PowerShell Core. I když jsou rozhraní .NET Framework a .NET Core vysoce kompatibilní, existují rozdíly v dostupných rozhraních API mezi těmito dvěma rozhraními. Existují také rozdíly v rozhraních API dostupných ve Windows PowerShellu a PowerShellu Core. Moduly určené k použití v obou prostředích musí mít na paměti tyto rozdíly.

Přenos existujícího modulu

Převedení PSSnapIn

PowerShell SnapIns se v PowerShellu Core nepodporují. Převod PSSnapIn na modul PowerShellu je ale triviální. Registrační kód PSSnapIn je obvykle v jednom zdrojovém souboru třídy, který je odvozen z PSSnapIn. Odeberte tento zdrojový soubor ze sestavení; už to není potřeba.

Pomocí New-ModuleManifest vytvořte nový manifest modulu, který nahrazuje potřebu registračního kódu PSSnapIn. Některé hodnoty z PSSnapIn (například Popis) je možné znovu použít v manifestu modulu.

Vlastnost RootModule v manifestu modulu by měla být nastavena na název sestavení (.dll) implementující rutiny.

Analyzátor přenositelnosti .NET (neboli APIPort)

Pokud chcete portovat moduly napsané pro prostředí Windows PowerShell, aby pracovaly s PowerShell Core, začněte nástrojem Analyzátor přenositelnosti .NET. Spusťte tento nástroj na kompilované sestavení, abyste zjistili, jestli jsou rozhraní .NET API použitá v modulu kompatibilní s .NET Framework, .NET Core a dalšími běhovými prostředími .NET. Nástroj navrhuje alternativní rozhraní API, pokud existují. Jinak možná budete muset přidat běhové kontroly a omezit možnosti, které nejsou dostupné v konkrétních běhových prostředích.

Vytvoření nového modulu

Pokud vytváříte nový modul, doporučujeme použít rozhraní příkazového řádku .NET CLI.

Instalace šablony modulu PowerShell Standard

Po instalaci rozhraní příkazového řádku .NET nainstalujte knihovnu šablon pro vygenerování jednoduchého modulu PowerShellu. Modul bude kompatibilní s Windows PowerShellem, PowerShellem Core, Windows, Linuxem a macOS.

Následující příklad ukazuje, jak nainstalovat šablonu:

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

Vytvoření nového projektu modulu

Po instalaci šablony můžete pomocí této šablony vytvořit nový projekt modulu PowerShellu. V tomto příkladu se ukázkový modul nazývá 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...
Restoring  C:\Users\Steve\myModule\myModule.csproj:
  Determining projects to restore...
  Restored C:\Users\Steve\myModule\myModule.csproj (in 184 ms).
Restore succeeded.

Sestavení modulu

K sestavení projektu použijte standardní příkazy rozhraní příkazového řádku .NET.

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

Testování modulu

Po sestavení modulu ho můžete importovat a spustit ukázkovou rutinu.

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

Ladění modulu

Průvodce nastavením editoru Visual Studio Code pro ladění modulu najdete v tématu Použití editoru Visual Studio Code pro ladění kompilovaných rutin.

Podpůrné technologie

Následující části podrobně popisují některé technologie používané touto šablonou.

Knihovna .NET Standard

.NET Standard je formální specifikace rozhraní .NET API, která jsou k dispozici ve všech implementacích .NET. Spravovaný kód určený pro .NET Standard funguje s verzemi .NET Framework a .NET Core, které jsou kompatibilní s danou verzí .NET Standard.

Poznámka

I když rozhraní API může existovat ve standardu .NET Standard, implementace rozhraní API v .NET Core může za běhu vyvolat PlatformNotSupportedException, aby se ověřila kompatibilita s Windows PowerShellem a PowerShellem Core, osvědčeným postupem je spustit testy pro modul v obou prostředích. Pokud je váš modul určený pro různé platformy, spusťte také testy v Linuxu a macOS.

Cílení na .NET Standard pomáhá zajistit, aby se při vývoji nechtěně do modulu nevnesla nekompatibilní rozhraní API. Nekompatibility jsou zjištěny během kompilace místo za běhu programu.

Pokud ale používáte kompatibilní rozhraní API, není nutné cílit na .NET Standard, aby modul fungoval s Windows PowerShellem i PowerShellem Core. Mezikód (IL) je kompatibilní pro oba runtime. Můžete cílit na rozhraní .NET Framework 4.6.1, který je kompatibilní s rozhraním .NET Standard 2.0. Pokud nepoužíváte rozhraní API mimo .NET Standard 2.0, bude modul fungovat s PowerShellEm Core 6 bez rekompilace.

Standardní knihovna PowerShellu

Knihovna PowerShell Standard je formální specifikace rozhraní API PowerShellu dostupná ve všech verzích PowerShellu větších nebo rovných této verze standardu.

Například PowerShell Standard 5.1 je kompatibilní s Windows PowerShellem 5.1 a PowerShellem Core 6.0 nebo novějším.

Doporučujeme zkompilovat modul pomocí standardní knihovny PowerShellu. Knihovna zajišťuje, že rozhraní API jsou dostupná a implementovaná v prostředí Windows PowerShell i PowerShell Core 6. PowerShell Standard je určený k tomu, aby byl vždy kompatibilní s budoucími verzemi. Modul vytvořený pomocí standardní knihovny PowerShellu 5.1 bude vždy kompatibilní s budoucími verzemi PowerShellu.

Manifest modulu

Indikující kompatibilitu s Windows PowerShellem a PowerShellem Core

Po ověření, že modul funguje s Windows PowerShellem i PowerShellem Core, by manifest modulu měl explicitně indikovat kompatibilitu pomocí vlastnosti CompatiblePSEditions. Hodnota Desktop znamená, že modul je kompatibilní s Windows PowerShell, zatímco hodnota Core znamená, že modul je kompatibilní s PowerShell Core. Zahrnutím Desktop i Core znamená, že modul je kompatibilní s Windows PowerShellem i PowerShellem Core.

Poznámka

Core neznamená, že modul je kompatibilní s Windows, Linuxem a macOS. Vlastnost CompatiblePSEditions byla zavedena v PowerShellu v5. Manifesty modulů, které používají vlastnost CompatiblePSEditions, se nepodaří načíst ve verzích před PowerShellem v5.

Indikující kompatibilitu operačního systému

Nejprve ověřte, že váš modul funguje v Linuxu a macOS. Dále uveďte kompatibilitu s těmito operačními systémy v manifestu modulu. To uživatelům usnadňuje vyhledání modulu pro svůj operační systém při publikování do Galerie Prostředí PowerShell.

V manifestu modulu má vlastnost PrivateData dílčí vlastnost PSData. Volitelná vlastnost Tags u PSData přijímá pole hodnot, které se zobrazí v PowerShell Gallery. Galerie Prostředí PowerShell podporuje následující hodnoty kompatibility:

Značka	Popis
PSEdition_Core	Kompatibilní s PowerShellem Core 6
PSEdition_Desktop	Kompatibilní s Prostředím Windows PowerShell
Windows	Kompatibilní s Windows
Linux	Kompatibilní s Linuxem (bez konkrétní distribuce)
macOS	Kompatibilní s macOS

Příklad:

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

Závislost na nativních knihovnách

Moduly určené pro použití v různých operačních systémech nebo architekturách procesorů můžou záviset na spravované knihovně, která sama závisí na některých nativních knihovnách.

Před PowerShellem 7 byste museli mít vlastní kód pro načtení příslušné nativní knihovny DLL, aby ji spravovaná knihovna našla správně.

V PowerShellu 7 se nativní binární soubory, které se mají načíst, prohledávají v podsložkách v umístění spravované knihovny za podmnožinou zápisu katalogu identifikátorů RID .NET.

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

Sdílet prostřednictvím