Guide d’implémentation du serveur NuGet

Dans certains cas, vous pouvez implémenter votre propre flux de package NuGet. De nombreuses implémentations existantes existent , ce qui vous permet d’héberger votre propre flux de manière variée, mais le protocole entre le logiciel client NuGet officiel et un flux de package est documenté, ce qui vous permet de créer votre propre implémentation de flux à partir de zéro.

Le protocole évolue au fil du temps et ce guide vise ceux qui souhaitent ou ont déjà implémenté un serveur de package NuGet.

Depuis la version initiale du protocole NuGet V3 en 2015, NuGet a évolué pour fournir aux développeurs une expérience plus riche, et cela nécessite des dépôts de packages pour effectuer des tâches supplémentaires afin de fournir la valeur supplémentaire à leurs consommateurs de packages, au-delà de la simple précision des métadonnées des packages hébergés et de retourner les métadonnées dans différents formulaires. Par exemple, les points de terminaison de recherche et de métadonnées de package contiennent plus que les métadonnées trouvées dans le fichier nuspec du nupkg.

Notez que ce guide est axé sur le protocole NuGet V3, car le protocole V2 est essentiellement non documenté et, depuis 2015, le protocole recommandé pour le client NuGet et la communication serveur est le protocole V3. Pour plus d’informations, consultez la section sur le versionnement des protocoles.

Chronology

Pour aider les auteurs de référentiels NuGet existants à tenir à jour les fonctionnalités les plus récentes de NuGet, voici la chronologie des fonctionnalités pertinentes mentionnées dans le reste du document.

Year	Feature
2013	Un billet de blog expliquant comment gérer les propriétaires de packages sur nuget.org précisé que les propriétaires affichés sur le site web sont les comptes qui ont l’autorisation de charger de nouvelles versions, et par conséquent les owners métadonnées du package sont ignorées.
2017	Ajouté verified aux SearchQueryService réponses.
	Prise en charge du versionnage sémantique 2.0.0
2018	Licences incorporées
2019	Icônes incorporées
	Mise en obsolescence du paquet dans RegistrationBaseUrl (ressource de métadonnées de paquet)
2020	Informations sur les vulnérabilités du package dans RegistrationsBaseUrl (ressource de métadonnées de package)
	Ajout du paramètre de requête packageTypes aux requêtes SearchQueryService
2021	Fichier Readme intégré
2023	Pré-authentifier les demandes authentifiées VulnerabilityInfo ressource
2025	Activer les téléchargements README incorporés

Champ Propriétaire

Considérons deux champs du fichier manifeste du package (.nuspec) : , <authors> et <owners>. Les auteurs de packages qui empaquetagent du contenu tiers mettent souvent le nom tiers dans le <authors> champ. Le <owners> champ a été destiné à indiquer qui a publié le package sur un dépôt et, par conséquent, qui doit être contacté en cas de problèmes ou de questions d’emballage.

Cela a été expliqué dans un billet de blog de 2013, donc le <owners> champ est considéré comme déconseillé dans le .nuspec fichier. Si le manifeste du package contient ces métadonnées, il doit être ignoré. Ne retournez pas la valeur du champ .nuspec du fichier <owners> dans la propriété owners dans la réponse JSON de la ressource de recherche ou la ressource de métadonnées de package.

Si votre référentiel dispose d’autorisations par package, il est recommandé de signaler les comptes disposant d’autorisations pour publier de nouvelles versions dans les owner métadonnées pour les réponses JSON des ressources de métadonnées de recherche et de package.

verified champ de réponse de recherche

L'interface utilisateur du gestionnaire de packages de Visual Studio affiche une coche bleue à côté des packs dans les résultats du service de recherche, lorsqu'un nouveau champ verified est défini sur true.

NuGet.org utilise ceci avec des données de préfixe de package (données côté serveur, et non une partie de l’API NuGet), afin que cette coche soit affichée uniquement aux clients lorsque le compte propriétaire du package a chargé le package. Par exemple, tout package avec préfixe microsoft.* est vérifié uniquement lorsque le package appartient au compte Microsoft sur nuget.org. Toute personne qui a chargé un package avec l’ID de package commençant par microsoft. les préfixes réservés avant l’implémentation des préfixes réservés, n’aura pas cette coche vérifiée. NuGet.org autorise également les préfixes à ne pas être exclusifs, ce qui permet à tout le monde de charger un package sous Contoso.ToolWithPlugins.Community.*, mais ne recevra pas de coche de vérification.

Prise en charge de Semantic Versioning 2.0.0

NuGet prend en charge un hybride entre System.Version et la version sémantique, mais la prise en charge de la version sémantique 2.0.0 a été ajoutée en 2017. Par conséquent, les ressources de l’API NuGet qui retournent des versions aux versions clientes inférieures à 3.6.0 ne doivent pas retourner les packages qui utilisent des fonctionnalités Semantic 2.0.0 incompatibles avec la version sémantique 1.0.0.

Les différences les plus importantes entre les deux versions sont les étiquettes de préversion et la chaîne de métadonnées. La spécification Semantic Versioning 1.0.0 fournit [0-9A-Za-z-] comme exemple de chaîne d’expression régulière pour les seuls caractères autorisés dans l’étiquette de préversion et ne prend pas en charge les chaînes de métadonnées. La spécification Semantic Versioning 2.0.0 permet aux identificateurs de préversion d’être séparés par des caractères . (et interdit à un identificateur numérique d’avoir un zéro initial) et permet également d’ajouter des métadonnées de build à la suite d’un +.

Dans la ressource de métadonnées de package (RegistrationsBaseUrl), les versions de ressources inférieures à la version 3.6.0 doivent uniquement retourner des packages conformes à .NET ou à la version 1.0.0 du Versioning Sémantique. Cela signifie que les packages dont les versions sont uniquement conformes à la gestion sémantique de version 2.0.0 sont invisibles pour ces versions clientes.

De même, le service de requête de recherche (SearchQueryService) et le service de saisie semi-automatique (SearchAutocompleteService) ont ajouté &semVerLevel={version} des paramètres de requête. Lorsqu'il manque semVerLevel, présumez la valeur 1.0.0. Comme la ressource de métadonnées de package, les packages dont la version est compatible uniquement avec la sémantique Versioning 2.0.0 ne doivent pas être retournés lorsque la semVerLevel valeur est inférieure à 2.0.0.

Fichiers incorporés

Les icônes de package, la licence et les fichiers lisez-moi peuvent être (et sont recommandés) incorporées dans le package. Ces fichiers ont besoin d'un point de terminaison URL, soit en les extrayant et en les plaçant sur un serveur de fichiers statique, soit en utilisant une URL qui extrait dynamiquement les fichiers sur demande à partir du .nupkg, afin qu’ils puissent être affichés sans avoir à télécharger l'intégralité du nupkg. Si votre référentiel de packages fournit la navigation et l’affichage des détails du package, vous pouvez utiliser les URL pour afficher aux clients le contenu incorporé sur votre site web.

Enfin, la ressource de métadonnées de package et la ressource de recherche doivent contenir l'URL hébergée dans les propriétés iconUrl, licenseUrl et/ou readmeUrl de la réponse JSON. Les packages (.nupkg fichiers) ne doivent pas être modifiés, car les fonctionnalités du client (fichiers de verrouillage et packages signés) détecteront les modifications comme si le package avait été falsifié.

Notez que la licence peut être une expression SPDX ou un fichier incorporé (mais pas les deux). Les packages qui utilisent une expression de licence, lorsqu’ils apparaissent dans les résultats de recherche et des métadonnées de package, peuvent avoir la valeur de licenseUrl définie comme l’expression de licence, encodée en URL et ajoutée à la fin de https://licenses.nuget.org/. Par exemple : https://licenses.nuget.org/Apache-2.0. L’équipe serveur NuGet.org dispose d’une documentation supplémentaire sur licenses.nuget.org.

Données de vulnérabilité et de dépréciation connues

Ressource de métadonnées de paquet (RegistrationsBaseUrl)

La ressource de métadonnées du paquet peut contenir des informations sur la dépréciation et la vulnérabilité. Cela permet aux clients de parcourir les packages dans l’interface utilisateur du Gestionnaire de package de Visual Studio, ou équivalent dans d’autres IDE, d’être avertis des problèmes de sécurité ou de maintenance importants.

Si votre dépôt de packages récupère des packages d’un autre référentiel pour les répliquer dans votre propre flux, nous vous recommandons de vérifier périodiquement la source d’origine pour des données de dépréciation ou de vulnérabilité, et de répliquer ces métadonnées dans votre propre référentiel. Si votre référentiel de packages provient directement de nuget.org, en conservant l'état de la dernière vérification (un « curseur »), vous pouvez utiliser la Catalog ressource pour vérifier efficacement s'il existe des mises à jour de package pour les packages que vous répliquez, sans avoir à télécharger un grand nombre de fichiers JSON de métadonnées de package à partir du flux en amont. Il existe un guide sur l’utilisation de la ressource de catalogue avec un exemple de code qui peut vous aider à commencer.

Base de données des vulnérabilités connues (VulnerabilityInfo)

Pour fournir une analyse des vulnérabilités hautes performances lors de la restauration de package, NuGet télécharge la liste complète des vulnérabilités connues de la VulnerabilityInfo ressource. Nuget.org fournit des données de vulnérabilité pour tous les avis examinés par GitHub à partir de la base de données GitHub Advisories, qui inclut des packages qui ne sont pas hébergés sur nuget.org.

Si votre référentiel de packages héberge des packages internes et que vous souhaitez fournir des informations de vulnérabilité aux clients utilisant votre propre flux, mais que vous n’avez pas encore de vulnérabilités de package divulguées, vous devez fournir un index de vulnérabilité avec une ou plusieurs pages de vulnérabilité dont le contenu est un tableau JSON vide ().[]

Réutilisation des données de vulnérabilité de nuget.org

NuGet ne nécessite pas que les ressources de l’index de service, ou l’index de vulnérabilité, doivent se trouver sur le même serveur que l’index de service lui-même. Toutefois, il existe plusieurs raisons pour lesquelles certaines entreprises choisissent de bloquer nuget.org au niveau du pare-feu ou d’avoir des flux locaux sur un réseau déconnecté. Pour éviter les problèmes de connectivité, nous vous recommandons de traiter les données de vulnérabilité de votre propre application web afin que les clients NuGet effectuent uniquement des connexions HTTP à l’hôte sur lequel le flux est installé.

✔️ Mettre en cache ou utiliser un proxy pour les pages de vulnérabilités dans votre propre application web

❌ NE PUBLIEZ PAS api.nuget.org dans votre index de service ou index de vulnérabilité sans configuration pour désactiver ce paramètre.

packageTypes requête de recherche

L’interface CLI .NET permet de rechercher des packages d’outils .NET avec la dotnet tool search commande. Cela est implémenté en ajoutant un &packageTypes={value} paramètre de requête à la ressource de requête de recherche, qui lit les valeurs du champ de fichier .nuspec du <packageTypes> package.

Structure d’URL pour les flux authentifiés

Comme décrit dans la vue d’ensemble de l’API NuGet, l’URL de départ de toutes les communications de serveur NuGet est l’index de service. Ce document contient les URL de toutes les autres ressources que les clients NuGet interrogeront. À partir de NuGet 6.7 (Visual Studio &MSBuild 17.7 et .NET SDK 7.0.400), NuGet utilise . NetHttpClientHandler.PreAuthenticate, qui évite uniquement les requêtes HTTP anonymes lorsque les URL suivantes se trouvent dans le même répertoire virtuel, ou un sous-répertoire, d’une URL qui a déjà été authentifiée. Cela réduit considérablement le nombre de requêtes HTTP non authentifiées envoyées au serveur, ce qui réduit donc la charge de travail de votre serveur.

Voici quelques exemples :

URL	Voudra-t-il pré-authentifier ?
https://pkgs.contoso.com/nuget/v3/feed/index.json	N/A, il s’agit de l’index de service.
https://pkgs.contoso.com/nuget/v3/search	Non, pas dans le même répertoire ou sous-répertoire que l’index de service.
https://search.pkgs.contoso.com/nuget/v3/feed/	Non, pas sur le même nom d’hôte que l’index de service.
https://pkgs.contoso.com/nuget/v3/feed/search	Oui, dans le même répertoire que l’index de service.
https://pkgs.contoso.com/nuget/v3/registration/	Non, pas dans un sous-répertoire de l’index de service.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Oui, dans un sous-répertoire de l’index de service.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Voir ci-dessous

Dans le dernier exemple, le serveur peut avoir un nom canonique (dans cet exemple de guid) et avoir un ou plusieurs alias. Si la demande d'index de service a été authentifiée sur une URL non canonique (le « nom amical », dans notre exemple feed), alors non, les demandes adressées aux ressources sous l'URL canonique ne respecteront pas les règles de HttpClientHandler pour PreAuthenticate. Toutefois, si l’URL non canonique est une redirection HTTP vers l’URL canonique, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsoncette URL sera utilisée dans HttpClientHandlerle cache d’informations d’identification. Dans ce cas, chaque requête adressée à l’index de service aura une latence supplémentaire, en raison de la redirection.

Bien que l’API V3 de NuGet ait été conçue pour fonctionner sur un serveur de fichiers statique, la ressource de recherche est l’exception qui nécessite toujours un service web dynamique pour traiter les demandes. Si vous souhaitez héberger la recherche ou toute autre ressource d’API NuGet sur différents serveurs, afin de bénéficier des avantages de HttpClientHandler et PreAuthenticate, vous devez utiliser un proxy inverse pour vous assurer que toutes les URL accessibles par le client dans l’index de service répondent à la règle du "même répertoire ou sous-répertoire".

Activer les téléchargements README incorporés

Une nouvelle ressource a été documentée pour construire une URL qui peut être utilisée pour télécharger un fichier README pour un package donné. Cela permet au client, comme l’interface utilisateur de gestion des packages dans VS, d’afficher le fichier README incorporé pour les packages qui n’ont pas été précédemment installés par l’utilisateur. Le client construit cette URL et tente de télécharger le fichier README à l’aide de la réponse à la demande pour déterminer si un fichier README est disponible. Cela signifie que les serveurs doivent s’attendre à plusieurs demandes adressées au point de terminaison construit lorsque les utilisateurs naviguent dans l’interface utilisateur pm.