Scelta del pacchetto NuGet di PowerShell appropriato per il progetto .NETChoosing the right PowerShell NuGet package for your .NET project

Oltre ai pacchetti eseguibili pwsh pubblicati con ogni versione di PowerShell, il team di PowerShell gestisce anche diversi pacchetti disponibili in NuGet.Alongside the pwsh executable packages published with each PowerShell release, the PowerShell team also maintains several packages available on NuGet. Questi pacchetti consentono di specificare PowerShell come piattaforma API di destinazione in .NET.These packages allow targeting PowerShell as an API platform in .NET.

Essendo un'applicazione .NET che fornisce API e prevede il caricamento delle librerie .NET che implementano le proprie (moduli binari), è essenziale che PowerShell sia disponibile sotto forma di pacchetto NuGet.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.

Esistono attualmente diversi pacchetti NuGet che forniscono una rappresentazione della superficie di attacco dell'API PowerShell.Currently there are several NuGet packages that provide some representation of the PowerShell API surface area. Non è sempre stato chiaro quale pacchetto usare con un determinato progetto.Which package to use with a particular project hasn't always been made clear. Questo articolo fornisce informazioni su alcuni scenari comuni per i progetti .NET destinati a PowerShell e illustra come scegliere il pacchetto NuGet appropriato come destinazione per il progetto .NET orientato a PowerShell.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.

Hosting e riferimentiHosting vs referencing

Alcuni progetti .NET cercano di scrivere il codice da caricare in un runtime di PowerShell preesistente (ad esempio pwsh, powershell.exe, la console integrata di PowerShell o ISE), mentre altri vogliono eseguire PowerShell nelle proprie applicazioni.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.

  • I riferimenti vengono usati quando un progetto, in genere un modulo, deve essere caricato in PowerShell.Referencing is for when a project, usually a module, is intended to be loaded into PowerShell. Deve essere compilato con le API fornite da PowerShell per consentire l'interazione, ma l'implementazione di PowerShell viene fornita dal processo di caricamento di PowerShell.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. Per i riferimenti, un progetto può usare gli assembly di riferimento o gli assembly di runtime effettivi come destinazione della compilazione, ma è necessario assicurarsi che nessuno di questi venga pubblicato con la relativa build.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.
  • L'hosting viene usato quando un progetto necessita di una propria implementazione di PowerShell, in genere perché si tratta di un'applicazione autonoma che deve eseguire PowerShell.Hosting is when a project needs its own implementation of PowerShell, usually because it is a standalone application that needs to run PowerShell. In questo caso, non si possono usare gli assembly di riferimento puri.In this case, pure reference assemblies cannot be used. È invece necessaria una dipendenza da un'implementazione di PowerShell concreta.Instead, a concrete PowerShell implementation must be depended upon. Poiché deve essere usata un'implementazione di PowerShell concreta, è necessario scegliere una versione specifica di PowerShell per l'hosting. Una singola applicazione host non può specificare come destinazione più versioni di PowerShell.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.

Pubblicazione di progetti che specificano PowerShell come riferimento di destinazionePublishing projects that target PowerShell as a reference

Nota

Il termine pubblicare in questo articolo viene usato per fare riferimento all'esecuzione di dotnet publish, che inserisce una libreria .NET in una directory con tutte le relative dipendenze, pronta per la distribuzione in un determinato runtime.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.

Per evitare la pubblicazione delle dipendenze del progetto che vengono usate solo come destinazioni di riferimento per la compilazione, è consigliabile impostare l'attributo PrivateAssets: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" />

Se si dimentica di eseguire questa operazione e si usa un assembly di riferimento come destinazione, è possibile che si verifichino problemi relativi all'uso dell'implementazione predefinita dell'assembly di riferimento invece che dell'implementazione effettiva.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. Potrebbe quindi verificarsi un'eccezione NullReferenceException, perché gli assembly di riferimento spesso simulano l'API di implementazione semplicemente restituendo null.This may take the form of a NullReferenceException, since reference assemblies often mock the implementation API by simply returning null.

Tipi chiave di progetti .NET destinati a PowerShellKey kinds of PowerShell-targeting .NET projects

Anche se qualsiasi libreria o applicazione .NET può incorporare PowerShell, esistono alcuni scenari comuni che usano le API di PowerShell:While any .NET library or application can embed PowerShell, there are some common scenarios that use PowerShell APIs:

  • Implementazione di un modulo binario di PowerShellImplementing a PowerShell binary module

    I moduli binari di PowerShell sono librerie .NET caricate da PowerShell che devono implementare le API di PowerShell, ad esempio i tipi PSCmdlet o CmdletProvider per esporre rispettivamente i cmdlet o i provider.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. Poiché vengono caricati, i moduli provano a eseguire la compilazione in base ai riferimenti a PowerShell senza pubblicarli nella build.Because they are loaded in, modules seek to compile against references to PowerShell without publishing it in their build. È anche frequente che i moduli vogliano supportare più piattaforme e versioni di PowerShell, idealmente con un sovraccarico minimo di spazio su disco, complessità o implementazione ripetuta.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. Vedere [Informazioni sui moduli][] per altre informazioni sui moduli.See about_Modules for more information about modules.

  • Implementazione di un host di PowerShellImplementing a PowerShell Host

    Un host di PowerShell fornisce un livello di interazione per il runtime di PowerShell.A PowerShell Host provides an interaction layer for the PowerShell runtime. È una forma specifica di hosting, in cui PSHost viene implementato come nuova interfaccia utente per PowerShell.It is a specific form of hosting, where a PSHost is implemented as a new user interface to PowerShell. ConsoleHost di PowerShell, ad esempio, fornisce un'interfaccia utente di terminale per i file eseguibili di PowerShell, mentre l'host di PowerShell Editor Services e l'host ISE forniscono entrambi un'interfaccia utente parzialmente grafica integrata nell'editor in PowerShell.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. Anche se è possibile caricare un host in un processo di PowerShell esistente, è molto più comune che un'implementazione host funga da implementazione di PowerShell autonoma che ridistribuisce il motore di PowerShell.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.

  • Chiamata in PowerShell da un'altra applicazione .NETCalling into PowerShell from another .NET application

    Come qualsiasi applicazione, PowerShell può essere chiamato come sottoprocesso per l'esecuzione di carichi di lavoro.As with any application, PowerShell can be called as a subprocess to run workloads. Trattandosi tuttavia di un'applicazione .NET, è anche possibile richiamare PowerShell In-Process per ottenere gli oggetti .NET completi da usare all'interno dell'applicazione chiamante.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. Si tratta di una forma più generale di hosting, in cui l'applicazione contiene la propria implementazione di PowerShell per uso interno.This is a more general form of hosting, where the application holds its own PowerShell implementation for internal use. Ne sono esempi un servizio o un daemon che esegue PowerShell per gestire lo stato del computer o un'applicazione Web che esegue PowerShell su richiesta, ad esempio per gestire le distribuzioni cloud.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.

  • Testing unità di moduli di PowerShell da .NETUnit testing PowerShell modules from .NET

    Anche se i moduli e le altre librerie progettate per esporre le funzionalità a PowerShell devono essere testati principalmente da PowerShell (è consigliabile usare Pester), a volte è necessario eseguire unit test delle API scritte per un modulo di PowerShell da .NET.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. In questa situazione il codice del modulo prova a specificare come destinazione diverse versioni di PowerShell, mentre il test deve eseguirlo in implementazioni specifiche e concrete.This situation involves the module code trying to target a number of PowerShell versions, while testing should run it on specific, concrete implementations.

Riepilogo dei pacchetti NuGet di PowerShellPowerShell NuGet packages at a glance

In questo articolo verranno descritti i pacchetti NuGet seguenti che espongono le API di PowerShell:In this article, we'll cover the following NuGet packages that expose PowerShell APIs:

  • PowerShellStandard.Library: assembly di riferimento che consente di compilare un singolo assembly che può essere caricato da più runtime di PowerShell.PowerShellStandard.Library, a reference assembly that enables building a single assembly that can be loaded by multiple PowerShell runtimes.
  • Microsoft.PowerShell.SDK: modo per specificare come destinazione ed effettuare il rehosting dell'intero PowerShell SDKMicrosoft.PowerShell.SDK, the way to target and rehost the whole PowerShell SDK
  • Pacchetto System.Management.Automation: implementazione del motore e del runtime di PowerShell di base, che può essere utile nelle implementazioni minime ospitate e per gli scenari con versioni di destinazione specifiche.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.
  • Assembly di riferimento di Windows PowerShell: modo per specificare come destinazione ed effettuare in modo efficace il rehosting di Windows PowerShell (PowerShell versione 5.1 e precedenti).The Windows PowerShell reference assemblies, the way to target and effectively rehost Windows PowerShell (PowerShell versions 5.1 and below).

Nota

Il pacchetto NuGet di PowerShell non è affatto un pacchetto di librerie .NET, ma fornisce l'implementazione dello strumento globale dotnet di PowerShell.The PowerShell NuGet package is not a .NET library package at all, but instead provides the PowerShell dotnet global tool implementation. Questo pacchetto non deve essere usato da nessun progetto, perché fornisce solo un file eseguibile.This should not be used by any projects, since it only provides an executable.

PowerShellStandard.LibraryPowerShellStandard.Library

La libreria di PowerShell Standard è un assembly di riferimento che acquisisce l'intersezione delle API di PowerShell versione 7, 6 e 5.1.The PowerShell Standard library is a reference assembly that captures the intersection of the APIs of PowerShell versions 7, 6 and 5.1. Fornisce un'area API controllata in fase di compilazione in base alla quale compilare il codice .NET, consentendo ai progetti .NET di specificare come destinazione le versioni 7, 6 e 5.1 di PowerShell senza rischiare di chiamare un'API che non sarà disponibile.This 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.

PowerShell Standard è progettato per la scrittura di moduli di PowerShell o di altro codice che dovrà essere eseguito solo dopo averlo caricato in un processo di PowerShell.PowerShell Standard is intended for writing PowerShell modules, or other code only intended to be run after loading it into a PowerShell process. Poiché si tratta di un assembly di riferimento, PowerShell Standard non contiene implementazioni, quindi non fornisce funzionalità per le applicazioni autonome.Because it is a reference assembly, PowerShell Standard contains no implementation itself, so provides no functionality for standalone applications.

Uso di PowerShell Standard con runtime .NET diversiUsing PowerShell Standard with different .NET runtimes

PowerShell Standard ha come destinazione il runtime .NET Standard 2.0, ovvero un runtime di facciata progettato per fornire una superficie di attacco comune condivisa da .NET Framework e .NET Core.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. In questo modo è possibile specificare come destinazione un singolo runtime per produrre un singolo assembly che funzionerà con più versioni di PowerShell, ma con le conseguenze seguenti:This allows targeting a single runtime to produce a single assembly that will work with multiple PowerShell versions, but has the following consequences:

  • L'istanza di PowerShell che carica il modulo o la libreria deve eseguire almeno .NET 4.6.1. .NET 4.6 e .NET 4.5.2 non supportano .NET Standard.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. Si noti che una versione più recente di Windows PowerShell non implica una versione di .NET Framework più recente. Windows PowerShell 5.1 può essere eseguito in .NET 4.5.2.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.
  • Per usare un'istanza di PowerShell che esegue .NET Framework 4.7.1 o versione precedente, è necessaria l'implementazione di NETStandard.Library di .NET 4.6.1 per fornire netstandard.dll e altri assembly shim nelle versioni di .NET Framework precedenti.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.

PowerShell 6+ fornisce i propri assembly shim per l'inoltro dei tipi da .NET Framework 4.6.1 (e versioni successive) a .NET Core.PowerShell 6+ provides its own shim assemblies for type forwarding from .NET Framework 4.6.1 (and above) to .NET Core. Se quindi un modulo usa solo le API esistenti in .NET Core, PowerShell 6+ può caricarlo ed eseguirlo quando è stato compilato per .NET Framework 4.6.1 (la destinazione del runtime net461).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).

I moduli binari che usano PowerShell Standard per specificare come destinazione più versioni di PowerShell con una singola DLL pubblicata hanno quindi due opzioni:This means that binary modules using PowerShell Standard to target multiple PowerShell versions with a single published DLL have two options:

  1. Pubblicazione di un assembly compilato per il runtime di destinazione net461,Publishing an assembly built for the net461 target runtime. che implica:This involves:

    • Pubblicazione del progetto per il runtime net461Publishing the project for the net461 runtime
    • Compilazione in base al runtime netstandard2.0 (senza usare l'output di compilazione) per assicurarsi che tutte le API usate siano presenti anche in .NET Core.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. Pubblicazione di un assembly compilato per il runtime di destinazione netstandard2.0,Publishing an assembly build for the netstandard2.0 target runtime. che richiede:This requires:

    • Pubblicazione del progetto per il runtime netstandard2.0Publishing the project for the netstandard2.0 runtime
    • Acquisizione e copia delle dipendenze net461 di NETStandard.Library nel percorso di pubblicazione dell'assembly del progetto, in modo che il tipo dell'assembly venga inoltrato correttamente in .NET Framework.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.

Per compilare moduli o librerie di PowerShell che hanno come destinazione versioni di .NET Framework meno recenti, può essere preferibile specificare come destinazione più runtime di .NET.To build PowerShell modules or libraries targeting older .NET Framework versions, it may be preferable to target multiple .NET runtimes. In questo modo verrà pubblicato un assembly per ogni runtime di destinazione e l'assembly corretto dovrà essere caricato durante il caricamento del modulo (ad esempio con un file psm1 di piccole dimensioni come modulo radice).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).

Test di progetti PowerShell Standard in .NETTesting PowerShell Standard projects in .NET

Quando si tratta di testare il modulo in strumenti di esecuzione dei test per .NET, ad esempio xUnit, tenere presente che i controlli in fase di compilazione possono arrivare solo fino a un certo punto.When it comes to testing your module in .NET test runners like xUnit, remember that compile-time checks can only go so far. È necessario testare il modulo con le piattaforme di PowerShell pertinenti.You must test your module against the relevant PowerShell platforms.

Per testare le API compilate in base a PowerShell Standard in .NET, è consigliabile aggiungere Microsoft.Powershell.SDK come dipendenza di test con .NET Core (con la versione impostata in modo che corrisponda alla versione di PowerShell desiderata) e gli assembly di riferimento di Windows PowerShell appropriati con .NET Framework.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.

Per altre informazioni su PowerShell Standard e su come usarlo per scrivere un modulo binario che funzioni in più versioni di PowerShell, vedere questo post di blog.For more information on PowerShell Standard and using it to write a binary module that works in multiple PowerShell versions, see this blog post. Vedere anche il repository di PowerShell Standard in GitHub.Also see the PowerShell Standard repository on GitHub.

Microsoft.PowerShell.SDKMicrosoft.PowerShell.SDK

Microsoft.PowerShell.SDK è un metapacchetto che esegue il pull di tutti i componenti di PowerShell SDK in un singolo pacchetto NuGet.Microsoft.PowerShell.SDK is a meta-package that pulls together all of the components of the PowerShell SDK into a single NuGet package. Un'applicazione .NET autonoma può usare Microsoft.PowerShell.SDK per eseguire funzionalità di PowerShell arbitrarie senza dipendere da alcuna installazione o libreria di PowerShell esterna.A self-contained .NET application can use Microsoft.PowerShell.SDK to run arbitrary PowerShell functionality without depending on any external PowerShell installations or libraries.

Nota

PowerShell SDK fa riferimento a tutti i pacchetti di componenti che costituiscono PowerShell e che possono essere usati per lo sviluppo .NET con PowerShell.The PowerShell SDK just refers to all the component packages that make up PowerShell, and which can be used for .NET development with PowerShell.

Una determinata versione di Microsoft.Powershell.SDK contiene l'implementazione concreta della stessa versione dell'applicazione PowerShell. La versione 7.0 contiene l'implementazione di PowerShell 7.0 e l'esecuzione di comandi o script con questa versione sarà molto simile all'esecuzione in PowerShell 7.0.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.

L'esecuzione dei comandi di PowerShell dall'SDK è molto simile, anche se con alcune differenze, all'esecuzione da pwsh.Running PowerShell commands from the SDK is mostly, but not totally, the same as running them from pwsh. Start-Job, ad esempio, dipende attualmente dalla disponibilità del file eseguibile pwsh e quindi non funzionerà con Microsoft.Powershell.SDK per impostazione predefinita.For example, Start-Job currently depends on the pwsh executable being available, and so will not work with Microsoft.Powershell.SDK by default.

Specificare come destinazione Microsoft.Powershell.SDK da un'applicazione .NET consente l'integrazione con tutti gli assembly di implementazione di PowerShell, ad esempio System.Management.Automation, Microsoft.PowerShell.Management e altri assembly del modulo.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.

La pubblicazione di un'applicazione che ha come destinazione Microsoft.Powershell.SDK includerà tutti questi assembly e le dipendenze necessarie per PowerShell.Publishing an application targeting Microsoft.Powershell.SDK will include all these assemblies, and any dependencies PowerShell requires. Includerà anche altri asset richiesti da PowerShell nella build, ad esempio i manifesti per i moduli Microsoft.PowerShell.* e la directory ref richiesta da Add-Type.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.

Microsoft.Powershell.SDK, grazie alla sua completezza, è ideale per:Given the completeness of Microsoft.Powershell.SDK, it's best suited for:

  • Implementazione degli host di PowerShell.Implementation of PowerShell hosts.
  • Test xUnit delle librerie che hanno come destinazione gli assembly di riferimento di PowerShell.xUnit testing of libraries targeting PowerShell reference assemblies.
  • Chiamata a PowerShell In-Process da un'applicazione .NET.Invoking PowerShell in-process from a .NET application.

Microsoft.PowerShell.SDK può essere usato anche come destinazione di riferimento quando un progetto .NET deve essere usato come modulo o altrimenti caricato da PowerShell, ma dipende dalle API presenti solo in una determinata versione di PowerShell.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. Si noti che un assembly pubblicato in base a una versione specifica di Microsoft.PowerShell.SDK potrà essere caricato e usato in tutta sicurezza solo in tale versione di PowerShell.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. Per avere come destinazione più versioni di PowerShell con API specifiche, sono necessarie più build, ognuna delle quali ha come destinazione la propria versione di Microsoft.Powershell.SDK.To target multiple PowerShell versions with specific APIs, multiple builds are required, each targeting their own version of Microsoft.Powershell.SDK.

Nota

PowerShell SDK è disponibile solo per PowerShell versione 6 e successive.The PowerShell SDK is only available for PowerShell versions 6 and up. Per fornire funzionalità equivalenti con Windows PowerShell, usare gli assembly di riferimento di Windows PowerShell illustrati di seguito.To provide equivalent functionality with Windows PowerShell, use the Windows PowerShell reference assemblies described below.

System.Management.AutomationSystem.Management.Automation

Il pacchetto System.Management.Automation è il cuore di PowerShell SDK.The System.Management.Automation package is the heart of the PowerShell SDK. Esiste in NuGet, principalmente come asset per il pull di Microsoft.Powershell.SDK.It exists on NuGet, primarily, as an asset for Microsoft.Powershell.SDK to pull in. Può tuttavia essere usato anche direttamente come pacchetto per gli scenari di hosting minori e per i moduli che specificano una versione come destinazione.However, it can also be used directly as a package for smaller hosting scenarios and version-targeting modules.

Il pacchetto System.Management.Automation, in particolare, può essere un provider migliore di funzionalità di PowerShell nei casi seguenti:Specifically, the System.Management.Automation package may be a preferable provider of PowerShell functionality when:

  • Si vogliono solo usare le funzionalità del linguaggio di PowerShell (nello spazio dei nomi System.Management.Automation.Language), ad esempio il parser di PowerShell, AST e le API AST visitor (ad esempio, per l'analisi statica di PowerShell).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).
  • Si vogliono eseguire solo comandi specifici dal modulo Microsoft.PowerShell.Core ed è possibile eseguirli in uno stato sessione creato con il metodo factory CreateDefault2.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.

System.Management.Automation è anche un assembly di riferimento utile nei casi seguenti:Additionally, System.Management.Automation is a useful reference assembly when:

  • Si vogliono specificare come destinazione API presenti solo in una versione specifica di PowerShellYou wish to target APIs that are only present within a specific PowerShell version
  • Non si dipenderà da tipi che si verificano all'esterno dell'assembly System.Management.Automation (ad esempio, i tipi esportati dai cmdlet in moduli 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).

Assembly di riferimento di Windows PowerShellWindows PowerShell reference assemblies

Per PowerShell versione 5.1 e precedenti (Windows PowerShell), non sono disponibili SDK che forniscono un'implementazione di PowerShell perché l'implementazione di Windows PowerShell fa parte di Windows.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.

Gli assembly di riferimento di Windows PowerShell forniscono invece sia le destinazioni di riferimento che un modo per effettuare il rehosting di Windows PowerShell, esattamente come fa PowerShell SDK per le versioni 6 e successive.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.

Invece di distinguersi in base alla versione, gli assembly di riferimento di Windows PowerShell hanno un pacchetto diverso per ogni versione di Windows PowerShell:Rather than being differentiated by version, Windows PowerShell reference assemblies have a different package for each version of Windows PowerShell:

Per informazioni su come usare gli assembly di riferimento di Windows PowerShell, vedere Windows PowerShell SDK.Information on how to use the Windows PowerShell reference assemblies can be found in the Windows PowerShell SDK.

Esempi reali dell'uso di questi pacchetti NuGetReal-world examples using these NuGet packages

I progetti basati su strumenti di PowerShell hanno come destinazione pacchetti NuGet di PowerShell diversi a seconda delle esigenze.Different PowerShell tooling projects target different PowerShell NuGet packages depending on their needs. Ecco alcuni esempi significativi.Listed here are some notable examples.

PSReadLinePSReadLine

PSReadLine, il modulo di PowerShell che offre gran parte dell'esperienza avanzata della console di PowerShell, ha come destinazione PowerShell Standard come dipendenza invece che una versione specifica di PowerShell e ha come destinazione il runtime .NET net461 in csproj.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.

PowerShell 6+ fornisce i propri assembly shim che consentono a una DLL che ha come destinazione il runtime net461 "semplicemente di funzionare" quando viene caricata (reindirizzando il binding a mscorlib.dll di .NET Framework all'assembly .NET Core pertinente).PowerShell 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).

Questo semplifica considerevolmente il layout e la distribuzione del modulo PSReadLine perché PowerShell Standard garantisce che le uniche API usate saranno presenti sia in PowerShell 5.1 che in PowerShell 6+, consentendo allo stesso tempo di distribuire il modulo con un singolo assembly.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.

La destinazione .NET 4.6.1 significa che Windows PowerShell in esecuzione in .NET 4.5.2 e .NET 4.6 non è supportato.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 Editor ServicesPowerShell Editor Services

PowerShell Editor Services (PSES) è il back-end per l'[estensione PowerShell][] per Visual Studio Code ed è in realtà una forma di modulo di PowerShell che viene caricato da un file eseguibile di PowerShell e quindi subentra a tale processo per effettuare il rehosting di PowerShell al suo interno, fornendo al tempo stesso anche il protocollo del servizio di linguaggio e le funzionalità di adattatore di debug.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.

PSES fornisce destinazioni di implementazione concreta per consentire a netcoreapp2.1 di specificare come destinazione PowerShell 6+ (perché il runtime netcoreapp3.1 di PowerShell 7 è compatibile con le versioni precedenti) e a net461 di specificare come destinazione Windows PowerShell 5.1, ma contiene la maggior parte della logica in un secondo assembly che ha come destinazione netstandard2.0 e PowerShell Standard.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. Ciò gli consente di eseguire il pull delle dipendenze necessarie per le piattaforme .NET Core e .NET Framework, semplificando al tempo stesso la maggior parte della codebase dietro un'astrazione uniforme.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.

Essendo basato su PowerShell Standard, PSES richiede un'implementazione di runtime di PowerShell per poter essere testato correttamente.Because it is built against PowerShell Standard, PSES requires a runtime implementation of PowerShell in order to be tested correctly. A tale scopo, i test xUnit di PSES eseguono il pull di Microsoft.PowerShell.SDK e Microsoft.PowerShell.5.ReferenceAssemblies per fornire un'implementazione di PowerShell nell'ambiente di test.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.

Come per PSReadLine, PSES non può supportare .NET 4.6 e versioni precedenti, ma esegue un controllo in fase di esecuzione prima di chiamare una delle API che potrebbero causare un arresto anomalo dei runtime di .NET Framework precedenti.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

PSScriptAnalyzer, il linter per PowerShell, deve avere come destinazione gli elementi sintattici introdotti solo in determinate versioni di PowerShell.PSScriptAnalyzer, the linter for PowerShell, must target syntactic elements only introduced in certain versions of PowerShell. Poiché il riconoscimento di questi elementi sintattici viene eseguito implementando una classe AstVisitor2, non è possibile usare PowerShellStandard e anche implementare i metodi AST visitor per le sintassi di PowerShell più recenti.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.

Invece PSScriptAnalyzer specifica come destinazione ogni versione di PowerShell come configurazione della build e produce una DLL separata per ognuna di esse.Instead, PSScriptAnalyzer targets each PowerShell version as a build configuration, and produces a separate DLL for each of them. In questo modo aumentano le dimensioni e la complessità della build, ma è possibile:This increases build size and complexity, but allows:

  • Usare come destinazione l'API specifica della versioneVersion-specific API targeting
  • Implementare le funzionalità specifiche della versione sostanzialmente senza costi di runtimeVersion-specific functionality to be implemented with essentially no runtime cost
  • Supportare completamente Windows PowerShell fino a .NET Framework 4.5.2Total support for Windows PowerShell all the way down to .NET Framework 4.5.2

RiepilogoSummary

In questo articolo sono stati elencati e illustrati i pacchetti NuGet disponibili per l'impostazione della destinazione quando si implementa un progetto .NET che usa PowerShell e i motivi per cui usarne uno invece di un altro.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.

Se si è passati direttamente al riepilogo, tenere presenti questi suggerimenti generali:If you've skipped to the summary, some broad recommendations are:

  • I moduli di PowerShell devono essere compilati in base a PowerShell Standard se richiedono solo API comuni a versioni diverse di PowerShell.PowerShell modules should compile against PowerShell Standard if they only require APIs common to different PowerShell versions.
  • Gli host e le applicazioni di PowerShell che devono eseguire PowerShell internamente devono avere come destinazione PowerShell SDK per PowerShell 6+ o gli assembly di riferimento di Windows PowerShell pertinenti per Windows PowerShell.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.
  • I moduli di PowerShell che necessitano di API specifiche della versione devono avere come destinazione gli assembly di riferimento di PowerShell SDK o di Windows PowerShell per le versioni di PowerShell richieste, usandoli come assembly di riferimento (ovvero senza pubblicare le dipendenze di PowerShell).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).