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 référentiels 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 métadonnées de recherche et de package contiennent plus que les métadonnées trouvées dans le fichier nuspec de 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 Contrôle de version du protocole.

Chronologie

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	Fonctionnalité
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é aux réponses verified à SearchQueryService.
	Prise en charge de la Gestion sémantique de version 2.0.0
2018	Licences incorporées
2019	Icônes incorporées
	Abandon du package dans RegistrationBaseUrl (ressource de métadonnées de package)
2020	Informations sur les vulnérabilités du package dans RegistrationsBaseUrl (ressource de métadonnées de package)
	Paramètres de requête packageTypes ajoutés aux requêtes SearchQueryService
2021	Readme incorporé
2023	Demandes authentifiées PreAuthenticate VulnerabilityInforessource

Champ Propriétaire

Considérez deux des champs du fichier manifeste de package (.nuspec)<authors> et <owners>. Les auteurs de packages qui mettent en package le contenu tiers mettent souvent le nom tiers dans le champ <authors>. Le champ <owners> a été destiné à indiquer qui a publié le package sur un référentiel et, par conséquent, qui doit être contacté en cas de problèmes ou de questions de pack.

Cela a été expliqué dans un billet de blog de 2013, donc le champ <owners> est considéré comme déconseillé dans le fichier .nuspec. 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 de 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 métadonnées owner pour les réponses JSON des ressources de métadonnées de recherche et de package.

champ de réponse de recherche verified

L’interface utilisateur Gestionnaire de package de Visual Studio affiche une coche bleue à côté des packages dans les résultats du service Search, 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 pour les 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. avant que les préfixes réservés ont été implémentés, n’aura pas cette coche Vérifié. NuGet.org autorise également les préfixes à ne pas être exclusifs, afin que tout le monde puisse charger un package sous Contoso.ToolWithPlugins.Community.*, mais n’obtiendra pas de coche Vérifié.

Prise en charge de la Gestion sémantique de version 2.0.0

NuGet prend en charge un hybride entre System.Version et la gestion sémantique de version, mais la prise en charge de la gestion sémantique de version 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 Gestion sémantique de version 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 de Gestion sémantique de version 1.0.0 fournit [0-9A-Za-z-] un exemple de chaîne d’expression régulière pour les seuls caractères autorisés dans le cadre de l’étiquette de préversion et ne prend pas en charge les chaînes de métadonnées. La spécification de Gestion sémantique de version 2.0.0 permet aux identificateurs de préversion d’être séparés par . caractères (et interdit à un identificateur numérique d’avoir un zéro non significatif) et permet également d’ajouter des métadonnées de version à 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 à la System.Version de NET ou à la Gestion sémantique de version 1.0.0. 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 d’autocomplétion (SearchAutocompleteService) ont ajouté &semVerLevel={version} des paramètres de requête. Quand semVerLevel est manquante, supposons qu’il s’agit de la valeur 1.0.0. Comme la ressource de métadonnées de package, les packages dont la version est compatible uniquement avec la Gestion sémantique de version 2.0.0 ne doivent pas être retournés lorsque la valeur semVerLevel est inférieure à 2.0.0.

Fichiers incorporés

Les icônes de package, la licence et les fichiers readme peuvent être incorporées dans le package (et il est recommandé qu’ils le soient). Ces fichiers ont besoin d’un point de terminaison d’URL, soit extrait et placé sur un serveur de fichiers statique, soit une URL qui extrait dynamiquement les fichiers à partir de .nupkg sur demande, afin qu’ils puissent être affichés sans télécharger l’intégralité de 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étectent les modifications à mesure que le package a é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 sont représentés dans les résultats des métadonnées de recherche et de package, peuvent avoir la valeur licenseUrl définie sur l’expression de licence, l’URL encodée et ajoutées à la fin de https://licenses.nuget.org/. Par exemple : https://licenses.nuget.org/Apache-2.0. L’équipe du serveur NuGet.org dispose d’une documentation supplémentaire sur licenses.nuget.org.

Données de vulnérabilité et d’abandon connues

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

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

Si votre référentiel de packages est des packages « up-sourcing » à partir d’un autre référentiel, afin de mettre en miroir des packages dans votre propre flux, nous vous recommandons de vérifier régulièrement la source d’origine en cas d’abandon ou de données de vulnérabilité, et de mettre en miroir ces métadonnées dans votre propre référentiel. Si votre référentiel de packages est à l’origine de nuget.org spécifiquement, en conservant l’état de la dernière fois que vous avez vérifié (un « curseur »), vous pouvez utiliser la ressource Catalog pour vérifier efficacement s’il existe des mises à jour de package pour les packages que vous mettez en miroir, sans avoir à télécharger un grand nombre de fichiers JSON de métadonnées de package à partir du flux 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 ressource VulnerabilityInfo. Nuget.org fournit des données de vulnérabilité pour tous les avertissements 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 ([]).

Si votre référentiel de packages est destiné à être utilisé par les applications comme référentiel par défaut (au lieu de nuget.org), vous pouvez utiliser les données de vulnérabilité de nuget.org. L’une des options consiste à utiliser l’URL d’index de vulnérabilité de nuget.org dans votre index de service. Une autre option consiste à vérifier régulièrement l’index VulnerabilityInfo de nuget.org et à télécharger toutes les pages modifiées pour les mettre localement en miroir.

packageTypes requête de recherche

La CLI .NET permet de rechercher des packages d’outils .NET avec la commande dotnet tool search. Ceci est mis en œuvre en ajoutant un paramètre de requête &packageTypes={value} à la ressource de requête de recherche, qui lit les valeurs du champ <packageTypes> de fichier .nuspec du 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 .NET HttpClientHandler.PreAuthenticate, qui évite les requêtes HTTP anonymes uniquement lorsque les URL suivantes se trouvent dans le même répertoire virtuel, ou dans un sous-répertoire, d'une URL qui a été précédemment authentifiée. Cela réduit considérablement le nombre de demandes HTTP non authentifiées envoyées au serveur, ce qui réduit donc la charge de travail de votre serveur.

Voici quelques exemples :

URL	Le PreAuthenticate sera-t-il effectué ?
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 que l’index de service ou dans un sous-annuaire.
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 annuaire 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 un 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 « convivial », dans notre exemple feed), alors non, toutes les demandes adressées aux ressources sous l’URL canonique ne correspondent pas aux 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 le cache d’identifiants de HttpClientHandler. 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 de PreAuthenticate de HttpClientHandler, vous devez utiliser un proxy inverse pour vous assurer que tous les URL accessibles par le client dans l’index de service répondent à la règle « même ou sous-répértoire ».