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

Az egyes PowerShell-kiadásokban közzétett végrehajtható csomagok mellett pwsh a PowerShell-csapat több NuGet-en elérhető csomagot is tart fenn. Ezek a csomagok lehetővé teszik a PowerShell api-platformként való célzását a .NET-ben.

.NET-alkalmazásként, amely API-kat biztosít, és 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 némi megjelenítését biztosítják. Az adott projekthez használandó csomag nem mindig egyértelmű. Ez a cikk bemutatja a PowerShell-alapú .NET-projektek néhány gyakori forgatókönyvét, valamint azt, hogyan választhatja ki a powerShell-orientált .NET-projekthez megfelelő NuGet-csomagot.

Üzemeltetés és hivatkozás

Egyes .NET-projektek egy már meglévő PowerShell-futtatókörnyezetbe (például pwshpowershell.exea PowerShell integrált konzoljára vagy az I Standard kiadás) való betöltendő kód írására törekszenek, míg mások a PowerShellt a saját alkalmazásaikban szeretnék futtatni.

• A hivatkozás arra az esetben vonatkozik, ha 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éssel.
• A ü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 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 gazdagépalkalmazás nem tud több célként megadott PowerShell-verziót létrehozni.

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

Feljegyzés

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

Annak érdekében, hogy megakadályozza az éppen fordítási referenciacélként használt projektfüggőségek közzétételét, 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 referencia-szerelvényt használ célként, előfordulhat, hogy a referencia-szerelvény alapértelmezett implementációjának a tényleges implementáció helyett való használatával kapcsolatos problémákat tapasztal. Ennek formája lehet egy NullReferenceException, mivel a referencia-szerelvények gyakran egyszerűen visszaadva szimulálják a megvalósítási API-t null.

A PowerShell-célzott .NET-projektek főbb típusai

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

• 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. Az is gyakori, 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ő megvalósítással. A modulokról további információt a about_Modules talál.

• PowerShell-gazdagép implementálása

  A PowerShell-gazdagépek interakciós réteget biztosítanak a PowerShell-futtatókörnyezethez. Ez egy adott üzemeltetési forma, ahol a PSHost a PowerShell új felhasználói felületeként van implementálva. 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 I Standard kiadás 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 a 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 esetén, 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álatra. Ez egy általánosabb üzemeltetési forma, ahol 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 a gépállapot kezeléséhez, vagy egy olyan webalkalmazás, amely kérésre Futtatja a PowerShellt, például a felhőbeli üzemelő példányok felügyeletére.

• 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 (javasoljuk a Pestert), néha szükség van a .NET-ből származó PowerShell-modulhoz írt API-k egységtesztelésére. Ebben a helyzetben a modulkód több PowerShell-verziót próbál meg célozni, 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 szerelvény összeállítását, amelyet több PowerShell-futtatókörnyezet is betölthet.
• Microsoft.PowerShell.SDK, a teljes PowerShell SDK megcélzásának és újbóli tárolásának módja
• A System.Management.Automation csomag, amely a PowerShell-futtatókörnyezet és a motor alapvető implementációja, amely hasznos lehet a minimálisan üzemeltetett implementációkban és a verzióspecifikus célzási forgatókönyvekben.
• A Windows PowerShell referenciaszerelvényei, a Windows PowerShell célzásának és hatékony újrahelyének módja (a PowerShell 5.1-s és újabb verziói).

Feljegyzés

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

PowerShellStandard.Library

A PowerShell Standard kódtár egy referencia-szerelvény, amely rögzíti a PowerShell 7., 6. és 5.1-ös verziójának API-jainak 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, így a .NET-projektek a PowerShell 7-es, 6-os és 5.1-es verzióit 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ése után futtatandó kódra. Mivel ez egy referencia-szerelvény, a PowerShell Standard 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 cél futtatókörnyezetet célozza meg, amely egy olyan homlokzati futtatókörnyezet, amely a .NET-keretrendszer és a .NET Core közös felületét biztosítja. Ez lehetővé teszi, hogy egyetlen futtatókörnyezetet célozva egyetlen szerelvényt állítsunk elő, 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 egy újabb Windows PowerShell-verzió nem jelent újabb .NET-keretrendszer verziót; A Windows PowerShell 5.1 a .NET 4.5.2-en futhat.
• A 4.7.1 vagy újabb .NET-keretrendszer futó PowerShell használatához a .NET 4.6.1 NETStandard.Library implementációra van szükség ahhoz, hogy a netstandard.dll és más shim szerelvényeket a régebbi .NET-keretrendszer verziókban is biztosítani lehessen.

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

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örnyezethez
   • A futtatókörnyezetre netstandard2.0 is lefordítva (a buildkimenet használata nélkül), hogy a használt API-k is jelen legyenek a .NET Core-ban.

2. Szerelvény buildjének közzététele a netstandard2.0 cél futtatókörnyezethez. Ehhez szükséges:

   • A projekt közzététele a netstandard2.0 futtatókörnyezethez
   • 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é fog tenni egy szerelvényt, és a megfelelő szerelvényt modulbetöltéskor kell betölteni (például egy kis psm1-et főmodulként).

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 mehet. A modult a megfelelő PowerShell-platformokon kell tesztelnie.

A .NET-ben a PowerShell Standardhoz készült API-k teszteléséhez a .NET Core-nal (a kívánt PowerShell-verziónak megfelelő verzióval) és a megfelelő Windows PowerShell-referenciaszerelvényekkel kell hozzáadnia Microsoft.Powershell.SDK a tesztelési függőséget a .NET-keretrendszer.

A PowerShell Standardról és a több PowerShell-verzióban működő bináris modul írásáról ebben a blogbejegyzésben olvashat bővebben. Tekintse meg a GitHubOn található PowerShell Standard-adattárat is.

Microsoft.PowerShell.SDK

Microsoft.PowerShell.SDK egy metacsomag, amely a PowerShell SDK összes összetevőjét egyetlen NuGet-csomagba húzza össze. A saját .NET-alkalmazások a Microsoft.PowerShell.SDK használatával tetszőleges PowerShell-funkciókat futtathatnak külső PowerShell-telepítéstől vagy -táraktól függetlenül.

Feljegyzés

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

Egy adott Microsoft.Powershell.SDK verzió tartalmazza a PowerShell-alkalmazás ugyanazon verziójának konkrét implementálását; 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 futtatnám őket.

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

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

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

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

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

Microsoft.PowerShell.SDK referenciacélként akkor is használható, ha egy .NET-projektet modulként kíván használni, vagy a PowerShell más módon betölti, 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óban közzétett szerelvény csak a PowerShell adott verziójában Microsoft.PowerShell.SDK tölthető be és használható. Több, adott API-val rendelkező PowerShell-verzió megcélzásához több buildre van szükség, amelyek mindegyike a saját verzióját Microsoft.Powershell.SDKcélozza.

Feljegyzés

A PowerShell SDK csak a PowerShell 6-os és újabb verzióihoz érhető el. Ha a Windows PowerShell-lel egyenértékű funkciókat szeretne biztosítani, használja az alább ismertetett Windows PowerShell-referencia-szerelvényeket.

System.Management.Automation

A System.Management.Automation csomag a PowerShell SDK szíve. A NuGeten elsősorban a beolvasandó eszközként Microsoft.Powershell.SDK létezik. 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 a PowerShell-funkciók előnyösebb szolgáltatója lehet, ha:

• Csak a PowerShell nyelvi funkcióit (a System.Management.Automation.Language névtérben) szeretné használni, 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ére).
• 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).

Windows PowerShell-referenciaszerelvények

A PowerShell 5.1-s és újabb verziói (Windows PowerShell) esetében nincs SDK a PowerShell implementálásához, mivel a Windows PowerShell implementációja a Windows része.

Ehelyett a Windows PowerShell referencia-szerelvények hivatkozási célokat és módot is biztosítanak a Windows PowerShell újbóli üzembe helyezése érdekében, ugyanúgy, mint a PowerShell SDK a 6. és a újabb verziók esetében.

A windowsos PowerShell-referenciaszerelvények verzió szerinti megkülönböztetése helyett a Windows PowerShell minden egyes verziójához más-más csomag tartozik:

• PowerShell 5.1
• PowerShell 4
• PowerShell 3

A Windows PowerShell referencia-szerelvények használatáról a Windows PowerShell SDK-ban olvashat.

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 talál.

PSReadLine

A PSReadLine, a PowerShell gazdag konzolélményét biztosító PowerShell-modul a PowerShell Standardot 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 shim szerelvé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 .NET-keretrendszer mscorlib.dll a megfelelő .NET Core-szerelvényre való átirányításával).

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 a PowerShell 5.1-ben és a PowerShell 6+-ban is jelen legyenek, ugyanakkor lehetővé teszi a modul számára, hogy csak egyetlen szerelvényt szállítson.

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

PowerShell-szerkesztőszolgáltatások

A PowerShell Editor Services (P Standard kiadás S) a Visual Studio Code PowerShell-bővítményénekháttérrendszere, és 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 való újbóli üzembe helyezéséhez, miközben a Language Service Protocol és a Hibakeresési adapter funkcióit is biztosítja.

A P Standard kiadás S 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 a Windows PowerShell 5.1-et célozza meg, de a legtöbb logikát egy második szerelvényben tartalmazza, amely a célokat és a PowerShell Standardot célozza netstandard2.0 meg. Ez lehetővé teszi a .NET Core-hoz és .NET-keretrendszer platformokhoz szükséges függőségek lekérését, 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 P Standard kiadás S a PowerShell futtatókörnyezeti implementációját igényli a megfelelő teszteléshez. Ehhez a P Standard kiadás S xUnit-tesztjei beolvadnakMicrosoft.PowerShell.SDK, és Microsoft.PowerShell.5.ReferenceAssemblies powerShell-implementációt biztosítanak a tesztkörnyezetben.

A PSReadLine-hoz hasonlóan a P Standard kiadás S nem támogatja a .NET 4.6-ot és az újabb verziót, de futásidőben ellenőrzést végez, mielőtt meghívná 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 astVisitor2 implementálásával történik, a PowerShellStandard használata és az AST látogatói metódusok implementálása az újabb PowerShell-szintaxisokhoz nem lehetséges.

Ehelyett a PSScriptAnalyzer az egyes PowerShell-verziókat buildkonfigurációként célozza 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 lényegében futásidejű költségek nélkül implementálhatók
• A Windows PowerShell teljes támogatása egészen a .NET-keretrendszer 4.5.2-.NET-keretrendszer

Összegzés

Ebben a cikkben felsoroltuk és megvitattuk a PowerShellt használó .NET-projektek implementálásakor elérhető NuGet-csomagokat, valamint azokat az okokat, amelyek egymáshoz való használatát indokolhatják.

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

• A PowerShell-moduloknak a PowerShell Standardra kell fordítaniuk, ha csak a különböző PowerShell-verziókban gyakran használt API-kat igényelnek.
• A PowerShell belső futtatására szoruló PowerShell-gazdagépeknek és alkalmazásoknak a PowerShell 6+-hoz készült PowerShell SDK-ra vagy a Windows PowerShell megfelelő Windows PowerShell-referenciaszerelvényeire kell irányulnia.
• A verzióspecifikus API-kat igénylő PowerShell-moduloknak a Szükséges PowerShell-verziók PowerShell SDK- vagy Windows PowerShell-referenciaszerelvényeit kell célba venniük, referencia-szerelvényekként használva őket (azaz nem a PowerShell-függőségeket kell közzétenniük).