Créer un package NuGet avec l’interface CLI dotnet

  • Article

Les packages NuGet contiennent du code que les développeurs peuvent réutiliser dans leurs projets. Quoi que votre code fasse ou contienne, vous utilisez un outil en ligne de commande, soit nuget.exe, soit dotnet.exe, pour créer le package NuGet.

Cet article décrit comment créer un package à l’aide de l’interface CLI dotnet. À partir de Visual Studio 2017, l’interface CLI dotnet est incluse dans les charges de travail .NET et .NET Core. Si vous devez installer l’interface CLI dotnet ou d’autres outils clients NuGet, consultez Installer les outils clients NuGet.

Cette sujet s’applique uniquement à .NET et aux autres projets qui utilisent le format de style SDK. Pour ces projets, NuGet utilise des informations du fichier projet pour créer un package. Pour un didacticiel de démarrage rapide, consultez Créer des packages avec l’interface CLI dotnet ou Créer des packages avec Visual Studio.

La commande MSBuild msbuild -t:pack est fonctionnellement équivalente à dotnet pack. Pour plus d’informations sur la création d’un package avec MSBuild, consultez Créer un package NuGet à l’aide de MSBuild.

Remarque

Définir des propriétés

Vous pouvez créer un exemple de projet de bibliothèque de classes à l’aide de la commande dotnet new classlib et empaqueter le projet à l’aide de dotnet pack. La commande dotnet pack utilise les propriétés suivantes. Si vous ne spécifiez pas de valeurs dans le fichier projet, la commande utilise les valeurs par défaut.

  • PackageId, l’identificateur doit être unique sur nuget.org ainsi que sur toutes les autres cibles qui hébergent le package. Si vous ne spécifiez pas de valeur, la commande utilise le AssemblyName.
  • Version est un numéro de version spécifique dans le formulaire Major.Minor.Patch[-Suffix], où -Suffix identifie les versions préliminaires. Si elle n’est pas spécifiée, la valeur par défaut est 1.0.0.
  • Authors sont les auteurs du package. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.
  • Company sont les informations sur la société. Si la valeur n’est pas spécifiée, la valeur par défaut est la valeur Authors.
  • Product sont les informations sur le produit. Si elle n’est pas spécifiée, la valeur par défaut est AssemblyName.

Dans Visual Studio, vous pouvez définir ces valeurs dans les propriétés du projet. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, sélectionnez Propriétés, puis sélectionnez la section Package. Vous pouvez également ajouter des propriétés directement dans le fichier .csproj ou dans d’autres fichier projet.

L’exemple suivant montre un fichier projet avec des propriétés de package ajoutées.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

Vous pouvez ajouter d’autres propriétés facultatives, telles que Title, PackageDescriptionet PackageTags.

Remarque

Pour les packages que vous générez pour la consommation publique, veuillez porter une attention particulière à la propriété PackageTags. Les balises aident d’autres personnes à trouver votre package et à comprendre ce qu’il fait.

La commande dotnet pack convertit automatiquement les fichiers PackageReference dans les fichiers de projet et les transforme en dépendances dans le package créé. Vous pouvez contrôler les ressources à inclure via les balises IncludeAssets, ExcludeAssets et PrivateAssets. Pour plus d’informations, consultez Contrôle des ressources des dépendances.

Pour plus d’informations sur les dépendances, les propriétés facultatives et le contrôle de version, consultez :

Choisir un identificateur de package unique et définir le numéro de version

L’identificateur de package et le numéro de version identifient de façon unique le code exact contenu dans le package.

Suivez ces meilleures pratiques pour créer l’identificateur de package :

  • L’identificateur doit être unique sur nuget.org ainsi que sur tous les autres emplacements qui hébergent le package. Pour éviter les conflits, utilisez le nom de votre société comme première partie de l’identificateur est un bon modèle.

  • Suivez une convention d’affectation de noms similaire à celle de l’espace de noms de .NET, à l’aide de la notation par points. Par exemple, utilisez Contoso.Utility.UsefulStuff plutôt que Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Il est également utile pour les consommateurs si vous faites correspondre à l’identificateur du package à l’espace de noms utilisé par le code.

  • Si vous produisez un package d’exemple de code qui montre comment utiliser un autre package, ajoutez .Sample comme suffixe à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample.

    L’exemple de package a une dépendance envers le package d’origine. Lorsque vous créez l’exemple de package, ajoutez <IncludeAssets> avec la valeur contentFiles. Dans le dossier de contenu , disposez l’exemple de code dans un dossier appelé \Samples\<identifier>, tel que \Samples\Contoso.Utility.UsefulStuff.Sample.

Suivez ces meilleures pratiques pour définir la version du package :

  • En général, définissez la version du package pour qu’elle corresponde à la version du projet ou de l’assembly, bien que cela ne soit pas strictement obligatoire. Faire correspondre les version est simple lorsque vous avez des packages à assembly unique. NuGet traire lui-même les versions de package lors de la résolution des dépendances, mais pas les versions d’assembly.

  • Si vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de gestion de versions NuGet, comme expliqué dans Gestion des versions de package. NuGet est la plupart du temps conforme à la Gestion sémantique de version 2.0.0.

Remarque

Pour plus d’informations concernant la résolution des dépendances, consultez Résolution des dépendances avec PackageReference. Pour obtenir des informations qui peuvent vous aider à comprendre la gestions des versions, consultez cette série de billets de blog :

Si vous le souhaitez, renseignez le champ description

La description facultative du package s’affiche sous l’onglet LISEZMOI de la page nuget.org du package. La description extrait du <Description> dans le fichier projet ou du $description dans le fichier .nuspec.

L’exemple suivant montre un Description dans le fichier .csproj pour un package .NET :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

Exécuter la commande pack

Pour générer le package NuGet ou le fichier .nupkg, exécutez la commande dotnet pack depuis le dossier du projet, qui génère également le projet automatiquement.

dotnet pack

La sortie affiche le chemin d’accès au fichier .nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

Générer automatiquement le package à la création

Pour exécuter automatiquement dotnet pack chaque fois que vous exécutez dotnet build, ajoutez la ligne suivante à votre fichier projet dans la balise <PropertyGroup> :

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Remarque

Quand vous générez automatiquement le package, l’emballage augmente la durée de génération de votre projet.

Exécuter dotnet pack sur une solution compresse tous les projets de la solution qui peuvent être compressés. Autrement dit, cela concerne les projets possédant la propriété IsPackable dont la valeur est true.

Tester l’installation de package

Avant de publier un package, vous devriez tester l’installation de celui-ci dans un projet. Les tests permettent de s’assurer que les fichiers nécessaires se placent au bon endroit dans le projet.

Vous pouvez tester des installations manuellement dans Visual Studio ou à partir de la ligne de commande en suivant le processus d’installation normal du package.

Important

  • Vous ne pouvez pas modifier les packages une fois créés. Si vous corrigez un problème, modifiez le contenu du package et repackez-le.

  • Après avoir recréé le package, les nouvelles occurrences de tests utilisent toujours l’ancienne version du package jusqu’à ce que vous effaciez votre dossier de packages globaux. L’effacement du dossier est particulièrement important pour les packages qui n’utilisent pas d’étiquette de préversion unique à chaque version.

Étapes suivantes

Une fois le package créé, vous pouvez publier le fichier .nupkg sur l’hôte de votre choix.

Publier un package

Consultez les articles suivants présentent des moyens pour étendre les capacités de votre package ou prendre en charge d'autres scénarios :