NuGet

NuGet est un gestionnaire de package pour l’écosystème .NET et constitue la principale façon dont les développeurs découvrent et acquièrent des bibliothèques open source .NET. NuGet.org, un service gratuit fourni par Microsoft pour l’hébergement de packages NuGet, est l’hôte principal des packages NuGet publics, mais vous pouvez publier sur des services NuGet personnalisés tels que MyGet et Azure Artifacts.

Créer un package NuGet

Un package NuGet (*.nupkg) est un fichier zip qui contient des assemblys .NET et des métadonnées associées.

Il existe deux façons principales de créer un package NuGet. La méthode la plus récente et recommandée consiste à créer un package à partir d’un projet de style SDK (fichier projet dont le contenu commence par <Project Sdk="Microsoft.NET.Sdk">). Les assemblys et les cibles sont automatiquement ajoutés au package et les métadonnées restantes sont ajoutées au fichier MSBuild, comme le nom du package et le numéro de version. La compilation avec la commande dotnet pack génère un fichier *.nupkg au lieu d’assemblys.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

L’ancienne façon de créer un package NuGet consiste à utiliser un fichier *.nuspec et l’outil en ligne de commande nuget.exe. Un fichier nuspec vous donne un excellent contrôle, mais vous devez spécifier soigneusement les assemblys et cibles à inclure dans le package NuGet final. Il est facile de faire une erreur ou d’oublier de mettre à jour le nuspec lors d’apporter des modifications. L’avantage d’une nuspec est que vous pouvez l’utiliser pour créer des packages NuGet pour les frameworks qui ne prennent pas encore en charge un fichier projet de style SDK.

✔️ ENVISAGEZ d’utiliser un fichier projet de style SDK pour créer le package NuGet.

Dépendances de paquets

Les dépendances de package NuGet sont décrites en détail dans l’article Dépendances.

Métadonnées importantes du package NuGet

Un package NuGet prend en charge de nombreuses propriétés de métadonnées . Le tableau suivant contient les métadonnées principales que chaque package sur NuGet.org doit fournir :

Nom de la propriété MSBuild	Nom nuspec	Description
PackageId	id	Identificateur du package. Un préfixe de l’identificateur peut être réservé s’il répond aux critères .
PackageVersion	version	Version du package NuGet. Pour plus d'informations, consultez la version du package NuGet.
Title	title	Un titre convivial du package. Ce champ est défini sur PackageId par défaut.
Description	description	Description longue du package affiché dans l’interface utilisateur.
Authors	authors	Liste séparée par des virgules d’auteurs de packages, correspondant aux noms de profil sur nuget.org.
PackageTags	tags	Liste d’étiquettes et mots clés délimités par un espace ou un point-virgule qui décrivent le package. Les balises sont utilisées lors de la recherche de packages.
PackageIcon	icon	Chemin d’accès à une image dans le package à utiliser comme icône de package. En savoir plus sur les métadonnées icon.
PackageProjectUrl	projectUrl	URL de la page d’accueil du projet ou du référentiel source.
PackageLicenseExpression	license	L'identifiant SPDX de la licence du projet . Seules les licences approuvées OSI et FSF peuvent utiliser un identificateur. D’autres licences doivent utiliser PackageLicenseFile. En savoir plus sur les métadonnées license.

Important

Par défaut, un projet sans licence possède un copyright exclusif, ce qui empêche légalement d’autres personnes de l’utiliser.

✔️ ENVISAGEZ de choisir un nom de package NuGet avec un préfixe qui respecte les critères de réservation de préfixes de NuGet .

✔️ Utilisez un href HTTPS pour votre icône de package.

Les sites tels que NuGet.org s’exécutent avec HTTPS activé et l’affichage d’une image non HTTPS crée un avertissement de contenu mixte.

✔️ Utilisez une image d’icône de paquet de 64 x 64 qui dispose d’un arrière-plan transparent pour obtenir les meilleurs résultats d’affichage.

✔️ ENVISAGEZ la configuration de Source Link pour ajouter des métadonnées de contrôle de source à vos assemblys et à votre package NuGet.

Source Link ajoute automatiquement des métadonnées RepositoryUrl et RepositoryType au package NuGet. Source Link ajoute également des informations sur le code source exact à partir duquel le package a été créé. Par exemple, un package créé à partir d’un dépôt Git aura le hachage de validation ajouté en tant que métadonnées.

Packages de préversion

Les packages NuGet avec un suffixe de version sont considérés préversion. Par défaut, l’interface utilisateur du Gestionnaire de package NuGet affiche des versions stables, sauf si un utilisateur opte pour la préversion des packages, ce qui rend les packages de préversion idéaux pour les tests utilisateur limités.

<PackageVersion>1.0.1-beta1</PackageVersion>

Remarque

Un package stable ne peut pas dépendre d’un package de préversion. Votre package doit être en préversion ou dépendre d’une version stable antérieure.

✔️ Publiez un package de préversion lors du test, de l’aperçu ou de l’expérience

✔️ Publiez un package stable lorsqu’il est prêt pour que d’autres packages stables puissent le référencer.

Packages de symboles

Les fichiers de symboles (*.pdb) sont générés par le compilateur .NET en même temps que les assemblys. Les fichiers de symboles mappent les emplacements d’exécution au code source d’origine afin de pouvoir parcourir le code source à mesure qu’il s’exécute à l’aide d’un débogueur. NuGet prend en charge la génération d’un package de symboles distinct (*.snupkg) contenant des fichiers de symboles ainsi que le package principal contenant les assemblys .NET. L’idée des packages de symboles est qu’ils sont hébergés sur un serveur de symboles et sont uniquement téléchargés par un outil comme Visual Studio à la demande.

NuGet.org héberge son propre dépôt de serveur de symboles . Les développeurs peuvent utiliser les symboles publiés sur le serveur de symboles NuGet.org en ajoutant https://symbols.nuget.org/download/symbols à leurs sources de symboles dans Visual Studio.

Important

Le serveur de symboles NuGet.org prend uniquement en charge les nouveaux fichiers de symboles portables (*.pdb) créés par les projets de style SDK.

Pour utiliser le serveur de symboles NuGet.org lors du débogage d’une bibliothèque .NET, les développeurs doivent disposer de Visual Studio 2017 version 15.9 ou ultérieure.

Une alternative à la création d’un package de symboles consiste à incorporer des fichiers de symboles dans le package NuGet principal. Le package NuGet principal sera plus volumineux, mais les fichiers de symboles incorporés signifient que les développeurs n’ont pas besoin de configurer le serveur de symboles NuGet.org. Si vous créez votre package NuGet à l’aide d’un projet de style SDK, vous pouvez incorporer des fichiers de symboles en définissant la propriété AllowedOutputExtensionsInPackageBuildOutputFolder :

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

L’inconvénient de l’incorporation de fichiers de symboles est qu’ils augmentent la taille du package d’environ 30% pour les bibliothèques .NET compilées à l’aide de projets de style SDK. Si la taille du package est un problème, vous devez publier des symboles dans un package de symboles à la place.

✔️ ENVISAGEZ de publier des symboles en tant que package de symboles (*.snupkg) sur NuGet.org

Les packages de symboles (*.snupkg) fournissent aux développeurs une bonne expérience de débogage à la demande sans gonfler la taille principale du package et avoir un impact sur les performances de restauration pour ceux qui n’ont pas l’intention de déboguer le package NuGet.

La mise en garde est que les utilisateurs peuvent avoir besoin de rechercher et de configurer le serveur de symboles NuGet dans leur IDE (en tant que configuration unique) pour obtenir des fichiers de symboles. Visual Studio 2019 version 16.1 a ajouté le serveur de symboles nuGet.org à la liste des serveurs de symboles par défaut.

Précédent Suivant