A megfelelő PowerShell-NuGet csomag kiválasztása a .NET-projekthezChoosing the right PowerShell NuGet package for your .NET project

Az pwsh egyes PowerShell-kiadásokban közzétett végrehajtható csomagok mellett a PowerShell-csapat számos, a NuGet-on elérhető csomagot is fenntart.Alongside the pwsh executable packages published with each PowerShell release, the PowerShell team also maintains several packages available on NuGet. Ezek a csomagok lehetővé teszik a PowerShell célzását API-platformként a .NET-ben.These packages allow targeting PowerShell as an API platform in .NET.

Olyan .NET-alkalmazásként, amely API-kat biztosít, és a saját (bináris modulok) megvalósítását biztosító .NET-kódtárak betöltésére vár, elengedhetetlen, hogy a PowerShell NuGet-csomag formájában legyen elérhető.As a .NET application that provides APIs and expects to load .NET libraries implementing its own (binary modules), it's essential that PowerShell be available in the form of a NuGet package.

Jelenleg több NuGet-csomag is rendelkezésre áll, amelyek a PowerShell API felületének valamilyen ábrázolását biztosítják.Currently there are several NuGet packages that provide some representation of the PowerShell API surface area. Az adott projekthez használt csomagok nem mindig lettek törölve.Which package to use with a particular project hasn't always been made clear. Ez a cikk néhány olyan gyakori forgatókönyvet mutat be, amely a PowerShellre irányuló .NET-projekteket mutatja be, valamint azt, hogy hogyan válassza ki a megfelelő NuGet-csomagot a PowerShell-alapú .NET-projekthez.This article sheds some light on a few common scenarios for PowerShell-targeting .NET projects and how to choose the right NuGet package to target for your PowerShell-oriented .NET project.

Üzemeltetés és hivatkozásHosting vs referencing

Néhány .NET-projekt egy már létező PowerShell-futtatókörnyezetbe (például pwsh , powershell.exe , a PowerShell integrált konzolba vagy az ISE-be) való betöltéshez próbál kódot írni, míg mások saját alkalmazásaikban szeretnék futtatni a PowerShellt.Some .NET projects seek to write code to be loaded into a pre-existing PowerShell runtime (such as pwsh, powershell.exe, the PowerShell Integrated Console or the ISE), while others want to run PowerShell in their own applications.

  • A hivatkozás arra szolgál, hogy egy projekt (általában egy modul) hogyan tölthető be a powershellbe.Referencing is for when a project, usually a module, is intended to be loaded into PowerShell. Az API-kat a PowerShell által biztosított API-kkal együtt kell összeállítani, de a PowerShell-implementációt a PowerShell-folyamat biztosítja, amely betölti azt.It must be compiled against the APIs that PowerShell provides in order to interact with it, but the PowerShell implementation is supplied by the PowerShell process loading it in. Viszonyítási lehetőségként a projekt a [hivatkozásokat][] vagy a tényleges futtatókörnyezeti szerelvényeket használja fordítási célként, azonban biztosítania kell, hogy ezek közül bármelyiket ne tegye közzé a létrehozásával.For referencing, a project can use reference assemblies or the actual runtime assemblies as a compilation target, but must ensure that it does not publish any of these with its build.
  • Az üzemeltetés akkor történik meg, amikor egy projektnek a PowerShell saját megvalósítására van szüksége, általában azért, mert ez egy önálló alkalmazás, amelynek futtatnia kell a PowerShellt.Hosting is when a project needs its own implementation of PowerShell, usually because it is a standalone application that needs to run PowerShell. Ebben az esetben nem használhatók tiszta hivatkozási szerelvények.In this case, pure reference assemblies cannot be used. Ehelyett egy konkrét PowerShell-implementációra van szükség.Instead, a concrete PowerShell implementation must be depended upon. Mivel a konkrét PowerShell-implementációt kell használni, a PowerShell egy adott verzióját kell választani az üzemeltetéshez. egyetlen gazda-alkalmazás nem képes több cél PowerShell-verzióra.Because a concrete PowerShell implementation must be used, a specific version of PowerShell must be chosen for hosting; a single host application cannot multi-target PowerShell versions.

A PowerShellt hivatkozásként célzó projektek közzétételePublishing projects that target PowerShell as a reference

Megjegyzés

Ebben a cikkben a publish (közzététel ) kifejezést használjuk a futtatásra dotnet publish , amely a .net-függvénytárat az összes függőségével rendelkező könyvtárba helyezi, és készen áll arra, hogy egy adott futtatókörnyezethez lehessen üzembe helyezést.We use the term publish in this article to refer to running dotnet publish, which places a .NET library into a directory with all of its dependencies, ready for deployment to a particular runtime.

Annak érdekében, hogy ne legyenek a fordítási hivatkozási célokként használatos közzétételi projektek függőségei, ajánlott beállítani a [PrivateAssets attribútumot][]:In order to prevent publishing project dependencies that are just being used as compilation reference targets, it is recommended to set the PrivateAssets attribute:

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

Ha ezt nem teszi meg, és a hivatkozásokat a célként megadott célra használja, akkor a tényleges megvalósítás helyett a hivatkozási szerelvény alapértelmezett implementációjának használatával kapcsolatos problémák jelenhetnek meg.If you forget to do this and use a reference assembly as your target, you may see issues related to using the reference assembly's default implementation instead of the actual implementation. Ez a formáját is elvégezheti NullReferenceException , mivel a hivatkozási szerelvények gyakran kigúnyolják a megvalósítási API-t, egyszerűen csak visszatérve null .This may take the form of a NullReferenceException, since reference assemblies often mock the implementation API by simply returning null.

A PowerShell-célzási .NET-projektek legfontosabb típusaiKey kinds of PowerShell-targeting .NET projects

Habár bármely .NET-kódtár vagy-alkalmazás beágyazhatja a PowerShellt, a PowerShell API-kat használó gyakori forgatókönyvek:While any .NET library or application can embed PowerShell, there are some common scenarios that use PowerShell APIs:

  • A PowerShell bináris moduljának implementálásaImplementing a PowerShell binary module

    A PowerShell bináris moduljai a PowerShell által betöltött .NET-kódtárak, amelyeknek a PowerShell API-kat, például a PSCmdlet vagy a CmdletProvider típusokat kell alkalmazniuk, hogy elérhetők legyenek parancsmagok vagy szolgáltatók.PowerShell binary modules are .NET libraries loaded by PowerShell that must implement PowerShell APIs like the PSCmdlet or CmdletProvider types in order to expose cmdlets or providers respectively. Mivel be vannak töltve, a modulok a PowerShellre mutató hivatkozásokat a buildben való közzététel nélkül igyekeznek lefordítani.Because they are loaded in, modules seek to compile against references to PowerShell without publishing it in their build. Az is gyakori, hogy a modulok több PowerShell-verziót és-platformot is támogatnak, ideális esetben a lemezterület, az összetettség vagy az ismétlődő megvalósítás minimális terhelésével.It's also common for modules to want to support multiple PowerShell versions and platforms, ideally with a minimum of overhead of disk space, complexity, or repeated implementation. További információ a modulokról: about_Modules .See about_Modules for more information about modules.

  • PowerShell-gazdagép implementálásaImplementing a PowerShell Host

    A PowerShell-gazdagépek egy interakciós réteget biztosítanak a PowerShell futtatókörnyezethez.A PowerShell Host provides an interaction layer for the PowerShell runtime. A Futtatás egy adott formája, ahol a PSHost új felhasználói felületként van implementálva a PowerShell-hez.It is a specific form of hosting, where a PSHost is implemented as a new user interface to PowerShell. 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 biztosít egy szerkesztővel integrált, részben grafikus felhasználói felületet a PowerShell körül.For example, the PowerShell ConsoleHost provides a terminal user interface for PowerShell executables, while the PowerShell Editor Services Host and the ISE Host both provide an editor-integrated partially graphical user interface around PowerShell. Habár lehetséges egy gazdagép betöltése egy meglévő PowerShell-folyamatba, sokkal gyakoribb, hogy egy gazdagép implementációja önálló PowerShell-implementációként működik, amely újraosztja a PowerShell-motort.While it's possible to load a host onto an existing PowerShell process, it's much more common for a host implementation to act as a standalone PowerShell implementation that redistributes the PowerShell engine.

  • A PowerShell hívása egy másik .NET-alkalmazásbólCalling into PowerShell from another .NET application

    A többi alkalmazáshoz hasonlóan a PowerShell is meghívható alfolyamatként a számítási feladatok futtatásához.As with any application, PowerShell can be called as a subprocess to run workloads. .NET-alkalmazásként azonban lehetséges a PowerShell folyamaton belüli meghívása is, hogy a teljes .NET-objektumok a hívó alkalmazásban is használhatók legyenek.However, as a .NET application, it's also possible to invoke PowerShell in-process to get back full .NET objects for use within the calling application. Ez az _üzemeltetés_általánosabb formája, amelyben az alkalmazás saját PowerShell-implementációt biztosít belső használatra.This is a more general form of hosting, where the application holds its own PowerShell implementation for internal use. Erre példa lehet egy PowerShell-t futtató szolgáltatás vagy démon a gép állapotának kezeléséhez, vagy egy olyan webalkalmazáshoz, amely a PowerShell-t futtatja, ha a Felhőbeli központi telepítéseket szeretné kezelni.Examples of this might be a service or daemon running PowerShell to manage machine state or a web application that runs PowerShell on request to do something like manage cloud deployments.

  • A .NET-ből származó PowerShell-modulok egység teszteléseUnit testing PowerShell modules from .NET

    Noha a PowerShell funkcióinak elérhetővé tétele érdekében a modulokat és más könyvtárakat elsősorban a PowerShellből kell tesztelni (javasolt a támadásokat használni), időnként szükség van egy, a [.net-ből][]származó PowerShell-modulhoz írt, a tesztelési API-kra.While modules and other libraries designed to expose functionality to PowerShell should be primarily tested from PowerShell (we recommend Pester), sometimes it's necessary to unit test APIs written for a PowerShell module from .NET. Ez a helyzet magában foglalja azt a modul-kódot, amely több PowerShell-verziót céloz meg, a tesztelés pedig adott, konkrét implementáción fut.This situation involves the module code trying to target a number of PowerShell versions, while testing should run it on specific, concrete implementations.

PowerShell NuGet-csomagok áttekintésePowerShell NuGet packages at a glance

Ebben a cikkben a következő, a PowerShell API-kat közzétevő NuGet-csomagokat mutatjuk be:In this article, we'll cover the following NuGet packages that expose PowerShell APIs:

  • PowerShellStandard. library, egy olyan hivatkozás, amely lehetővé teszi egyetlen szerelvény kiépítését, amelyet több PowerShell-futtatókörnyezet is betölt.PowerShellStandard.Library, a reference assembly that enables building a single assembly that can be loaded by multiple PowerShell runtimes.
  • Microsoft. PowerShell. SDK, a teljes PowerShell SDK cél-és áttárolási módjaMicrosoft.PowerShell.SDK, the way to target and rehost the whole PowerShell SDK
  • A System. Management. Automation csomag, a PowerShell futtatókörnyezet és a motor implementációja, amely a minimálisan üzemeltetett implementációkban és a verzióra vonatkozó célzott forgatókönyvek esetében hasznos lehet.The System.Management.Automation package, the core PowerShell runtime and engine implementation, that can be useful in minimal hosted implementations and for version-specific targeting scenarios.
  • A Windows PowerShell-referenciák szerelvényei, a Windows PowerShell cél és hatékony újratárolásának módja (PowerShell-verzió: 5,1 és újabb).The Windows PowerShell reference assemblies, the way to target and effectively rehost Windows PowerShell (PowerShell versions 5.1 and below).

Megjegyzés

A PowerShell-NuGet csomag egyáltalán nem .net-függvénytár csomag, hanem a globálisan elérhető PowerShell-eszköz implementációja.The PowerShell NuGet package is not a .NET library package at all, but instead provides the PowerShell dotnet global tool implementation. Ezt egyetlen projekt sem használja, mert az csak végrehajtható fájlt biztosít.This should not be used by any projects, since it only provides an executable.

PowerShellStandard. libraryPowerShellStandard.Library

A PowerShell-függvénytár egy olyan hivatkozási szerelvény, amely rögzíti a PowerShell 7-es, 6-os és 5,1-es verziójú API-jait.The PowerShell Standard library is a reference assembly that captures the intersection of the APIs of PowerShell versions 7, 6 and 5.1. Ez egy lefordítható, időzített API-felületet biztosít a .NET-kód lefordításához, ami lehetővé teszi a .NET-projektek számára, hogy a PowerShell 7., 6. és 5,1-es verzióját célozzák meg anélkül, hogy olyan API-t kellene hívni, amely nemThis provides a compile-time-checked API surface to compile .NET code against, allowing .NET projects to target PowerShell versions 7, 6 and 5.1 without risking calling an API that won't be there.

A PowerShell-szabvány PowerShell-modulok írásához vagy más, csak a PowerShell-folyamatba való betöltést követően futtatandó kód futtatására szolgál.PowerShell Standard is intended for writing PowerShell modules, or other code only intended to be run after loading it into a PowerShell process. Mivel ez egy hivatkozási szerelvény, a PowerShell-szabvány nem tartalmaz implementációt, így nem biztosít különálló alkalmazások használatát.Because it is a reference assembly, PowerShell Standard contains no implementation itself, so provides no functionality for standalone applications.

A PowerShell standard használata különböző .NET-futtatókörnyezetekkelUsing PowerShell Standard with different .NET runtimes

A PowerShell standard célja a .net standard 2,0 Target Runtime, amely egy, a .NET-keretrendszer és a .net Core által közösen közös felületet biztosító homlokzati futtatókörnyezet.PowerShell Standard targets the .NET Standard 2.0 target runtime, which is a façade runtime designed to provide a common surface area shared by .NET Framework and .NET Core. Ez lehetővé teszi egyetlen futtatókörnyezet megcélzását, hogy egyetlen, több PowerShell-verzióval működő szerelvényt hozzon létre, de az alábbi következményekkel jár:This allows targeting a single runtime to produce a single assembly that will work with multiple PowerShell versions, but has the following consequences:

  • A modult vagy könyvtárat betöltő PowerShellnek legalább .NET 4.6.1-es, .net 4,6-es és .NET 4.5.2-es .net-es verzióját kell futtatnia.The PowerShell loading the module or library must be running a minimum of .NET 4.6.1; .NET 4.6 and .NET 4.5.2 do not support .NET Standard. Vegye figyelembe, hogy a Windows PowerShell újabb verziója nem jelent újabb .NET-keretrendszer-verziót; A Windows PowerShell 5,1 .NET 4.5.2-es verziójával is futhat.Note that a newer Windows PowerShell version does not mean a newer .NET Framework version; Windows PowerShell 5.1 may run on .NET 4.5.2.
  • Ha a .NET-keretrendszer 4.7.1 vagy újabb verzióját futtató PowerShell-lel szeretne dolgozni, a .net 4.6.1 NETStandard. library implementáció szükséges ahhoz, hogy a .NET-keretrendszer régebbi verzióiban elérhető legyen a netstandard.dll és a többi alátét-szerelvény.In order to work with a PowerShell running .NET Framework 4.7.1 or below, the .NET 4.6.1 NETStandard.Library implementation is required to provide the netstandard.dll and other shim assemblies in older .NET Framework versions.

A PowerShell 6 + a .NET-keretrendszer 4.6.1-es (és újabb) verzióról a .NET Core-ra való továbbításhoz saját alátét-szerelvényeket biztosít.PowerShell 6+ provides its own shim assemblies for type forwarding from .NET Framework 4.6.1 (and above) to .NET Core. Ez azt jelenti, hogy ha egy modul csak a .NET Core-ban található API-kat használja, akkor a PowerShell 6 + képes betölteni és futtatni, ha a .NET-keretrendszer 4.6.1-es verziójának (a net461 futtatókörnyezet célja) készült.This means that as long as a module uses only APIs that exist in .NET Core, PowerShell 6+ can load and run it when it has been built for .NET Framework 4.6.1 (the net461 runtime target).

Ez azt jelenti, hogy a PowerShell szabványt használó bináris modulok több PowerShell-verziót céloznak meg egyetlen közzétett DLL-sel, két lehetőség közül választhatnak:This means that binary modules using PowerShell Standard to target multiple PowerShell versions with a single published DLL have two options:

  1. A net461 cél futtatókörnyezethez készült szerelvény közzététele.Publishing an assembly built for the net461 target runtime. Ez a következőket foglalja magában:This involves:

    • A projekt közzététele a net461 futtatókörnyezetbenPublishing the project for the net461 runtime
    • A netstandard2.0 futtatókörnyezet (a Build kimenetének használata nélkül) fordításával biztosítható, hogy az összes használt API a .net Core-ban is megtalálható legyen.Also compiling against the netstandard2.0 runtime (without using its build output) to ensure that all APIs used are also present in .NET Core.
  2. Szerelvény-Build közzététele a netstandard2.0 cél futtatókörnyezethez.Publishing an assembly build for the netstandard2.0 target runtime. Ehhez a következőket kell tennie:This requires:

    • A projekt közzététele a netstandard2.0 futtatókörnyezetbenPublishing the project for the netstandard2.0 runtime
    • A net461 NETStandard. library függőségeinek elkészítése és a projekt-szerelvény közzétételi helyén való másolása, hogy a szerelvény a .net-keretrendszerben megadott típusra legyen továbbítva.Taking the net461 dependencies of NETStandard.Library and copying them into the project assembly's publish location so that the assembly is type-forwarded corrected in .NET Framework.

A .NET-keretrendszer régebbi verzióit célzó PowerShell-modulok vagy-kódtárak létrehozásához érdemes lehet több .NET-futtatókörnyezetet megcélozni.To build PowerShell modules or libraries targeting older .NET Framework versions, it may be preferable to target multiple .NET runtimes. Ez egy szerelvényt tesz közzé minden cél futtatókörnyezethez, és a megfelelő szerelvényt be kell tölteni a modul betöltési idejére (például egy kis psm1, mint a gyökérszintű modul).This will publish an assembly for each target runtime, and the correct assembly will need to be loaded at module load time (for example with a small psm1 as the root module).

A PowerShell standard projektjeinek tesztelése a .NET-benTesting PowerShell Standard projects in .NET

Ha a modult a .NET-tesztek (például a xUnit) használatával teszteli, ne feledje, hogy a fordítási idejű ellenőrzések csak eddig mehetnek el.When it comes to testing your module in .NET test runners like xUnit, remember that compile-time checks can only go so far. A modult a megfelelő PowerShell-platformokra kell tesztelni.You must test your module against the relevant PowerShell platforms.

A PowerShell standard .NET-ben létrehozott API-k teszteléséhez hozzá kell adni a Microsoft.Powershell.SDK .net Core-hoz készült tesztelési függőséget (a verziószámot a kívánt PowerShell-verziónak megfelelően), a megfelelő Windows PowerShell-referenciákat pedig a .NET-keretrendszerrel.To test APIs built against PowerShell Standard in .NET, you should add Microsoft.Powershell.SDK as a testing dependency with .NET Core (with the version set to match the desired PowerShell version), and the appropriate Windows PowerShell reference assemblies with .NET Framework.

Ha további információt szeretne a PowerShell standard megoldásról, és használja egy olyan bináris modul írásához, amely több PowerShell-verzióban is működik, tekintse meg [ezt a blogbejegyzést][].For more information on PowerShell Standard and using it to write a binary module that works in multiple PowerShell versions, see this blog post. Lásd még a [PowerShell standard adattárát][] is a githubon.Also see the PowerShell Standard repository on GitHub.

Microsoft. PowerShell. SDKMicrosoft.PowerShell.SDK

Microsoft.PowerShell.SDK a egy olyan meta-csomag, amely egyesíti a PowerShell SDK összes összetevőjét egyetlen NuGet-csomagba.Microsoft.PowerShell.SDK is a meta-package that pulls together all of the components of the PowerShell SDK into a single NuGet package. Egy önálló .NET-alkalmazás a Microsoft. PowerShell. SDK használatával tetszőleges PowerShell-funkciókat futtathat a külső PowerShell-telepítések és-kódtárak nélkül.A self-contained .NET application can use Microsoft.PowerShell.SDK to run arbitrary PowerShell functionality without depending on any external PowerShell installations or libraries.

Megjegyzés

A PowerShell SDK csak a PowerShellt alkotó összes összetevő-csomagra hivatkozik, amely a .NET-fejlesztéshez használható a PowerShell használatával.The PowerShell SDK just refers to all the component packages that make up PowerShell, and which can be used for .NET development with PowerShell.

Egy adott Microsoft.Powershell.SDK verzió a PowerShell-alkalmazás ugyanazon verziójának konkrét megvalósítását tartalmazza; az 7,0-es verzió a powershell 7,0-es és az azzal együtt futtatott parancsok és parancsfájlok futtatását is magában foglalja, így a powershell 7,0-ban futtatja őket.A given Microsoft.Powershell.SDK version contains the concrete implementation of the same version of the PowerShell application; version 7.0 contains the implementation of PowerShell 7.0 and running commands or scripts with it will largely behave like running them in PowerShell 7.0.

A PowerShell-parancsok az SDK-ból való futtatása többnyire, de nem teljesen, ugyanúgy, mint a futtatásához pwsh .Running PowerShell commands from the SDK is mostly, but not totally, the same as running them from pwsh. A Start-Job például jelenleg a pwsh rendelkezésre álló végrehajtható fájltól függ, így alapértelmezés szerint nem fog működni Microsoft.Powershell.SDK .For example, Start-Job currently depends on the pwsh executable being available, and so will not work with Microsoft.Powershell.SDK by default.

Microsoft.Powershell.SDKA .NET-alkalmazásokból való célzás lehetővé teszi a PowerShell megvalósítási szerelvények, például a System.Management.Automation , Microsoft.PowerShell.Management és más modul-szerelvények integrálását.Targeting Microsoft.Powershell.SDK from a .NET application allows you to integrate with all of PowerShell's implementation assemblies, such as System.Management.Automation, Microsoft.PowerShell.Management, and other module assemblies.

Az alkalmazások célzásának közzététele Microsoft.Powershell.SDK magában foglalja az összes szerelvényt, és minden függőség PowerShell-t igényel.Publishing an application targeting Microsoft.Powershell.SDK will include all these assemblies, and any dependencies PowerShell requires. Emellett olyan egyéb eszközöket is tartalmaz, amelyeket a PowerShell szükséges a buildben, például a modulok jegyzékfájlját a Microsoft.PowerShell.* modulokhoz, és az ref Add-Typeutasításhoz szükséges könyvtárat.It will also include other assets that PowerShell required in its build, such as the module manifests for Microsoft.PowerShell.* modules and the ref directory required by Add-Type.

A teljességének ismeretében a Microsoft.Powershell.SDK legmegfelelőbb a következő:Given the completeness of Microsoft.Powershell.SDK, it's best suited for:

  • PowerShell-gazdagépek implementálása.Implementation of PowerShell hosts.
  • xUnit a PowerShell-hivatkozásokat célzó könyvtárak tesztelése.xUnit testing of libraries targeting PowerShell reference assemblies.
  • A PowerShell folyamaton belüli meghívása .NET-alkalmazásból.Invoking PowerShell in-process from a .NET application.

Microsoft.PowerShell.SDK hivatkozásként is használható, ha egy .NET-projektet modulként vagy más PowerShell-lel való használatra terveztek, de az API-k csak a PowerShell egy adott verziójában jelennek meg.Microsoft.PowerShell.SDK may also be used as a reference target when a .NET project is intended to be used as a module or otherwise loaded by PowerShell, but depends on APIs only present in a particular version of PowerShell. Vegye figyelembe, hogy egy adott verzióra közzétett szerelvény Microsoft.PowerShell.SDK csak a PowerShell adott verziójában tölthető be és használható.Note that an assembly published against a specific version of Microsoft.PowerShell.SDK will only be safe to load and use in that version of PowerShell. Ha több PowerShell-verziót szeretne megcélozni adott API-kkal, több buildre van szükség, amelyek mindegyike a saját verzióját célozza meg Microsoft.Powershell.SDK .To target multiple PowerShell versions with specific APIs, multiple builds are required, each targeting their own version of Microsoft.Powershell.SDK.

Megjegyzés

A PowerShell SDK csak a 6. és újabb PowerShell-verziókban érhető el.The PowerShell SDK is only available for PowerShell versions 6 and up. A Windows PowerShell megfelelő működésének biztosításához használja az alább ismertetett Windows PowerShell-referenciákat.To provide equivalent functionality with Windows PowerShell, use the Windows PowerShell reference assemblies described below.

System. Management. AutomationSystem.Management.Automation

A System.Management.Automation csomag a POWERSHELL SDK szíve.The System.Management.Automation package is the heart of the PowerShell SDK. A NuGet-on található, elsődlegesen a Microsoft.Powershell.SDK lekérésére szolgáló eszköz.It exists on NuGet, primarily, as an asset for Microsoft.Powershell.SDK to pull in. Azonban a kisebb üzemeltetési forgatókönyvek és a verzió-célzási modulok esetében is közvetlenül használható csomagként.However, it can also be used directly as a package for smaller hosting scenarios and version-targeting modules.

Pontosabban a System.Management.Automation csomag a PowerShell-funkciók előnyben részesített szolgáltatója lehet, ha:Specifically, the System.Management.Automation package may be a preferable provider of PowerShell functionality when:

  • Csak a PowerShell nyelvi funkcióit szeretné használni (a System.Management.Automation.Language névtérben), például a PowerShell-elemző, az AST és az AST látogatói API-kat (például a PowerShell statikus elemzéséhez).You're only looking to use PowerShell language functionality (in the System.Management.Automation.Language namespace) like the PowerShell parser, AST, and AST visitor APIs (for example for static analysis of PowerShell).
  • Csak bizonyos parancsokat kíván végrehajtani a Microsoft.PowerShell.Core modulból, és a CreateDefault2 Factory metódussal létrehozott munkamenet-állapotban hajthatja végre őket.You only wish to execute specific commands from the Microsoft.PowerShell.Core module and can execute them in a session state created with the CreateDefault2 factory method.

Emellett System.Management.Automation hasznos hivatkozási szerelvény is, ha:Additionally, System.Management.Automation is a useful reference assembly when:

  • Olyan API-kat szeretne megcélozni, amelyek csak egy adott PowerShell-verzión belül találhatókYou wish to target APIs that are only present within a specific PowerShell version
  • A szerelvényen kívül bekövetkező típusoktól függ System.Management.Automation (például a modulokban lévő parancsmagok által exportált típusok Microsoft.PowerShell.* ).You won't be depending on types occurring outside the System.Management.Automation assembly (for example, types exported by cmdlets in Microsoft.PowerShell.* modules).

Windows PowerShell-hivatkozások szerelvényeiWindows PowerShell reference assemblies

A 5,1-es és régebbi PowerShell-verziók esetében a PowerShell implementációja nem biztosítható, mert a Windows PowerShell implementációja a Windows részét képezi.For PowerShell versions 5.1 and older (Windows PowerShell), there is no SDK to provide an implementation of PowerShell, since Windows PowerShell's implementation is a part of Windows.

Ehelyett a Windows PowerShell-hivatkozási szerelvények mind a hivatkozási célokat, mind a Windows PowerShell újratárolásának módját biztosítják, a PowerShell SDK-val megegyező módon, a 6-os és a újabb verziók esetében.Instead, the Windows PowerShell reference assemblies provide both reference targets and a way to rehost Windows PowerShell, acting the same as the PowerShell SDK does for versions 6 and up.

A Windows PowerShell hivatkozási szerelvényei nem a verziótól eltérőek, hanem egy másik csomaggal rendelkeznek a Windows PowerShell egyes verzióihoz:Rather than being differentiated by version, Windows PowerShell reference assemblies have a different package for each version of Windows PowerShell:

A Windows PowerShell-hivatkozási szerelvények használatáról a Windows POWERSHELL SDK-ban talál információt.Information on how to use the Windows PowerShell reference assemblies can be found in the Windows PowerShell SDK.

Valós példák ezekből a NuGet-csomagokbólReal-world examples using these NuGet packages

A különböző PowerShell-eszközök igényeitől függően különböző PowerShell-NuGet csomagokat céloznak meg.Different PowerShell tooling projects target different PowerShell NuGet packages depending on their needs. Itt látható néhány jelentős példa.Listed here are some notable examples.

PSReadLinePSReadLine

A PowerShell széles körű PSReadLinea PowerShell-modul, amely az adott PowerShell-verzió helyett a PowerShell-szabványt célozza meg, és a net461 .net-futtatókörnyezetet a csproj-ben célozza meg.PSReadLine, the PowerShell module that provides much of PowerShell's rich console experience, targets PowerShell Standard as a dependency rather than a specific PowerShell version, and targets the net461 .NET runtime in its csproj.

A PowerShell 6 + saját alátét-szerelvényeket biztosít, amelyek lehetővé teszik, hogy a (z) rendszerbe való betöltéskor egy olyan DLL-t, amely a net461 futtatókörnyezetet a "Just work" értékre célozza (a .NET-keretrendszer mscorlib.dll a megfelelő .net Core-szerelvényhezPowerShell 6+ supplies its own shim assemblies that allow a DLL targeting the net461 runtime to "just work" when loaded in (by redirecting binding to .NET Framework's mscorlib.dll to the relevant .NET Core assembly).

Ez leegyszerűsíti a PSReadLine moduljának elrendezését és kézbesítését, mivel a PowerShell standard biztosítja, hogy csak az API-k használhatók mind a PowerShell 5,1-ben, mind a PowerShell 6 +-ban, miközben a modult csak egyetlen szerelvénybe szállíthatja.This simplifies PSReadLine's module layout and delivery significantly, since PowerShell Standard ensures the only APIs used will be present in both PowerShell 5.1 and PowerShell 6+, while also allowing the module to ship with only a single assembly.

A .NET 4.6.1-cél azt jelenti, hogy a .NET 4.5.2-es és a .NET 4,6-es verzióját futtató Windows PowerShell azonban nem támogatott.The .NET 4.6.1 target does mean that Windows PowerShell running on .NET 4.5.2 and .NET 4.6 is not supported though.

PowerShell-szerkesztő szolgáltatásokPowerShell Editor Services

A PowerShell- [szerkesztő szolgáltatások][] (PSES) a Visual Studio Code-hoz készült PowerShell-bővítmény háttere, amely a PowerShell-végrehajtható fájl által betöltött PowerShell-modul formáját képezi, majd átveszi ezt a folyamatot a PowerShell áttelepítésére, miközben a nyelvi szolgáltatási protokollt és a hibakeresési adapter szolgáltatásait is megadja.PowerShell Editor Services (PSES) is the backend for the PowerShell extension for Visual Studio Code, and is actually a form of PowerShell module that gets loaded by a PowerShell executable and then takes over that process to rehost PowerShell within itself while also providing Language Service Protocol and Debug Adapter features.

A PSES konkrét implementációs célokat biztosít a netcoreapp2.1 PowerShell 6-os verziójának megcélzásához (mivel a PowerShell 7-es netcoreapp3.1 futtatókörnyezete visszafelé kompatibilis), és a net461 Windows PowerShell 5,1-et célozza meg, de a legtöbb logikáját egy második, a célokat szolgáló és a PowerShell-szabványt tartalmazó szerelvényben tartalmazza netstandard2.0 .PSES provides concrete implementation targets for netcoreapp2.1 to target PowerShell 6+ (since PowerShell 7's netcoreapp3.1 runtime is backwards compatible) and net461 to target Windows PowerShell 5.1, but contains most of its logic in a second assembly that targets netstandard2.0 and PowerShell Standard. Ez lehetővé teszi, hogy lekérje a .NET Core és a .NET Framework platformokhoz szükséges függőségeket, miközben továbbra is leegyszerűsíti a teljes rendszerfelügyeletet egy egységes absztrakció mögött.This allows it to pull in dependencies required for .NET Core and .NET Framework platforms, while still simplifying most of the codebase behind a uniform abstraction.

Mivel a PowerShell-szabványon alapul, a PSES a PowerShell futtatókörnyezet-implementációját igényli a megfelelő tesztelés érdekében.Because it is built against PowerShell Standard, PSES requires a runtime implementation of PowerShell in order to be tested correctly. Ennek elvégzéséhez a PSES xUnit -tesztek behúzásával Microsoft.PowerShell.SDK és annak érdekében, Microsoft.PowerShell.5.ReferenceAssemblies hogy PowerShell-implementációt biztosítsanak a tesztkörnyezetben.To do this, PSES's xUnit tests pull in Microsoft.PowerShell.SDK and Microsoft.PowerShell.5.ReferenceAssemblies in order to provide a PowerShell implementation in the test environment.

A PSReadLine-hez hasonlóan a PSES nem támogatja a .NET 4,6-es és ennél régebbi verziókat, de az API-k meghívása előtt [ellenőrzi][] , hogy az alacsonyabb .NET-keretrendszer futtatókörnyezete összeomlást okozhat-e.As with PSReadLine, PSES cannot support .NET 4.6 and below, but it performs a check at runtime before calling any of the APIs that could cause a crash on the lower .NET Framework runtimes.

PSScriptAnalyzerPSScriptAnalyzer

Az PSScriptAnalyzer, a PowerShell-lel, a a PowerShell bizonyos verzióiban kizárólag a szintaktikai elemeket kell megcélozni.PSScriptAnalyzer, the linter for PowerShell, must target syntactic elements only introduced in certain versions of PowerShell. Mivel a szintaktikai elemek felismerése egy AstVisitor2megvalósításával valósítható meg, nem lehetséges a PowerShellStandard használata, valamint az AST látogatói metódusok bevezetése újabb PowerShell-szintaxisokhoz.Because recognition of these syntactic elements is accomplished by implementing an AstVisitor2, it's not possible to use PowerShellStandard and also implement AST visitor methods for newer PowerShell syntaxes.

Ehelyett a PSScriptAnalyzer az [egyes PowerShell-verziókat][] Build-konfigurációként célozza meg, és mindegyikhez külön DLL-t hoz létre.Instead, PSScriptAnalyzer targets each PowerShell version as a build configuration, and produces a separate DLL for each of them. Ez növeli a Build méretét és összetettségét, de lehetővé teszi a következőket:This increases build size and complexity, but allows:

  • Verzió-specifikus API-célzásVersion-specific API targeting
  • A verzióra jellemző funkcionalitás, amelynek megvalósításához lényegében nincs futtatókörnyezeti díjVersion-specific functionality to be implemented with essentially no runtime cost
  • A Windows PowerShell teljes támogatása egészen a .NET-keretrendszer 4.5.2-es verziójávalTotal support for Windows PowerShell all the way down to .NET Framework 4.5.2

ÖsszegzésSummary

Ebben a cikkben az NuGet-csomagokat a PowerShell-t használó .NET-projektek megvalósítása során a célként elérhetővé tettük, valamint az egyiket a másikkal való használat okaira vonatkozóan ismertetjük.In this article, we've listed and discussed the NuGet packages available to target when implementing a .NET project that uses PowerShell, and the reasons you might have for using one over another.

Ha kihagyta az összegzést, néhány átfogó javaslat a következő:If you've skipped to the summary, some broad recommendations are:

  • A PowerShell- modulokat a PowerShell-szabványokkal kell lefordítani, ha csak a különböző PowerShell-verziókkal közös API-kat igényelnek.PowerShell modules should compile against PowerShell Standard if they only require APIs common to different PowerShell versions.
  • A PowerShell belső futtatásához szükséges PowerShell -gazdagépeknek és alkalmazásoknak meg kell célozniuk a PowerShell 6 + PowerShell SDK-t, vagy a Windows powershellhez kapcsolódó Windows PowerShell-referenciákat.PowerShell hosts and applications that need to run PowerShell internally should target the PowerShell SDK for PowerShell 6+ or the relevant Windows PowerShell reference assemblies for Windows PowerShell.
  • A verzióra jellemző API-kat igénylő PowerShell-moduloknak a PowerShell SDK vagy a Windows PowerShell hivatkozási szerelvényeit kell megcéloznia a szükséges PowerShell-verziókhoz, azok hivatkozási szerelvényként való használatával (azaz nem teszi közzé a PowerShell-függőségeket).PowerShell modules that need version-specific APIs should target the PowerShell SDK or Windows PowerShell reference assemblies for the required PowerShell versions, using them as reference assemblies (that is, not publishing the PowerShell dependencies).