Elección del paquete NuGet de PowerShell adecuado para un proyecto de .NETChoosing the right PowerShell NuGet package for your .NET project

Junto con los paquetes pwsh ejecutables publicados con cada versión de PowerShell, el equipo de PowerShell también mantiene varios paquetes disponibles en NuGet.Alongside the pwsh executable packages published with each PowerShell release, the PowerShell team also maintains several packages available on NuGet. Estos paquetes permiten que PowerShell se establezca como destino como una plataforma de API en .NET.These packages allow targeting PowerShell as an API platform in .NET.

Como aplicación de .NET que proporciona API y espera cargar las bibliotecas de .NET que implementan sus propios módulos binarios, es fundamental que PowerShell esté disponible en forma de paquete 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.

Actualmente hay varios paquetes NuGet que proporcionan alguna representación del área expuesta de la API de PowerShell.Currently there are several NuGet packages that provide some representation of the PowerShell API surface area. No siempre se ha determinado con claridad qué paquete usar con un proyecto en concreto.Which package to use with a particular project hasn't always been made clear. En este artículo se arroja luz sobre algunos escenarios comunes para los proyectos de .NET que tienen como destino PowerShell y sobre cómo elegir el paquete NuGet adecuado que establecer como destino para el proyecto .NET orientado 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.

Hospedaje frente a referenciaHosting vs referencing

Algunos proyectos de .NET buscan escribir código para que se cargue en un entorno de ejecución de PowerShell ya existente (como pwsh, powershell.exe, la consola integrada de PowerShell o el ISE), mientras que otros quieren ejecutar PowerShell en sus propias aplicaciones.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.

  • Las referencias son para cuando un proyecto, normalmente un módulo, está diseñado a fin de cargarse en PowerShell.Referencing is for when a project, usually a module, is intended to be loaded into PowerShell. Se debe compilar en las API que proporciona PowerShell para interactuar con este, pero la implementación de PowerShell la proporciona el proceso de PowerShell que se carga en él.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. Para las referencias, un proyecto puede usar ensamblados de referencia o ensamblados de entorno de ejecución reales como un destino de compilación, pero es necesario asegurarse de no publicar ninguno de estos con su compilación.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.
  • El hospedaje es cuando un proyecto necesita su propia implementación de PowerShell, normalmente porque es una aplicación independiente que necesita ejecutar PowerShell.Hosting is when a project needs its own implementation of PowerShell, usually because it is a standalone application that needs to run PowerShell. En este caso, no se pueden utilizar ensamblados de referencia puros.In this case, pure reference assemblies cannot be used. En su lugar, conviene depender de una implementación concreta de PowerShell.Instead, a concrete PowerShell implementation must be depended upon. Dado que se debe usar una implementación concreta de PowerShell, es necesario elegir una versión específica de PowerShell para el hospedaje; una única aplicación host no puede tener como destino varias versiones de 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.

Publicación de proyectos que tienen como destino PowerShell como referenciaPublishing projects that target PowerShell as a reference

Nota

En este artículo usamos el término publicación para hacer referencia a la ejecución de dotnet publish, que coloca una biblioteca de .NET en un directorio con todas sus dependencias, a punto para su implementación en un entorno de ejecución determinado.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.

Para evitar la publicación de las dependencias de proyecto que se usan como destinos de referencia de compilación, se recomienda establecer el atributo 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" />

Si olvida hacerlo y usa un ensamblado de referencia como destino, es posible que observe incidencias relacionadas con el uso de la implementación predeterminada del ensamblado de referencia en lugar de la implementación real.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. Esto puede adoptar la forma de un elemento NullReferenceException, ya que los ensamblados de referencia suelen simular la API de implementación simplemente devolviendo null.This may take the form of a NullReferenceException, since reference assemblies often mock the implementation API by simply returning null.

Tipos de claves de proyectos de .NET con destino en PowerShellKey kinds of PowerShell-targeting .NET projects

Aunque cualquier biblioteca o aplicación de .NET puede insertar PowerShell, hay algunos escenarios comunes en los que se usan las API de PowerShell:While any .NET library or application can embed PowerShell, there are some common scenarios that use PowerShell APIs:

  • Implementación de un módulo binario de PowerShellImplementing a PowerShell binary module

    Los módulos binarios de PowerShell son bibliotecas de .NET que PowerShell carga y que deben implementar las API de PowerShell, como los tipos PSCmdlet o CmdletProvider, para exponer los cmdlets o proveedores, respectivamente.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. Puesto que se cargan, los módulos buscan realizar la compilación en las referencias a PowerShell sin publicarlo en su compilación.Because they are loaded in, modules seek to compile against references to PowerShell without publishing it in their build. También es habitual que los módulos quieran admitir varias plataformas y versiones de PowerShell, idealmente con una sobrecarga de espacio en disco, complejidad o implementación repetida mínimas.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. Para obtener más información sobre los módulos, vea about_Modules.See about_Modules for more information about modules.

  • Implementación de un host de PowerShellImplementing a PowerShell Host

    Un host de PowerShell proporciona una capa de interacción para el entorno de ejecución de PowerShell.A PowerShell Host provides an interaction layer for the PowerShell runtime. Es una forma específica de hospedaje, donde un elemento PSHost se implementa como una interfaz de usuario nueva en PowerShell.It is a specific form of hosting, where a PSHost is implemented as a new user interface to PowerShell. Por ejemplo, ConsoleHost de PowerShell proporciona una interfaz de usuario de terminal para los ejecutables de PowerShell, mientras que el host de servicios del editor de PowerShell y el host de ISE proporcionan una interfaz gráfica de usuario parcialmente integrada en el editor en torno a 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. Aunque es posible cargar un host en un proceso de PowerShell existente, es mucho más habitual que una implementación de host actúe como una implementación de PowerShell independiente que redistribuye el motor de 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.

  • Llamada a PowerShell desde otra aplicación .NETCalling into PowerShell from another .NET application

    Al igual que con cualquier aplicación, se puede llamar a PowerShell como un subproceso para ejecutar cargas de trabajo.As with any application, PowerShell can be called as a subprocess to run workloads. Sin embargo, como aplicación de .NET, también es posible invocar PowerShell en el proceso con el fin de obtener objetos .NET completos para su uso en la aplicación que realiza la llamada.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. Se trata de una forma más general de hospedaje, donde la aplicación mantiene su propia implementación de PowerShell para uso interno.This is a more general form of hosting, where the application holds its own PowerShell implementation for internal use. Ejemplos de ello podrían ser un servicio o un demonio que ejecuten PowerShell para administrar el estado de la máquina, o una aplicación web que ejecute PowerShell a petición para hacer tareas como, por ejemplo, administrar implementaciones en la nube.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.

  • Pruebas unitarias de módulos de PowerShell desde .NETUnit testing PowerShell modules from .NET

    Aunque los módulos y otras bibliotecas diseñadas para exponer la función en PowerShell deben probarse principalmente desde PowerShell (se recomienda Pester), a veces es necesario realizar pruebas unitarias de las API escritas para un módulo de PowerShell desde .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. Esta situación implica que el código del módulo intenta tener como destino varias versiones de PowerShell, mientras que las pruebas deben ejecutarlo en implementaciones concretas y específicas.This situation involves the module code trying to target a number of PowerShell versions, while testing should run it on specific, concrete implementations.

Resumen de los paquetes NuGet de PowerShellPowerShell NuGet packages at a glance

En este artículo, trataremos los paquetes NuGet siguientes que exponen las API de PowerShell:In this article, we'll cover the following NuGet packages that expose PowerShell APIs:

  • PowerShellStandard.Library es un ensamblado de referencia que permite compilar un ensamblado único que pueden cargar varios entornos de ejecución de PowerShell.PowerShellStandard.Library, a reference assembly that enables building a single assembly that can be loaded by multiple PowerShell runtimes.
  • Microsoft.PowerShell.SDK es el modo de establecer como destino y volver a hospedar todo el SDK de PowerShell.Microsoft.PowerShell.SDK, the way to target and rehost the whole PowerShell SDK
  • El paquete System.Management.Automation es la implementación principal del entorno en ejecución y el motor de PowerShell, lo cual puede resultar útil en implementaciones hospedadas mínimas y en escenarios de destino específicos de la versión.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.
  • Los ensamblados de referencia de Windows PowerShell son la manera de establecer como destino y volver a hospedar de forma eficaz Windows PowerShell (versiones 5.1 y anteriores de PowerShell).The Windows PowerShell reference assemblies, the way to target and effectively rehost Windows PowerShell (PowerShell versions 5.1 and below).

Nota

El paquete NuGet de PowerShell no es en absoluto un paquete de la biblioteca de .NET, sino que proporciona la implementación de la herramienta global dotnet de PowerShell.The PowerShell NuGet package is not a .NET library package at all, but instead provides the PowerShell dotnet global tool implementation. No debe usarse en ningún proyecto, ya que solo proporciona un ejecutable.This should not be used by any projects, since it only provides an executable.

PowerShellStandard.LibraryPowerShellStandard.Library

La biblioteca de PowerShell estándar es un ensamblado de referencia que captura la intersección de las API de las versiones 7, 6 y 5.1 de PowerShell.The PowerShell Standard library is a reference assembly that captures the intersection of the APIs of PowerShell versions 7, 6 and 5.1. Esto proporciona una superficie de API comprobada en tiempo de compilación para compilar código de .NET, lo que permite a los proyectos de .NET tener como destino las versiones 7, 6 y 5.1 de PowerShell sin poner en riesgo la llamada a una API que no esté presente.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 estándar está diseñado a fin de escribir módulos de PowerShell u otro código previsto solo para ejecutarse después de cargarlo en un proceso de PowerShell.PowerShell Standard is intended for writing PowerShell modules, or other code only intended to be run after loading it into a PowerShell process. Dado que se trata de un ensamblado de referencia, PowerShell estándar no contiene ninguna implementación, por lo que no proporciona ninguna función para las aplicaciones independientes.Because it is a reference assembly, PowerShell Standard contains no implementation itself, so provides no functionality for standalone applications.

Uso de PowerShell estándar con diferentes entornos de ejecución de .NETUsing PowerShell Standard with different .NET runtimes

PowerShell estándar tiene como destino el entorno de ejecución de destino [.NET Standard 2.0][], que es un entorno de ejecución de fachada diseñado para proporcionar una área expuesta común compartida por .NET Framework y .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. Esto permite establecer como destino un único entorno de ejecución para generar un ensamblado único que funcionará con varias versiones de PowerShell. Sin embargo, conlleva las consecuencias siguientes:This allows targeting a single runtime to produce a single assembly that will work with multiple PowerShell versions, but has the following consequences:

  • La instancia de PowerShell que carga el módulo o la biblioteca debe ejecutar como mínimo .NET 4.6.1; .NET 4.6 y .NET 4.5.2 no admiten .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. Tenga en cuenta que una versión más reciente de Windows PowerShell no significa una versión más reciente de .NET Framework; Windows PowerShell 5.1 puede ejecutarse en .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.
  • Para trabajar con una instancia de PowerShell que ejecute .NET Framework 4.7.1 o una versión inferior, se requiere la implementación NETStandard.Library de .NET 4.6.1 para proporcionar netstandard.dll y otros ensamblados de correcciones de compatibilidad (shim) en versiones anteriores de .NET Framework.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 y versiones posteriores proporcionan sus propios ensamblados de correcciones de compatibilidad (shim) para el reenvío de tipos de .NET Framework 4.6.1 (y versiones posteriores) a .NET Core.PowerShell 6+ provides its own shim assemblies for type forwarding from .NET Framework 4.6.1 (and above) to .NET Core. Esto significa que, siempre que un módulo use solo las API que existen en .NET Core, PowerShell 6 y versiones posteriores podrán cargarlo y ejecutarlo cuando se haya compilado para .NET Framework 4.6.1 (el destino del entorno de ejecución de 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).

Esto significa que los módulos binarios que usan PowerShell estándar para establecer como destino varias versiones de PowerShell con un solo archivo .dll publicado tienen dos opciones:This means that binary modules using PowerShell Standard to target multiple PowerShell versions with a single published DLL have two options:

  1. Publicar un ensamblado compilado para el entorno de ejecución de destino de net461.Publishing an assembly built for the net461 target runtime. Esto implica lo siguiente:This involves:

    • Publicar el proyecto para el entorno de ejecución de net461.Publishing the project for the net461 runtime
    • Realizar la compilación también con el entorno de ejecución de netstandard2.0 (sin usar su salida de compilación) para asegurarse de que todas las API usadas también están presentes en .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. Publicar un ensamblado compilado para el entorno de ejecución de destino de netstandard2.0.Publishing an assembly build for the netstandard2.0 target runtime. Esto requiere lo siguiente:This requires:

    • Publicar el proyecto para el entorno de ejecución de netstandard2.0.Publishing the project for the netstandard2.0 runtime
    • Tomar las dependencias de net461 de NETStandard.Library y copiarlas en la ubicación de publicación del ensamblado del proyecto para que el ensamblado reenvíe el tipo corregido en .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.

Para compilar módulos o bibliotecas de PowerShell que tengan como destino versiones anteriores de .NET Framework, es posible que se prefiera establecer como destino varios entornos de ejecución de .NET.To build PowerShell modules or libraries targeting older .NET Framework versions, it may be preferable to target multiple .NET runtimes. Esto publicará un ensamblado para cada entorno de ejecución de destino y el ensamblado correcto tendrá que cargarse en el momento de la carga del módulo (por ejemplo, con un archivo psm1 pequeño como módulo raíz).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).

Prueba de proyectos de PowerShell estándar en .NETTesting PowerShell Standard projects in .NET

En cuanto a la prueba del módulo en los ejecutores de pruebas de .NET como xUnit, recuerde que las comprobaciones en tiempo de compilación solo pueden llegar hasta cierto punto.When it comes to testing your module in .NET test runners like xUnit, remember that compile-time checks can only go so far. Debe probar el módulo en las plataformas de PowerShell pertinentes.You must test your module against the relevant PowerShell platforms.

Para probar las API compiladas con PowerShell estándar en .NET, debe agregar Microsoft.Powershell.SDK como una dependencia de prueba con .NET Core (con la versión establecida para que coincida con la versión de PowerShell deseada) y los ensamblados de referencia de Windows PowerShell adecuados 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.

Para obtener más información sobre PowerShell estándar y usarlo a fin de escribir un módulo binario que funcione en varias versiones de PowerShell, vea esta entrada de 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. Vea también el repositorio de PowerShell estándar en GitHub.Also see the PowerShell Standard repository on GitHub.

Microsoft.PowerShell.SDKMicrosoft.PowerShell.SDK

Microsoft.PowerShell.SDK es un metapaquete que reúne todos los componentes del SDK de PowerShell en un único paquete NuGet.Microsoft.PowerShell.SDK is a meta-package that pulls together all of the components of the PowerShell SDK into a single NuGet package. Una aplicación de .NET independiente puede usar Microsoft.PowerShell.SDK para ejecutar una función arbitraria de PowerShell sin depender de las instalaciones o bibliotecas externas de PowerShell.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

El SDK de PowerShell solo hace referencia a todos los paquetes de los componentes que conforman PowerShell y que se pueden usar para el desarrollo de .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 versión de Microsoft.Powershell.SDK determinada contiene la implementación concreta de la misma versión de la aplicación de PowerShell; la versión 7.0 contiene la implementación de PowerShell 7.0, y los comandos o scripts que se ejecuten en esta se comportarán en gran medida como si se ejecutaran en 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.

La ejecución de comandos de PowerShell desde el SDK es, sobre todo, pero no del todo, lo mismo que ejecutarlos desde pwsh.Running PowerShell commands from the SDK is mostly, but not totally, the same as running them from pwsh. Por ejemplo, Start-Job actualmente depende de que el ejecutable pwsh esté disponible, por lo que no funcionará con Microsoft.Powershell.SDK de forma predeterminada.For example, Start-Job currently depends on the pwsh executable being available, and so will not work with Microsoft.Powershell.SDK by default.

Establecer como destino Microsoft.Powershell.SDK desde una aplicación .NET permite la integración con todos los ensamblados de implementación de PowerShell, como System.Management.Automation, Microsoft.PowerShell.Management y otros ensamblados de módulo.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 publicación de una aplicación que tiene como destino Microsoft.Powershell.SDK incluirá todos los ensamblados y las dependencias que requiera PowerShell.Publishing an application targeting Microsoft.Powershell.SDK will include all these assemblies, and any dependencies PowerShell requires. También incluirá otros recursos que PowerShell necesita en su compilación, como los manifiestos de módulo para los módulos de Microsoft.PowerShell.* y el directorio ref que necesita 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.

Dada la integridad de Microsoft.Powershell.SDK, resulta idóneo para lo siguiente:Given the completeness of Microsoft.Powershell.SDK, it's best suited for:

  • Implementación de hosts de PowerShell.Implementation of PowerShell hosts.
  • Pruebas xUnit de las bibliotecas que tienen como destino ensamblados de referencia de PowerShell.xUnit testing of libraries targeting PowerShell reference assemblies.
  • Invocación de PowerShell en curso desde una aplicación .NET.Invoking PowerShell in-process from a .NET application.

Microsoft.PowerShell.SDK también se puede usar como un destino de referencia cuando un proyecto de .NET está diseñado para que PowerShell lo use como un módulo o lo cargue de otro modo, pero depende de las API que solo están presentes en una versión concreta de 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. Tenga en cuenta que un ensamblado publicado en una versión específica de Microsoft.PowerShell.SDK solo se cargará y usará de forma segura en esa versión de 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. Para tener como destino varias versiones de PowerShell con API específicas, se necesitan varias compilaciones, habiendo establecido como destino para cada una de ellas su propia versión de 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

El SDK de PowerShell solo está disponible para las versiones 6 y posteriores de PowerShell.The PowerShell SDK is only available for PowerShell versions 6 and up. Para proporcionar una función equivalente con Windows PowerShell, use los ensamblados de referencia de Windows PowerShell que se describen a continuación.To provide equivalent functionality with Windows PowerShell, use the Windows PowerShell reference assemblies described below.

System.Management.AutomationSystem.Management.Automation

El paquete System.Management.Automation es el corazón del SDK de PowerShell.The System.Management.Automation package is the heart of the PowerShell SDK. Existe en NuGet, principalmente, como un recurso para que Microsoft.Powershell.SDK lo extraiga.It exists on NuGet, primarily, as an asset for Microsoft.Powershell.SDK to pull in. Sin embargo, también se puede usar directamente como un paquete para escenarios de hospedaje más pequeños y módulos que tengan como destino la versión.However, it can also be used directly as a package for smaller hosting scenarios and version-targeting modules.

En concreto, el paquete System.Management.Automation puede ser un proveedor preferido de la función de PowerShell en casos como los siguientes:Specifically, the System.Management.Automation package may be a preferable provider of PowerShell functionality when:

  • Únicamente quiere usar la función del lenguaje de PowerShell (en el espacio de nombres System.Management.Automation.Language), como las API del analizador de PowerShell, AST y AST Visitor (por ejemplo, para el análisis estático de 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).
  • Únicamente quiere ejecutar comandos específicos desde el módulo Microsoft.PowerShell.Core y poder ejecutarlos en un estado de sesión creado con el Factory Method 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.

Además, System.Management.Automation es un ensamblado de referencia útil en los siguientes casos:Additionally, System.Management.Automation is a useful reference assembly when:

  • Quiere tener como destino las API que solo están presentes en una versión específica de PowerShell.You wish to target APIs that are only present within a specific PowerShell version
  • No va a depender de los tipos que se produzcan fuera del ensamblado System.Management.Automation (por ejemplo, los tipos que exporten los cmdlets en módulos 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).

Ensamblados de referencia de Windows PowerShellWindows PowerShell reference assemblies

En las versiones 5.1 y anteriores de PowerShell (Windows PowerShell), no hay ningún SDK que proporcione una implementación de PowerShell, ya que la implementación de Windows PowerShell forma parte de 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.

En su lugar, los ensamblados de referencia de Windows PowerShell proporcionan destinos de referencia y una manera de volver a hospedar Windows PowerShell, actuando igual que el SDK de PowerShell para las versiones 6 y posteriores.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.

En lugar de diferenciarse por versión, los ensamblados de referencia de Windows PowerShell tienen un paquete diferente para cada versión de Windows PowerShell:Rather than being differentiated by version, Windows PowerShell reference assemblies have a different package for each version of Windows PowerShell:

Puede encontrar información sobre cómo usar los ensamblados de referencia de Windows PowerShell en el [SDK de Windows PowerShell][].Information on how to use the Windows PowerShell reference assemblies can be found in the Windows PowerShell SDK.

Ejemplos reales con estos paquetes NuGetReal-world examples using these NuGet packages

Diferentes proyectos de herramientas de PowerShell tienen como destino paquetes NuGet distintos de PowerShell en función de sus necesidades.Different PowerShell tooling projects target different PowerShell NuGet packages depending on their needs. Aquí se muestran algunos ejemplos importantes.Listed here are some notable examples.

PSReadLinePSReadLine

PSReadLine, el módulo de PowerShell que proporciona gran parte de la amplia experiencia de la consola de PowerShell, establece como destino PowerShell estándar como una dependencia en lugar de una versión específica de PowerShell y el entorno de ejecución net461 de .NET en su archivo 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 y versiones posteriores proporciona sus propios ensamblados de correcciones de compatibilidad (shim) que permiten que un archivo .dll que tiene como destino el entorno de ejecución net461 "solo funcione" cuando se cargue (mediante el redireccionamiento del enlace al elemento mscorlib.dll de .NET Framework al ensamblado de .NET Core correspondiente).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).

Esto simplifica el diseño y la entrega del módulo de PSReadLine de forma significativa, ya que PowerShell estándar garantiza que las únicas API utilizadas estarán presentes en PowerShell 5.1, y PowerShell 6 y versiones posteriores, a la vez que permite que el módulo se envíe solo con un único ensamblado.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.

El destino de .NET 4.6.1 significa que Windows PowerShell en ejecución en .NET 4.5.2 y .NET 4.6 no es compatible.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.

Servicios del editor de PowerShellPowerShell Editor Services

Los Servicios del editor de PowerShell (PSES) son el back-end de la extensión de PowerShell para [Visual Studio Code][] y, en realidad, son una forma del módulo de PowerShell que se carga mediante un ejecutable de PowerShell y, después, asume ese proceso para volver a hospedar PowerShell dentro de sí mismo, a la vez que proporciona las características adaptador de depuración y protocolo de servicio de lenguaje.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 proporciona destinos de implementación concretos para netcoreapp2.1 a fin de establecer como destino PowerShell 6 y versiones posteriores (dado que el entorno de ejecución netcoreapp3.1 de PowerShell 7 es compatible con versiones anteriores) y net461 con el fin de establecer como destino Windows PowerShell 5.1, pero contiene la mayor parte de su lógica en un segundo ensamblado que tiene como destino netstandard2.0 y PowerShell estándar.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. Esto permite extraer las dependencias requeridas para las plataformas .NET Core y .NET Framework, a la vez que todavía simplifica la mayor parte del código base detrás de una abstracción 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.

Dado que se basa en PowerShell estándar, PSES requiere una implementación del entorno de ejecución de PowerShell para que se pueda probar correctamente.Because it is built against PowerShell Standard, PSES requires a runtime implementation of PowerShell in order to be tested correctly. Para ello, las pruebas xUnit de PSES se extraen en Microsoft.PowerShell.SDK y Microsoft.PowerShell.5.ReferenceAssemblies para proporcionar una implementación de PowerShell en el entorno de prueba.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.

Al igual que con PSReadLine, PSES no admite .NET 4.6 y versiones anteriores, pero realiza una comprobación en tiempo de ejecución antes de llamar a cualquiera de las API que podrían provocar un bloqueo en los entornos de ejecución anteriores de .NET Framework.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, el linter para PowerShell, debe tener como destino los elementos sintácticos introducidos únicamente en determinadas versiones de PowerShell.PSScriptAnalyzer, the linter for PowerShell, must target syntactic elements only introduced in certain versions of PowerShell. Dado que el reconocimiento de estos elementos sintácticos se logra mediante la implementación de un elemento AstVisitor2, no es posible usar PowerShell estándar y, a la vez, implementar métodos de AST Visitor para las sintaxis de PowerShell más recientes.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.

En su lugar, PSScriptAnalyzer [establece como destino cada versión de PowerShell][] como una configuración de compilación y genera un archivo .dll independiente para cada una de ellas.Instead, PSScriptAnalyzer targets each PowerShell version as a build configuration, and produces a separate DLL for each of them. Esto aumenta el tamaño y la complejidad de la compilación, pero permite lo siguiente:This increases build size and complexity, but allows:

  • Destinatarios de API específicos de la versión.Version-specific API targeting
  • Función específica de la versión que se va a implementar básicamente sin costo del entorno de ejecución.Version-specific functionality to be implemented with essentially no runtime cost
  • Compatibilidad total para Windows PowerShell directamente con .NET Framework 4.5.2.Total support for Windows PowerShell all the way down to .NET Framework 4.5.2

ResumenSummary

En este artículo, hemos enumerado y descrito los paquetes NuGet disponibles para establecer como destino al implementar un proyecto de .NET que usa PowerShell y los motivos por los que podría tener que usar uno u otro.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.

Si ha ido directamente al resumen, estas son algunas recomendaciones generales:If you've skipped to the summary, some broad recommendations are:

  • Los módulos de PowerShell deben compilarse con PowerShell estándar si solo requieren las API comunes en diferentes versiones de PowerShell.PowerShell modules should compile against PowerShell Standard if they only require APIs common to different PowerShell versions.
  • Los hosts y aplicaciones de PowerShell que necesitan ejecutar PowerShell internamente deben tener como destino el SDK de PowerShell para PowerShell 6 y versiones posteriores, o los ensamblados de referencia de Windows PowerShell pertinentes para 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.
  • Los módulos de PowerShell que necesitan API específicas de la versión deben tener como destino el SDK de PowerShell o los ensamblados de referencia de Windows PowerShell para las versiones de PowerShell requeridas, usándolas como ensamblados de referencia (es decir, sin publicar las dependencias de 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).