Complementos multiplataforma de NuGet

En NuGet 4.8+ se ha agregado compatibilidad con complementos multiplataforma. Esto se logra con mediante la creación de un nuevo modelo de extensibilidad de complementos, que tiene que cumplir con un conjunto estricto de reglas de funcionamiento. Los complementos son ejecutables independientes (ejecutables en el mundo de .NET Core), que los clientes NuGet inician en un proceso independiente. Se trata de un complemento que realmente se escribe una vez y se ejecuta en todas partes. Funcionará con todas las herramientas de cliente de NuGet. Los complementos se pueden escribir en cualquier lenguaje de programación, pero la experiencia de instalación y desarrollo de complementos más fácil será con .NET. Se define un protocolo de comunicación con versiones entre el cliente NuGet y el complemento. Durante el inicio, los dos procesos negocian la versión del protocolo.

Cómo funciona

El flujo de trabajo de alto nivel se puede describir de la siguiente manera:

1. NuGet detecta complementos disponibles.
2. Cuando corresponda, NuGet iterará los complementos en orden de prioridad y los iniciará uno por uno.
3. NuGet usará el primer complemento que puede atender la solicitud.
4. Los complementos se apagarán cuando ya no sean necesarios.

Requisitos generales del complemento

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

• Admite el inicio sin estado en el contexto de seguridad actual de las herramientas de cliente de NuGet. Por ejemplo, las herramientas de cliente de NuGet no realizarán la elevación ni la inicialización adicional fuera del protocolo de complemento que se describe más adelante.
• No sea interactivo, a menos que se especifique explícitamente.
• Cumplir con la versión negociada del protocolo de complemento.
• Responda a todas las solicitudes dentro de un período de tiempo razonable.
• Respetar las solicitudes de cancelación de cualquier operación en curso.

Además, los complementos detectados desde la variable de entorno PATH (por ejemplo, instalados a través de dotnet tool) deben coincidir con el patrón de nombre de archivo nuget-plugin-*. La nuget-plugin- parte debe escribirse completamente en minúsculas.

NuGet 6.12 (MSBuild 17.12 y el SDK de .NET 9.0.100) y versiones anteriores también requerían que los complementos estén firmados con Authenticode en Windows.

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

• Complemento de descarga de paquetes NuGet
• Complemento de autenticación multiplataforma de NuGet
• Complementos de Herramientas Dotnet

Cliente - interacción del complemento

Las herramientas de cliente de NuGet y los complementos se comunican con JSON a través de flujos estándar (stdin, stdout, stderr). Todos los datos deben estar codificados con UTF-8. Los complementos se inician con el argumento "-Plugin". En caso de que un usuario inicie directamente un archivo ejecutable del complemento sin este argumento, el complemento puede proporcionar un mensaje informativo en lugar de esperar un protocolo de enlace. El tiempo de espera del protocolo de enlace es de 5 segundos. El complemento debe completar la configuración en tan poco tiempo como sea posible. Las herramientas de cliente NuGet solicitarán las operaciones que admite un complemento enviando el índice de servicio para la fuente NuGet. Un complemento puede usar el índice de servicio para comprobar la presencia de tipos de servicio admitidos.

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

Instalación y detección de complementos

NuGet busca complementos de una estructura de directorio basada en convención y examina la variable de entorno PATH.

Detección basada en convención

Los escenarios de CI/CD y los usuarios avanzados pueden usar 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 la versión 5.3+ de las herramientas de NuGet y versiones posteriores.

• 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 NuGet versión 5.3+)
• 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 NuGet versión 5.3+)
• NUGET_PLUGIN_PATHS - define los complementos que se usarán para ese proceso de NuGet, manteniendo la prioridad. Si se establece esta variable de entorno, invalida la detección basada en convención. Se omite si se especifica alguna de las variables específicas del marco.
• Ubicación del usuario, la ubicación principal de NuGet en %UserProfile%/.nuget/plugins. Esta ubicación no se puede anular. Se usará un directorio raíz diferente para complementos de .NET Core y .NET Framework.

Cada complemento debe instalarse en su propia carpeta. El punto de entrada del complemento será el nombre de la carpeta instalada, con las extensiones de .dll para .NET Core y .exe extensión para .NET Framework.

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

Descubrimiento de PATH

A partir de NuGet 6.13, NuGet buscará en cada directorio proporcionado en la variable de entorno PATH para los archivos que coincidan con el patrón nuget-plugin-*. La coincidencia de patrones distingue entre mayúsculas y minúsculas, y nuget-plugin- debe escribirse completamente en minúsculas. En Windows, el archivo debe tener una .exe extensión o .bat . En Linux y Mac, el archivo debe tener establecido el bit ejecutable.

Esto permite instalar complementos de NuGet a través de dotnet tool comandos, WinGet, el administrador de paquetes de una distribución de Linux o cualquier otro método que pueda colocar ejecutables en el PATH del usuario. Esto también permite que los complementos nuGet se escriban en cualquier lenguaje de programación (los complementos anteriores para Linux y Mac deben escribirse en .NET).

Se recomienda que los complementos se desarrollen en .NET para que puedan usar el paquete NuGet.Protocol, evitar tener que escribir el código RPC json y permitir que los clientes descubran el complemento a través de dotnet package search nuget-plugin.

Operaciones compatibles

Se admiten dos operaciones en el nuevo protocolo de complemento.

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

En el caso de NuGet en escenarios de dotnet.exe, los complementos deben poder ejecutarse en ese entorno de ejecución específico de la dotnet.exe. Está en el proveedor de complementos y del consumidor asegurarse de que se usa una combinación de dotnet.exe/plugin compatible. Un posible problema podría surgir con los complementos de ubicación del usuario cuando, por ejemplo, un 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 y creación de instancias de seguridad de los complementos es costosa. La operación de descarga se produce con más frecuencia que la operación de autenticación, pero el usuario de NuGet promedio solo es probable que tenga un complemento de autenticación. Para mejorar la experiencia, NuGet almacenará en caché las notificaciones de operación de la solicitud especificada. Esta caché es por complemento y 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 puede sobrescribir con la variable de entorno NUGET_PLUGINS_CACHE_PATH. Para borrar esta memoria caché, se puede ejecutar el comando local con la plugins-cache opción . La all opción locals ahora también eliminará la memoria caché de complementos.

Índice de mensajes de protocolo

Mensajes de protocolo versión 1.0.0 :

1. Cerrar

   • Dirección de la solicitud: NuGet:> complemento
   • La solicitud no contendrá ninguna carga
   • No se espera ninguna respuesta. La respuesta adecuada es que el proceso del complemento deba cerrarse rápidamente.

2. Copiar archivos en el paquete

   • Dirección de la solicitud: NuGet:> complemento
   • La solicitud contendrá:
     • el identificador y la versión del paquete
     • ubicación del repositorio de origen del paquete
     • ruta de acceso del directorio de destino
     • lista enumerada de archivos del paquete que se va a copiar a la ruta de acceso del directorio de destino
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • enumerable de rutas de acceso completas para los archivos copiados en el directorio de destino si la operación se realizó correctamente

3. Copiar archivo de paquete (.nupkg)

   • Solicitud de dirección: NuGet -> complemento
   • La solicitud contendrá:
     • el identificador y la versión del paquete
     • ubicación del repositorio de origen del paquete
     • ruta de acceso al archivo de destino
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación

4. Obtener credenciales

   • Dirección de la solicitud: complemento -> NuGet
   • La solicitud contendrá:
     • ubicación del repositorio de origen del paquete
     • el código de estado HTTP obtenido del repositorio de origen del paquete mediante las credenciales actuales
   • Una respuesta contendrá:
     • 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

5. Obtener archivos en el paquete

   • Dirección de la solicitud: NuGet:> complemento
   • La solicitud contendrá:
     • el identificador y la versión del paquete
     • ubicación del repositorio de origen del paquete
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • un enumerado de rutas de archivos en el paquete si la operación se realizó correctamente

6. Obtención de reclamaciones de operación

   • Dirección de la solicitud: NuGet:> complemento
   • La solicitud contendrá:
     • el servicio index.json para un origen de paquete
     • ubicación del repositorio de origen del paquete
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • un conjunto enumerable de operaciones admitidas (por ejemplo: descarga de paquetes) si la operación fue exitosa. Si un complemento no admite el origen del paquete, el complemento debe devolver un conjunto vacío de operaciones admitidas.

7. Obtención del hash de paquete

   • Dirección de la solicitud: NuGet:> complemento
   • La solicitud contendrá:
     • el identificador y la versión del paquete
     • ubicación del repositorio de origen del paquete
     • el algoritmo hash
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • un hash del archivo del paquete utilizando el algoritmo de hash solicitado si la operación fue exitosa

8. Obtener versiones de paquetes

   • Solicitud de dirección: complemento NuGet>
   • La solicitud contendrá:
     • el identificador del paquete
     • ubicación del repositorio de origen del paquete
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • una enumeración de versiones de paquetes si la operación se realizó correctamente

9. Obtención del índice de servicio

   • Dirección de la solicitud: complemento -> NuGet
   • La solicitud contendrá:
     • ubicación del repositorio de origen del paquete
   • Una respuesta contendrá:
     • un código de respuesta que indica el resultado de la operación
     • índice de servicio si la operación se realizó correctamente

10. Apretón de manos

    • Dirección de la solicitud: NuGet <:> complemento
    • La solicitud contendrá:
      • la versión actual del protocolo de complemento
      • la versión mínima admitida del protocolo de complemento
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación
      • la versión del protocolo negociado si la operación se realizó correctamente. Un error provocará la finalización del complemento.

11. Inicialización

    • Solicitud de dirección: NuGet -> complemento
    • La solicitud contendrá:
      • la versión de la herramienta cliente de NuGet
      • el lenguaje efectivo de la herramienta de cliente NuGet. Esto tiene en cuenta la configuración ForceEnglishOutput, si se usa.
      • el tiempo de espera de solicitud predeterminado, que reemplaza el valor predeterminado del protocolo.
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación. Un error provocará la finalización del complemento.

12. Registro

    • Dirección de la solicitud: complemento -> NuGet
    • La solicitud contendrá:
      • el nivel de registro de la solicitud
      • un mensaje para registrar
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación.

13. Supervisar la salida del proceso de NuGet

    • Instrucciones de solicitud: NuGet -> complemento
    • La solicitud contendrá:
      • El identificador de proceso de NuGet
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación.

14. Paquete de captura previa

    • Dirección de la solicitud: NuGet:> complemento
    • La solicitud contendrá:
      • el identificador y la versión del paquete
      • ubicación del repositorio de origen del paquete
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación

15. Establecimiento de credenciales

    • Dirección de la solicitud: NuGet:> complemento
    • La solicitud contendrá:
      • ubicación del repositorio de origen del paquete
      • el último nombre de usuario del origen del paquete conocido, si está disponible
      • la última contraseña de origen del paquete conocida, si está disponible.
      • el último nombre de usuario de proxy conocido, si está disponible
      • la última contraseña de proxy conocida, si está disponible.
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación

16. Establecer el nivel de registro

    • Dirección de la solicitud: NuGet:> complemento
    • La solicitud contendrá:
      • el nivel de registro predeterminado
    • Una respuesta contendrá:
      • un código de respuesta que indica el resultado de la operación

Mensajes de protocolo versión 2.0.0

17. Obtener reclamos de operación

• Dirección de la solicitud: NuGet:> complemento

  • La solicitud contendrá:
    • el servicio index.json para un origen de paquete
    • ubicación del repositorio de origen del paquete
  • Una respuesta contendrá:
    • un código de respuesta que indica el resultado de la operación
    • un enumerable de operaciones compatibles si la operación fue exitosa. Si un complemento no admite el origen del paquete, el complemento debe devolver un conjunto vacío de operaciones admitidas.

  Si el índice de servicio y el origen del paquete son NULL, el complemento puede responder con la autenticación.

18. Obtención de credenciales de autenticación

• Dirección de solicitud: complemento de NuGet>
• La solicitud contendrá:
  • Uri
  • isRetry
  • No interactivo
  • PuedeMostrarDiálogo
• Una respuesta incluirá
  • Nombre de usuario
  • Contraseña
  • Mensaje
  • Lista de tipos de autenticación
  • CódigoDeRespuestaDeMensaje