Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En algunos casos, puede que quieras implementar tu propio feed de paquetes NuGet. Existen muchas implementaciones que le permiten hospedar su propio feed de paquetes de diversas maneras, pero el protocolo entre el software cliente oficial de NuGet y un feed de paquetes está documentado, lo que le permite crear su propia implementación de feed desde cero.
El protocolo evoluciona con el tiempo y esta guía está dirigida a aquellos que desean o ya han implementado un servidor de paquetes NuGet.
Desde la versión inicial del protocolo NuGet V3 en 2015, NuGet ha evolucionado para proporcionar a los desarrolladores una experiencia más completa, y esto requiere que los repositorios de paquetes realicen un trabajo adicional con el fin de proporcionar el valor adicional a sus consumidores de paquetes, más allá de simplemente exactamente los metadatos de los paquetes hospedados y devolver los metadatos en varios formularios. Por ejemplo, los puntos de conexión de metadatos de búsqueda y paquete contienen más que los metadatos que se incluyen en el archivo nuspec de nupkg.
Tenga en cuenta que esta guía se centra en el protocolo NuGet V3, ya que el protocolo V2 es esencialmente no documentado y, desde 2015, el protocolo recomendado para la comunicación de cliente y servidor nuGet es el protocolo V3. Para obtener más información, lea sobre el control de versiones de protocolo.
Chronology
Para ayudar a los autores de repositorios nuGet existentes a mantenerse al día con las características más recientes de NuGet, esta es la cronología de las características pertinentes mencionadas en el resto del documento.
| Year | Feature |
|---|---|
| 2013 |
Una entrada de blog que explica cómo administrar los propietarios de paquetes en nuget.org aclaró que los propietarios que se muestran en el sitio web son las cuentas que tienen permiso para cargar nuevas versiones y, por lo tanto, se omiten los owners metadatos del paquete. |
| 2017 |
Se ha agregado verified a las SearchQueryService respuestas. |
| Compatibilidad con versionamiento semántico 2.0.0 | |
| 2018 | Licencias insertadas |
| 2019 | Iconos incrustados |
Obsolescencia de paquetes en RegistrationBaseUrl (recurso de metadatos de paquetes) |
|
| 2020 |
Información de vulnerabilidad del paquete en RegistrationsBaseUrl (recurso de metadatos del paquete) |
Se ha agregado packageTypes el parámetro de consulta a las SearchQueryService solicitudes. |
|
| 2021 | Léame incrustado |
| 2023 |
Preautenticar solicitudes autenticadas VulnerabilityInfo recurso |
| 2025 | Habilitar la descarga de LÉAME incrustados |
Campo de Propietario
Considere dos de los campos del archivo de manifiesto de paquete (.nuspec), <authors> y <owners>.
Los autores de paquetes que empaquetan contenido de terceros suelen colocar el nombre de terceros en el <authors> campo.
El <owners> campo estaba pensado para indicar quién publicó el paquete en un repositorio y, por lo tanto, quién debe ponerse en contacto en caso de problemas de empaquetado o preguntas.
Esto se explicó en una entrada de blog de 2013, por lo que el campo <owners> se considera en desuso en el archivo .nuspec.
Si el manifiesto del paquete contiene estos metadatos, se debe omitir.
No devuelva el valor del campo .nuspec del archivo <owners> en la propiedad owners en la respuesta JSON del recurso de búsqueda o del recurso de metadatos del paquete .
Si el repositorio tiene permisos por paquete, se recomienda informar sobre las cuentas que tienen permisos para publicar nuevas versiones en los metadatos de owner para buscar y empaquetar las respuestas JSON de los recursos de metadatos.
verified campo de respuesta del motor de búsqueda
La interfaz de usuario del Administrador de paquetes de Visual Studio muestra una marca de verificación azul junto a los paquetes en los resultados del servicio de búsqueda, cuando un nuevo campo verified se establece en true.
NuGet.org usa esto con datos de prefijo de paquete (datos del lado servidor, no parte de la API de NuGet), de modo que esta marca de verificación solo se muestra a los clientes cuando la cuenta propietaria del paquete cargó el paquete.
Por ejemplo, cualquier paquete con prefijo microsoft.* solo se comprueba cuando el paquete es propiedad de la cuenta Microsoft en nuget.org. Cualquier persona que haya cargado un paquete con el identificador de paquete a partir microsoft. de antes de implementar los prefijos reservados, no tendrá esta marca de verificación comprobada.
NuGet.org también permite que los prefijos no sean exclusivos, de modo que cualquier usuario pueda cargar un paquete en Contoso.ToolWithPlugins.Community.*, pero no obtendrá una marca de verificación comprobada.
Compatibilidad con versionamiento semántico 2.0.0
NuGet admite un híbrido entre System.Version y la versión semántica, pero la compatibilidad con la versión semántica 2.0.0 se agregó en 2017.
Por lo tanto, los recursos de la API de NuGet que devuelven versiones de cliente inferiores a 3.6.0 no deben devolver paquetes que usen características semánticas 2.0.0 que no sean compatibles con versionamiento semántico 1.0.0.
Las diferencias más importantes entre las dos versiones son las etiquetas de versión preliminar y la cadena de metadatos.
La especificación de Versionado semántico 1.0.0 proporciona [0-9A-Za-z-] como ejemplo de cadena de expresión regular para los únicos caracteres permitidos como parte de la etiqueta de pre-lanzamiento y no admite cadenas de metadatos.
La especificación de Versionamiento Semántico 2.0.0 permite separar los id. de versión preliminar mediante caracteres . y prohíbe que un identificador numérico tenga un cero inicial. Asimismo, permite agregar metadatos de generación después de +.
En el recurso de metadatos del paquete (RegistrationsBaseUrl), las versiones de recursos inferiores a 3.6.0 solo deben devolver paquetes que cumplan con el versionado semántico 1.0.0 o con .NET System.Version.
Esto significa que los paquetes cuyas versiones solo son compatibles con versionamiento semántico 2.0.0 son invisibles para estas versiones de cliente.
Del mismo modo, el servicio de consulta de búsqueda (SearchQueryService) y el servicio de autocompletar (SearchAutocompleteService) agregaron &semVerLevel={version} parámetros de consulta.
Cuando semVerLevel falta, asuma el valor 1.0.0.
Al igual que el recurso de metadatos del paquete, los paquetes cuya versión solo es compatible con versionamiento semántico 2.0.0 no se deben devolver cuando el semVerLevel valor es inferior a 2.0.0.
Archivos incrustados
Los iconos de paquete, la licencia y los archivos Léame pueden estar incrustados (y se recomienda que se inserten en el paquete).
Estos archivos necesitan un punto de conexión de dirección URL, ya sea mediante su extracción y colocación en un servidor de archivos estáticos, o por medio de una dirección URL que extraiga dinámicamente los archivos de .nupkg cuando así se requiera, de modo que se puedan visualizar sin descargar todo el archivo nupkg.
Si el repositorio de paquetes proporciona información de exploración y visualización de paquetes, puede usar las direcciones URL para mostrar a los clientes el contenido insertado en su sitio web.
Por último, el recurso de metadatos del paquete y el recurso de búsqueda deben contener la dirección URL hospedada en las iconUrlpropiedades , licenseUrly/o readmeUrl de la respuesta JSON.
Los paquetes (.nupkg archivos) no se deben modificar, ya que las características de cliente (archivos de bloqueo y paquetes firmados) detectarán modificaciones como el paquete que se ha alterado.
Tenga en cuenta que la licencia podría ser una expresión SPDX o un archivo incrustado (pero no ambos).
Los paquetes que usan una expresión de licencia, cuando se muestran en los resultados de búsqueda y metadatos del paquete, pueden tener la expresión de licencia establecida en licenseUrl, codificada en URL y anexada al final de https://licenses.nuget.org/.
Por ejemplo: https://licenses.nuget.org/Apache-2.0.
El equipo del servidor de NuGet.org tiene la documentación adicional en licenses.nuget.org.
Datos conocidos de vulnerabilidad y desuso
Recurso de metadatos de paquete (RegistrationsBaseUrl)
El recurso de metadatos del paquete puede contener información de desuso y vulnerabilidad . Esto permite a los clientes examinar paquetes en la interfaz de usuario del Administrador de paquetes de Visual Studio, o equivalente en otros IDE, recibir notificaciones de problemas importantes de seguridad o mantenimiento.
Si el repositorio de paquetes está “reuniendo” paquetes de otro repositorio a fin de reflejar los paquetes de tu propio feed, te recomendamos comprobar periódicamente el origen por si hay datos de vulnerabilidades o de desuso, y reflejar esos metadatos en tu propio repositorio.
Si el repositorio de paquetes reúne los datos de nuget.org específicamente, y mantiene el estado de la última vez que lo has comprobado (por medio de un “cursor”), puedes utilizar el recurso Catalog para comprobar de forma eficaz si existen actualizaciones de los paquetes que estás reflejando, y evitarte así tener que descargar un gran número de archivos JSON de metadatos de paquete desde el feed del canal de subida.
Hay una guía sobre el uso del recurso de catálogo con código de ejemplo que puede ayudarle a empezar.
Base de datos de vulnerabilidades conocidas (VulnerabilityInfo)
Para proporcionar un examen de vulnerabilidades de alto rendimiento durante la restauración del paquete, NuGet descarga la lista completa de vulnerabilidades conocidas del VulnerabilityInfo recurso.
Nuget.org proporciona datos de vulnerabilidad para todos los avisos revisados de GitHub de la base de datos de Avisos de GitHub, que incluye paquetes que no están hospedados en nuget.org.
Si el repositorio de paquetes hospeda paquetes de primera parte y desea proporcionar información de vulnerabilidad a los clientes que usan su propia fuente, pero aún no tiene vulnerabilidades de paquete divulgadas, debe proporcionar un índice de vulnerabilidades con una o varias páginas de vulnerabilidades cuyo contenido sea una matriz JSON vacía ([]).
Reutilización de los datos de vulnerabilidades de nuget.org
NuGet no requiere que los recursos del índice de servicio o el índice de vulnerabilidad deben estar en el mismo servidor que el propio índice de servicio. Sin embargo, hay varias razones por las que algunas empresas eligen bloquear nuget.org en el firewall o tener fuentes locales en una red desconectada. Para evitar problemas de conectividad, se recomienda proveer los datos de vulnerabilidad desde su propia aplicación web, de modo que los clientes NuGet solo realicen conexiones HTTP al host en el que está instalado el canal.
✔️ Almacenar en caché o proxy las páginas de vulnerabilidades en su propia aplicación web
❌ NO anuncie api.nuget.org en el índice de servicio o en el índice de vulnerabilidades sin una configuración para desactivarlo.
packageTypes consulta de búsqueda
La CLI de .NET permite buscar paquetes de herramientas de .NET con el dotnet tool search comando .
Esto se implementa agregando un &packageTypes={value} parámetro de consulta al recurso de consulta de búsqueda, que lee los valores del campo de archivo .nuspec del <packageTypes> paquete.
Estructura de URL para feeds autenticados
Como se describe en la información general de la API de NuGet, la dirección URL inicial de toda la comunicación del servidor NuGet es el índice de servicio.
Este documento contiene las direcciones URL de todos los demás recursos que consultarán los clientes NuGet.
A partir de NuGet 6.7 (Visual Studio y MSBuild 17.7 y SDK de .NET 7.0.400), NuGet utiliza .NET HttpClientHandler.PreAuthenticate, que solo evita solicitudes HTTP anónimas cuando las direcciones URL posteriores están en el mismo directorio virtual, o en un subdirectorio, de una dirección URL que se haya autenticado previamente.
Esto reducirá drásticamente el número de solicitudes HTTP no autenticadas enviadas al servidor y, por tanto, reducirá la carga de trabajo del servidor.
Estos son algunos ejemplos:
| URL | ¿Se preautenticará? |
|---|---|
| https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, este es el índice de servicio. |
| https://pkgs.contoso.com/nuget/v3/search | No, no en el mismo directorio ni en el mismo subdirectorio que el índice de servicio. |
| https://search.pkgs.contoso.com/nuget/v3/feed/ | No, no en el mismo nombre de host que el índice de servicio. |
| https://pkgs.contoso.com/nuget/v3/feed/search | Sí, en el mismo directorio que el índice de servicio. |
| https://pkgs.contoso.com/nuget/v3/registration/ | No, no en un subdirectorio del índice de servicio. |
| https://pkgs.contoso.com/nuget/v3/feed/registration/ | Sí, en un subdirectorio del índice de servicios. |
| https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Consulte a continuación |
En el último ejemplo, el servidor podría tener un nombre canónico (en este ejemplo, un guid) y tener uno o varios alias.
Si la solicitud de índice de servicio se autenticó en una dirección URL no canónica (el nombre “descriptivo”, en nuestro feed de muestra), las solicitudes para los recursos de la dirección URL canónica no coincidirán con las reglas de HttpClientHandler para PreAuthenticate.
Sin embargo, si la dirección URL no canónica es un redireccionamiento HTTP a la dirección URL canónica, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, esta dirección URL se usará en la caché de credenciales de HttpClientHandler.
En este caso, todas las solicitudes al índice de servicio tendrán latencia adicional, debido al redireccionamiento.
Aunque la API V3 de NuGet se diseñó para funcionar en un servidor de archivos estáticos, el recurso de búsqueda es la excepción que siempre requiere un servicio web dinámico para procesar las solicitudes.
Si desea alojar la búsqueda, o de hecho cualquier otro recurso de API de NuGet, en distintos servidores, para beneficiarse de las características de HttpClientHandler y PreAuthenticate, deberá usar un proxy inverso para asegurarse de que todas las URLs dirigidas al cliente en el índice de servicio cumplan con la regla de "mismo directorio o subdirectorio".
Habilitar descargas de README integradas
Se documentó un nuevo recurso para construir una URL que se puede usar para descargar un archivo README para un paquete determinado. Esto permitirá a los clientes, como la interfaz de administración de paquetes en VS, mostrar el archivo README incrustado para los paquetes que el usuario no haya instalado previamente. El cliente construirá esta URL e intentará descargar el archivo README, utilizando la respuesta a la solicitud para ver si hay un README disponible. Esto significa que los servidores deben esperar varias solicitudes al punto de conexión construido a medida que los usuarios navegan por la interfaz de usuario de PM.