Complementos multiplataforma de NuGet

Artículo
12/21/2023

En NuGet 4.8 y versiones posteriores, se ha agregado compatibilidad con complementos multiplataforma. Esto se logra mediante la creación de un nuevo modelo de extensibilidad de complementos, que tiene que ajustarse a un estricto conjunto de reglas de operación. Los complementos son archivos ejecutables autocontenidos (ejecutables en el mundo de .NET Core) que los clientes de NuGet inician en un proceso independiente. Se trata de un complemento de escritura única y ejecución en todas partes. Funcionará con todas las herramientas de cliente de NuGet. Los complementos pueden ser .NET Framework (NuGet.exe, MSBuild.exe y Visual Studio) o .NET Core (dotnet.exe). Se define un protocolo de comunicación con versión entre el cliente de NuGet y el complemento. Durante el protocolo de enlace de inicio, los dos procesos negocian la versión del protocolo.

Con el fin de cubrir todos los escenarios de herramientas de cliente de NuGet, se necesitaría tanto un complemento de .NET Framework como uno de .NET Core. A continuación se describen las combinaciones de cliente y marco de trabajo de los complementos.

Herramienta de cliente	marco
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
MSBuild.exe	.NET Framework
NuGet.exe en Mono	.NET Framework

Cómo funciona

El flujo de trabajo de alto nivel puede describirse de la siguiente manera:

NuGet detecta los complementos disponibles.
En los casos oportunos, NuGet recorrerá en iteración los complementos en orden de prioridad y los iniciará uno por uno.
NuGet usará el primer complemento que puede atender la solicitud.
Los complementos se cerrarán cuando ya no se necesiten.

Requisitos generales de complementos

La versión actual del protocolo es 2.0.0. En esta versión, los requisitos son los siguientes:

Tener un ensamblado de firma Authenticode válido y de confianza que se ejecutará en Windows y Mono. Todavía no hay ningún requisito de confianza especial para ensamblados que se ejecutan en Linux y Mac. Problema relevante
Admitir el inicio de herramientas del cliente de NuGet sin estado en el contexto de seguridad actual. Por ejemplo, las herramientas del cliente de NuGet no realizarán elevaciones ni inicializaciones adicionales fuera del protocolo del complemento que se describe a continuación.
No ser interactivo, a menos que se especifique explícitamente.
Adaptarse a la versión del protocolo del complemento negociada.
Responder a todas las solicitudes dentro de un plazo de tiempo razonable.
Respetar las solicitudes de cancelación de cualquier operación en curso.

La especificación técnica se describe con más detalle en las siguientes especificaciones:

Interacción entre cliente y complemento

Las herramientas de cliente de NuGet y los complementos se comunican con JSON mediante flujos estándar (stdin, stdout y stderr). Todos los datos deben estar codificados en UTF-8. Los complementos se inician con el argumento "-Plugin". En caso de que un usuario inicie directamente un ejecutable de complemento sin este argumento, el complemento puede proporcionar un mensaje informativo en lugar de esperar a un protocolo de enlace. El tiempo de espera del protocolo de enlace es de cinco segundos. El complemento debe completar la configuración en el menor tiempo posible. Las herramientas de cliente de NuGet consultarán las operaciones admitidas de un complemento pasando el índice de servicio de un origen de NuGet. Un complemento puede usar el índice de servicio para comprobar la presencia de tipos de servicio compatibles.

La comunicación entre las herramientas del cliente de NuGet y el complemento es bidireccional. Cada solicitud tiene un tiempo de espera de cinco segundos. Si se supone que las operaciones deben tardan más tiempo, el proceso correspondiente debe enviar un mensaje de progreso para evitar que se agote el tiempo de espera de la solicitud. Después de un minuto de inactividad, un complemento se considera inactivo y se cierra.

Instalación y detección de complementos

Los complementos se detectarán mediante una estructura de directorios basada en convenciones. Los escenarios de CI/CD y los usuarios avanzados pueden utilizar variables de entorno para invalidar el comportamiento. Cuando se usan variables de entorno, solo se permiten rutas de acceso absolutas. Tenga en cuenta que NUGET_NETFX_PLUGIN_PATHS y NUGET_NETCORE_PLUGIN_PATHS solo están disponibles con las versiones 5.3 y posteriores de las herramientas de NuGet.

NUGET_NETFX_PLUGIN_PATHS: define los complementos que usarán las herramientas basadas en .NET Framework (NuGet.exe/MSBuild.exe/Visual Studio). Tiene prioridad sobre NUGET_PLUGIN_PATHS. (Solo en las versiones 5.3 y posteriores de NuGet)
NUGET_NETCORE_PLUGIN_PATHS: define los complementos que usarán las herramientas basadas en .NET Core (dotnet.exe). Tiene prioridad sobre NUGET_PLUGIN_PATHS. (Solo en las versiones 5.3 y posteriores de NuGet)
NUGET_PLUGIN_PATHS: define los complementos que se usarán para ese proceso de NuGet, con prioridad conservada. Si se establece esta variable de entorno, invalida la detección basada en convenciones. Se omite si se especifica cualquiera de las variables específicas del marco de trabajo.
User-location, ubicación de inicio de NuGet en %UserProfile%/.nuget/plugins. Esta ubicación no se puede invalidar. Se usará otro directorio raíz para los complementos de .NET Core y .NET Framework.

marco	Ubicación de detección raíz
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

Cada complemento debe instalarse en su propia carpeta. El punto de entrada del complemento será el nombre de la carpeta donde se ha realizado la instalación, con la extensión .dll para .NET Core y .exe para .NET Framework.

.nuget
    plugins
        netfx
            myPlugin
                myPlugin.exe
                nuget.protocol.dll
                ...
        netcore
            myPlugin
                myPlugin.dll
                nuget.protocol.dll
                ...

Nota:

Actualmente no hay ningún caso de usuario para la instalación de los complementos. Es tan sencillo como mover los archivos necesarios a la ubicación predeterminada.

Operaciones admitidas

Se admiten dos operaciones en el nuevo protocolo de complementos.

Nombre de operación	Versión mínima del protocolo	Versión mínima del cliente de NuGet
Descargar paquete	1.0.0	4.3.0
Autenticación	2.0.0	4.8.0

Ejecución de complementos en el entorno de ejecución correcto

Para NuGet en escenarios de dotnet.exe, los complementos deben poder ejecutarse en ese entorno de ejecución específico de dotnet.exe. El consumidor y el proveedor del complemento deben asegurarse de que se usa una combinación compatible de dotnet.exe y complemento. Podría surgir un posible problema con los complementos de user-location cuando, por ejemplo, un complemento dotnet.exe en el entorno de ejecución 2.0 intenta usar un complemento escrito para el entorno de ejecución 2.1.

Almacenamiento en caché de funcionalidades

La comprobación de seguridad y la creación de instancias de los complementos son costosas. La operación de descarga se realiza de forma más frecuente que la operación de autenticación; sin embargo, es probable que el usuario de NuGet medio solo tenga un complemento de autenticación. Para mejorar la experiencia, NuGet almacenará en caché las notificaciones de operaciones para la solicitud proporcionada. Esta caché se distribuye por complemento. La clave del complemento es la ruta de acceso del complemento y la expiración de esta caché de funcionalidades es de 30 días.

La memoria caché se encuentra en %LocalAppData%/NuGet/plugins-cache y se invalida con la variable de entorno NUGET_PLUGINS_CACHE_PATH. Para borrar esta caché, puede ejecutar el comando locals con la opción plugins-cache. La opción de locals all ahora también eliminará la memoria caché de los complementos.

Índice de mensajes de protocolo

Mensajes de la versión de protocolo 1.0.0:

Cerrado
- Dirección de la solicitud: NuGet -> complemento
- La solicitud no contendrá ninguna carga.
- No se espera ninguna respuesta. La respuesta correcta es que el proceso de complementos salga de forma rápida.
Copiar archivos en el paquete
- Dirección de la solicitud: NuGet -> complemento
- La solicitud contendrá lo siguiente:
  - el id. y la versión del paquete.
  - la ubicación del repositorio de origen del paquete.
  - la ruta de acceso del directorio de destino.
  - un enumerable de archivos del paquete que se va a copiar en la ruta de acceso del directorio de destino.
- Una respuesta contendrá lo siguiente:
  - un código de respuesta que indica el resultado de la operación.
  - un enumerable de rutas de acceso completas para los archivos copiados en el directorio de destino si la operación se realizó correctamente.
Copiar un archivo de paquete (.nupkg)
- Dirección de la solicitud: NuGet -> complemento
- La solicitud contendrá lo siguiente:
  - el id. y la versión del paquete.
  - la ubicación del repositorio de origen del paquete.
  - la ruta de acceso del archivo de destino.
- Una respuesta contendrá lo siguiente:
  - un código de respuesta que indica el resultado de la operación.
Obtener credenciales
- Dirección de la solicitud: complemento -> NuGet
- La solicitud contendrá lo siguiente:
  - la ubicación del repositorio de origen del paquete.
  - el código de estado HTTP obtenido del repositorio de origen del paquete con las credenciales actuales.
- Una respuesta contendrá lo siguiente:
  - un código de respuesta que indica el resultado de la operación.
  - un nombre de usuario, si está disponible.
  - una contraseña, si está disponible.
Obtener archivos en el paquete
- Dirección de la solicitud: NuGet -> complemento
- La solicitud contendrá lo siguiente:
  - el id. y la versión del paquete.
  - la ubicación del repositorio de origen del paquete.
- Una respuesta contendrá lo siguiente:
  - un código de respuesta que indica el resultado de la operación.
  - un enumerable de rutas de acceso de archivo en el paquete si la operación se realizó correctamente.
Obtener notificaciones de operación
- Dirección de la solicitud: NuGet -> complemento
- La solicitud contendrá lo siguiente:
  - el servicio index.json para un origen de paquete.
  - la ubicación del repositorio de origen del paquete.
- Una respuesta contendrá lo siguiente:
  - un código de respuesta que indica el resultado de la operación.
  - un enumerable de las operaciones admitidas (por ejemplo, descarga de paquetes) si la operación se realizó correctamente. Si un complemento no admite el origen del paquete, el complemento debe devolver un conjunto vacío de operaciones admitidas.