A megfelelő PowerShell NuGet-csomag kiválasztása a .NET-projekthez

Az egyes PowerShell-kiadásokkal közzétett végrehajtható csomagok mellett pwsh a PowerShell csapata számos NuGet-csomagot is fenntart. Ezek a csomagok lehetővé teszik a PowerShell API-platformként való megcélzását a .NET-ben.

Az API-kat biztosító .NET-alkalmazásként, amely a saját (bináris) modulokat megvalósító .NET-kódtárak betöltésére számít, elengedhetetlen, hogy a PowerShell NuGet-csomag formájában legyen elérhető.

Jelenleg több NuGet-csomag is létezik, amelyek a PowerShell API felületének valamilyen ábrázolását biztosítják. Az adott projekthez használandó csomag nem mindig egyértelmű. Ez a cikk néhány gyakori forgatókönyvet mutat be a PowerShell-alapú .NET-projektek megcélzásához, és hogy hogyan választhatja ki a PowerShell-orientált .NET-projekthez megfelelő NuGet-csomagot.

Üzemeltetés és hivatkozás

Egyes .NET-projektek olyan kódot szeretnének írni, amelyet egy már meglévő PowerShell-futtatókörnyezetbe (például pwshpowershell.exea PowerShell integrált konzoljába vagy az ISE-be) szeretnének betölteni, míg mások a PowerShellt a saját alkalmazásaikban szeretnék futtatni.

  • A hivatkozás arra az állapotra vonatkozik, amikor egy projekt , általában egy modul a PowerShellbe való betöltésére szolgál. A PowerShell által biztosított API-k alapján kell lefordítani, de a PowerShell-implementációt a PowerShell-folyamat biztosítja, amelybe betölti. Hivatkozás esetén a projekt referenciaszerelvényeket vagy a tényleges futtatókörnyezeti szerelvényeket használhat fordítási célként, de gondoskodnia kell arról, hogy ezek egyikét sem tegye közzé a buildel együtt.
  • Az üzemeltetés az, amikor egy projektnek saját PowerShell-implementációra van szüksége, általában azért, mert egy különálló alkalmazásról van szó, amelynek a PowerShellt kell futtatnia. Ebben az esetben a tiszta referenciaszerelvények nem használhatók. Ehelyett egy konkrét PowerShell-implementációtól kell függenie. Mivel konkrét PowerShell-implementációt kell használni, a PowerShell egy adott verzióját kell kiválasztani az üzemeltetéshez; egyetlen gazdaalkalmazás nem tud több PowerShell-verziót megcélzni.

A PowerShellt referenciaként megcélzó projektek közzététele

Megjegyzés

A cikkben a közzététel kifejezéssel hivatkozunk a futtatásra dotnet publish, amely egy .NET-kódtárat helyez egy könyvtárba az összes függőségével együtt, és készen áll egy adott futtatókörnyezetben való üzembe helyezésre.

A csak fordítási referenciapéldányként használt projektfüggőségek közzétételének megakadályozása érdekében ajánlott beállítani a PrivateAssets attribútumot :

<PackageReference Include="PowerShellStandard.Library" Version="5.1.0.0" PrivateAssets="all" />

Ha elfelejti ezt megtenni, és referenciaszerelvényt használ célként, előfordulhat, hogy a referencia-szerelvény alapértelmezett implementációjának használatával kapcsolatos problémák merülnek fel a tényleges implementáció helyett. Ez egy , mivel a NullReferenceExceptionreferenciaszerelvények gyakran egyszerűen visszaadva nullutánozza az implementációs API-t.

A PowerShell-alapú .NET-projektek fő típusai

Bár bármely .NET-kódtár vagy -alkalmazás beágyazhatja a PowerShellt, vannak olyan gyakori forgatókönyvek, amelyek PowerShell API-kat használnak:

  • Bináris PowerShell-modul implementálása

    A PowerShell bináris moduljai a PowerShell által betöltött .NET-kódtárak, amelyeknek PowerShell API-kat kell implementálniuk, például a PSCmdlet vagy a CmdletProvider típusokat a parancsmagok vagy szolgáltatók közzétételéhez. Mivel be vannak töltve, a modulok a PowerShellre mutató hivatkozások alapján próbálnak fordítást készíteni anélkül, hogy közzétennének a buildben. Gyakran előfordul, hogy a modulok több PowerShell-verziót és -platformot szeretnének támogatni, ideális esetben minimális lemezterülettel, összetettséggel vagy ismétlődő implementációval. A modulokkal kapcsolatos további információkért lásd about_Modules.

  • PowerShell-gazdagép megvalósítása

    A PowerShell-gazdagépek interakciós réteget biztosítanak a PowerShell-futtatókörnyezethez. Ez az üzemeltetés egy speciális formája, ahol a PSHost a PowerShell új felhasználói felületeként van megvalósítva. A PowerShell ConsoleHost például egy terminál felhasználói felületet biztosít a PowerShell-végrehajtható fájlokhoz, míg a PowerShell-szerkesztőszolgáltatások gazdagépe és az ISE-gazdagép egyaránt egy szerkesztővel integrált, részben grafikus felhasználói felületet biztosít a PowerShell körül. Bár egy gazdagép betölthető egy meglévő PowerShell-folyamatba, sokkal gyakoribb, hogy egy gazdagép-implementáció önálló PowerShell-implementációként működik, amely újra elosztja a PowerShell-motort.

  • Hívás a PowerShellbe egy másik .NET-alkalmazásból

    Mint minden alkalmazás, a PowerShell is meghívható alfolyamatként a számítási feladatok futtatásához. .NET-alkalmazásként azonban a PowerShellt is meghívhatja folyamatban, hogy teljes .NET-objektumokat kapjon vissza a hívó alkalmazásban való használathoz. Ez egy általánosabb üzemeltetési forma, amelyben az alkalmazás saját PowerShell-implementációt használ belső használatra. Ilyen lehet például egy PowerShellt futtató szolgáltatás vagy démon, amely a gép állapotát kezeli, vagy egy webalkalmazás, amely kérésre Futtatja a PowerShellt, például a felhőbeli üzemelő példányok kezeléséhez.

  • PowerShell-modulok egységtesztelése a .NET-ből

    Bár a PowerShell funkcióinak közzétételére tervezett modulokat és más kódtárakat elsősorban a PowerShellből kell tesztelni (a Pestert javasoljuk), néha szükség van a .NET-ből származó PowerShell-modulhoz írt API-k egységtesztelési API-jaira. Ebben a helyzetben a modulkód több PowerShell-verziót próbál meg megcélolni, a tesztelés során pedig konkrét implementációkon kell futtatni.

A PowerShell NuGet-csomagok áttekintése

Ebben a cikkben a következő NuGet-csomagokat tárgyaljuk, amelyek PowerShell API-kat fednek le:

  • A PowerShellStandard.Library egy referenciaszerelvény, amely lehetővé teszi egyetlen, több PowerShell-futtatókörnyezet által betölthető szerelvény összeállítását.
  • Microsoft.PowerShell.SDK, a teljes PowerShell SDK célhelye és áthelyezése
  • A System.Management.Automation csomag, az alapvető PowerShell-futtatókörnyezet és motor-implementáció, amely minimálisan üzemeltetett implementációkban és verzióspecifikus célzási forgatókönyvekben lehet hasznos.
  • A Windows PowerShell referenciaszerelvények, a Windows PowerShell célzásának és hatékony áthelyezése (a PowerShell 5.1-s és újabb verziói).

Megjegyzés

A PowerShell NuGet-csomag egyáltalán nem .NET-kódtárcsomag, hanem a PowerShell dotnet globális eszköz-implementációt biztosítja. Ezt egyetlen projekt sem használhatja, mivel csak végrehajtható fájlt biztosít.

PowerShellStandard.Library

A PowerShell Standard kódtár egy referenciaszerelvény, amely rögzíti a PowerShell 7., 6. és 5.1-ös verziójának API-k metszetét. Ez egy fordítási időre ellenőrzött API-felületet biztosít a .NET-kód fordításához, amely lehetővé teszi, hogy a .NET-projektek a PowerShell 7-es, 6-os és 5.1-es verzióját célba érik anélkül, hogy egy olyan API meghívását kockáztatják, amely nem lesz ott.

A PowerShell Standard PowerShell-modulok írására szolgál, vagy más, csak a PowerShell-folyamatba való betöltés után futtatandó kód. Mivel referenciaszerelvényről van szó, a PowerShell Standard önmagában nem tartalmaz implementációt, ezért nem biztosít funkciókat önálló alkalmazásokhoz.

A PowerShell Standard használata különböző .NET-futtatókörnyezetekkel

A PowerShell Standard a .NET Standard 2.0-s cél futtatókörnyezetet célozza, amely egy homlokzati futtatókörnyezet, amely .NET-keretrendszer és a .NET Core közös felületének biztosítására lett kialakítva. Ez lehetővé teszi, hogy egyetlen futtatókörnyezet egyetlen szerelvényt hoz létre, amely több PowerShell-verzióval fog működni, de a következő következményekkel jár:

  • A modult vagy kódtárat betöltő PowerShellnek legalább .NET 4.6.1-et kell futtatnia; a .NET 4.6 és a .NET 4.5.2 nem támogatja a .NET Standardot. Vegye figyelembe, hogy az újabb Windows PowerShell verzió nem jelent újabb .NET-keretrendszer verziót; Windows PowerShell 5.1 a .NET 4.5.2-en futhat.
  • A 4.7.1-.NET-keretrendszer vagy újabb verziót futtató PowerShell használatához a .NET 4.6.1 NETStandard.Library implementációra van szükség ahhoz, hogy a netstandard.dll és a régebbi .NET-keretrendszer verziókban található egyéb shim szerelvényeket biztosíthassa.

A PowerShell 6+ saját shim szerelvényeket biztosít a típustovábbításhoz a .NET-keretrendszer 4.6.1-es (és újabb) rendszerekről a .NET Core-ba. Ez azt jelenti, hogy amíg egy modul csak a .NET Core-ban létező API-kat használ, a PowerShell 6+ betöltheti és futtathatja, ha .NET-keretrendszer 4.6.1-hez készült (a net461 futtatókörnyezeti célhoz).

Ez azt jelenti, hogy a PowerShell Standardot használó bináris modulok több PowerShell-verziót céloznak meg egyetlen közzétett DLL-vel, két lehetőség közül választhatnak:

  1. A cél futtatókörnyezethez net461 készült szerelvény közzététele. Ez a következőket foglalja magában:

    • A projekt közzététele a net461 futtatókörnyezetben
    • A futtatókörnyezetre netstandard2.0 is lefordítva (a buildkimenet használata nélkül), hogy az összes használt API megtalálható legyen a .NET Core-ban is.
  2. Szerelvény buildjének közzététele a netstandard2.0 cél futtatókörnyezethez. Ehhez a következőre van szükség:

    • A projekt közzététele a netstandard2.0 futtatókörnyezetben
    • Vegye figyelembe a net461 NETStandard.Library függőségeit, és másolja őket a projektszerelvény közzétételi helyére, hogy a szerelvény típustovábbítási javítása .NET-keretrendszer.

Ha a régebbi .NET-keretrendszer verziókat célzó PowerShell-modulokat vagy -kódtárakat szeretne létrehozni, érdemes lehet több .NET-futtatókörnyezetet is megcélznia. Ez minden cél-futtatókörnyezethez közzétesz egy szerelvényt, és a megfelelő szerelvényt a modul betöltési ideje alatt kell betölteni (például egy kis psm1-gyökerű modullal).

PowerShell Standard-projektek tesztelése a .NET-ben

Ha a modult az xUnithoz hasonló .NET-tesztfuttatókban teszteli, ne feledje, hogy a fordítási idő ellenőrzése csak eddig megy. A modult a megfelelő PowerShell-platformokon kell tesztelnie.

A .NET-ben a PowerShell Standard alapján létrehozott API-k teszteléséhez a .NET Core-jal (a kívánt PowerShell-verziónak megfelelő verzióval) és a .NET-keretrendszer megfelelő Windows PowerShell referenciaszerelvényekkel kell tesztelniMicrosoft.Powershell.SDK.

A PowerShell Standardról és a több PowerShell-verzióban használható bináris modul megírásáról ebben a blogbejegyzésben talál további információt. Tekintse meg a PowerShell Standard-adattárat a GitHubon.

Microsoft.PowerShell.SDK

Microsoft.PowerShell.SDK A egy metacsomag, amely a PowerShell SDK összes összetevőjét egyetlen NuGet-csomagba húzza. Egy önálló .NET-alkalmazás a Microsoft.PowerShell.SDK használatával tetszőleges PowerShell-funkciókat futtathat külső PowerShell-telepítések vagy -tárak nélkül.

Megjegyzés

A PowerShell SDK csak a PowerShellt alkotó összes összetevőcsomagra hivatkozik, és amely a PowerShell-lel való .NET-fejlesztéshez használható.

Egy adott Microsoft.Powershell.SDK verzió a PowerShell-alkalmazás ugyanazon verziójának konkrét implementációját tartalmazza; a 7.0-s verzió a PowerShell 7.0 implementációját tartalmazza, és a parancsok vagy szkriptek futtatása nagyrészt úgy fog viselkedni, mintha a PowerShell 7.0-ban futtatta volna őket.

A PowerShell-parancsok az SDK-ból való futtatása többnyire, de nem teljesen ugyanaz, mint az SDK-ból pwshvaló futtatásuk. A start-job például jelenleg attól függ, hogy a pwsh végrehajtható fájl elérhető-e, így alapértelmezés szerint nem fog működni Microsoft.Powershell.SDK .

A .NET-alkalmazásokból történő célzás Microsoft.Powershell.SDK lehetővé teszi, hogy integrálható legyen a PowerShell összes implementációs szerelvényével, például System.Management.Automationa , Microsoft.PowerShell.Managementés más modulszerelvényekkel.

Az alkalmazáscélzás Microsoft.Powershell.SDK közzététele magában foglalja az összes ilyen szerelvényt, és a PowerShell által igényelt függőségeket. Emellett a PowerShell által a buildben megkövetelt egyéb eszközöket is tartalmazni fog, például a modulok moduljegyzékeit Microsoft.PowerShell.* és a refbővítménytípus által igényelt könyvtárat.

A teljesség Microsoft.Powershell.SDKcéljából a következő célokra alkalmas:

  • PowerShell-gazdagépek implementálása.
  • A PowerShell-referenciaszerelvényeket célzó kódtárak xUnit-tesztelése.
  • Folyamaton belüli PowerShell meghívása .NET-alkalmazásból.

Microsoft.PowerShell.SDK referenciacélként is használható, ha a .NET-projektet modulként vagy más módon a PowerShell tölti be, de attól függ, hogy az API-k csak a PowerShell egy adott verziójában vannak-e jelen. Vegye figyelembe, hogy egy adott verzióhoz Microsoft.PowerShell.SDK közzétett szerelvény csak a PowerShell adott verziójában tölthető be és használható biztonságosan. Ahhoz, hogy több PowerShell-verziót célozzon meg adott API-kkal, több buildre van szükség, amelyek mindegyike a saját verzióját Microsoft.Powershell.SDKcélozza.

Megjegyzés

A PowerShell SDK csak a PowerShell 6-os és újabb verzióihoz érhető el. A Windows PowerShell megfelelő funkcióinak biztosításához használja az alább ismertetett Windows PowerShell referenciaszerelvényeket.

System.Management.Automation

A System.Management.Automation csomag a PowerShell SDK központja. Elsősorban a NuGeten létezik, mint a lekéréshez szükséges Microsoft.Powershell.SDK eszköz. Azonban közvetlenül csomagként is használható kisebb üzemeltetési forgatókönyvekhez és verziócélzási modulokhoz.

Pontosabban a System.Management.Automation csomag lehet a PowerShell-funkciók előnyben részesítő szolgáltatója, ha:

  • Csak a PowerShell nyelvi funkcióit szeretné használni (a System.Management.Automation.Language névtérben), például a PowerShell-elemzőt, az AST-t és az AST látogatói API-kat (például a PowerShell statikus elemzéséhez).
  • Csak bizonyos parancsokat szeretne végrehajtani a Microsoft.PowerShell.Core modulból, és a CreateDefault2 factory metódussal létrehozott munkamenet-állapotban hajthatja végre őket.

Emellett hasznos referenciaszerelvény, System.Management.Automation ha:

  • Olyan API-kat szeretne célba venni, amelyek csak egy adott PowerShell-verzióban vannak jelen
  • Nem függ a szerelvényen kívül System.Management.Automation előforduló típusoktól (például a modulok parancsmagjai Microsoft.PowerShell.* által exportált típusoktól).

referenciaszerelvények Windows PowerShell

A PowerShell 5.1-s és régebbi verziói (Windows PowerShell) esetében nincs olyan SDK, amely a PowerShell implementációját biztosíthassa, mivel Windows PowerShell implementációja a Windows része.

Ehelyett a Windows PowerShell referenciaszerelvények referenciacélokat és a Windows PowerShell áthelyezhetőek, ugyanúgy, mint a PowerShell SDK a 6-os és újabb verziók esetében.

Ahelyett, hogy verziónként megkülönböztetné őket, Windows PowerShell referenciaszerelvények a Windows PowerShell minden egyes verziójához külön csomagban rendelkeznek:

A Windows PowerShell referenciaszerelvények használatával kapcsolatos információk a Windows PowerShell SDK-ban találhatók.

Valós példák ezekre a NuGet-csomagokra

A különböző PowerShell-eszközprojektek az igényeiktől függően különböző PowerShell NuGet-csomagokat céloznak meg. Az alábbiakban néhány figyelemre méltó példát láthat.

PSReadLine

A PSReadLine, a PowerShell-modul, amely a PowerShell gazdag konzolélményének nagy részét biztosítja, a PowerShell Standardet egy adott PowerShell-verzió helyett függőségként célozza meg, és a net461 .NET-futtatókörnyezetet célozza meg a csprojban.

A PowerShell 6+ saját segédszerelvényeket biztosít, amelyek lehetővé teszik, hogy a net461 futtatókörnyezetet célzó DLL "csak működjön", amikor betöltődik (a kötés átirányításával .NET-keretrendszer mscorlib.dll a megfelelő .NET Core-szerelvényhez).

Ez jelentősen leegyszerűsíti a PSReadLine modulelrendezését és kézbesítését, mivel a PowerShell Standard biztosítja, hogy az egyetlen használt API-k mind a PowerShell 5.1-ben, mind a PowerShell 6+-ban jelen legyenek, ugyanakkor lehetővé teszi, hogy a modul csak egyetlen szerelvényt szállítson.

A .NET 4.6.1-cél azt jelenti, hogy a .NET 4.5.2-n és a .NET 4.6-on futó Windows PowerShell azonban nem támogatott.

PowerShell-szerkesztőszolgáltatások

A PowerShell Editor Services (PSES) a Visual Studio CodePowerShell-bővítményének háttérrendszere, amely valójában a PowerShell-modul egy olyan formája, amelyet egy Végrehajtható PowerShell tölt be, majd átveszi ezt a folyamatot a PowerShell önmagában történő újratelepítéséhez, miközben nyelvi szolgáltatási protokollt és hibakeresési adapterfunkciókat is biztosít.

A PSES konkrét megvalósítási célokat biztosít a PowerShell 6+ megcélzásához netcoreapp2.1 (mivel a PowerShell 7 futtatókörnyezete netcoreapp3.1 visszamenőlegesen kompatibilis) és net461 Windows PowerShell 5.1-et céloz meg, de a logikája nagy részét egy második szerelvényben tartalmazza, amely a PowerShell Standardot célozza netstandard2.0 meg. Ez lehetővé teszi, hogy lekérje a .NET Core-hoz és .NET-keretrendszer platformokhoz szükséges függőségeket, miközben továbbra is leegyszerűsíti a kódbázis nagy részét egy egységes absztrakció mögött.

Mivel a PowerShell Standardra épül, a PSES-hez a PowerShell futtatókörnyezeti implementációjára van szükség a megfelelő teszteléshez. Ehhez a PSES xUnit-tesztjei be Microsoft.PowerShell.SDK - és Microsoft.PowerShell.5.ReferenceAssemblies lekérnek egy PowerShell-implementációt a tesztkörnyezetben.

A PSReadLine-hoz hasonlóan a PSES nem támogatja a .NET 4.6-os vagy újabb verzióit, de futtatáskor ellenőrzi, hogy meghívja-e azokat az API-kat, amelyek összeomlást okozhatnak az alsó .NET-keretrendszer futtatókörnyezetekben.

PSScriptAnalyzer

A PSScriptAnalyzernek, a PowerShell linterének csak a PowerShell bizonyos verzióiban bevezetett szintaktikai elemeket kell céloznia. Mivel ezeknek a szintaktikai elemeknek a felismerése egy AstVisitor2 implementálásával történik, nem használható a PowerShellStandard, és nem valósítható meg AST látogatói metódus az újabb PowerShell-szintaxisokhoz.

Ehelyett a PSScriptAnalyzer minden PowerShell-verziót buildkonfigurációként céloz meg, és mindegyikhez külön DLL-t hoz létre. Ez növeli a build méretét és összetettségét, de lehetővé teszi a következőt:

  • Verzióspecifikus API-célzás
  • Verzióspecifikus funkciók, amelyek implementálása alapvetően futásidejű költségek nélkül történik
  • A Windows PowerShell teljes támogatása egészen a .NET-keretrendszer 4.5.2-.NET-keretrendszer

Összefoglalás

Ebben a cikkben felsoroltuk és megvitattuk a PowerShellt használó .NET-projektek implementálásakor elérhető NuGet-csomagokat, valamint az egymáshoz való használat lehetséges okait.

Ha kihagyta az összefoglalást, néhány általános javaslat a következő:

  • A PowerShell-modulokat a PowerShell Standard alapján kell lefordítani, ha csak a különböző PowerShell-verziókban közös API-kat igényelnek.
  • Azoknak a PowerShell-gazdagépeknek és alkalmazásoknak, amelyeknek belsőleg kell futtatniuk a PowerShellt, a PowerShell 6+-hoz készült PowerShell SDK-t vagy a Windows PowerShell vonatkozó Windows PowerShell referenciaszerelvényeit kell céloznia.
  • A verzióspecifikus API-kat igénylő PowerShell-moduloknak a PowerShell SDK-t vagy Windows PowerShell referenciaszerelvényeket kell célozniuk a szükséges PowerShell-verziókhoz, referenciaszerelvényként használva őket (azaz nem kell közzétenniük a PowerShell-függőségeket).