Partager via

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

Les packages NuGet contiennent du code que les développeurs peuvent réutiliser dans leurs projets. Quel que soit votre code ou contenu, vous utilisez un outil en ligne de commande, soit nuget.exedotnet.exepour créer le package NuGet.

Cet article explique comment créer un package à l’aide de l’interface CLI dotnet. À compter de Visual Studio 2017, l’interface CLI dotnet est incluse avec toutes 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 rubrique s’applique uniquement à .NET et à d’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 obtenir des didacticiels 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 au pack dotnet. Pour plus d’informations sur la création d’un package avec MSBuild, consultez Créer un package NuGet à l’aide de MSBuild.

Note

Définir des propriétés

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

  • PackageId, l’identificateur du package doit être unique entre nuget.org et 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 ce n’est pas spécifié, la valeur par défaut est la AssemblyName.
  • Company est des informations sur l’entreprise. Si elle n’est pas spécifiée, la valeur par défaut est la Authors valeur.
  • Product est des informations sur le produit. Si ce n’est pas spécifié, 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 les propriétés directement au fichier .csproj ou à d’autres fichiers 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.

Note

Pour les paquets que vous créez pour une utilisation publique, portez une attention particulière à la propriété PackageTags. Les balises aident d’autres personnes à trouver votre package et à comprendre ce qu’il fait.

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

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 du package et le numéro de version identifient de manière unique le code exact contenu dans le package.

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

  • L’identificateur doit être unique entre nuget.org et tous les autres emplacements qui hébergent le package. Pour éviter les conflits, un bon modèle consiste à utiliser le nom de votre entreprise comme première partie de l’identificateur.

  • Suivez une convention d’affectation de noms de type .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 utilisateurs si vous associez l'identificateur de 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 à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample.

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

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

  • En règle générale, définissez la version du package pour qu’elle corresponde à la version du projet ou de l’assembly, bien qu’elle ne soit pas strictement requise. La mise en correspondance de la version est simple lorsque vous limitez un package à un seul assembly. NuGet lui-même traite des versions de package lors de la résolution des dépendances, et non des versions d’assembly.

  • Si vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de contrôle de version NuGet , comme expliqué dans le contrôle de version du package. NuGet est principalement conforme à la version sémantique 2.0.0.

Note

Pour plus d’informations sur la résolution des dépendances, consultez Résolution des dépendances avec PackageReference. Pour plus d’informations qui peuvent vous aider à comprendre le contrôle de version, consultez cette série de billets de blog :

Ajouter un champ de description facultatif

La description facultative du package s’affiche sous l’onglet README de la page nuget.org du package. La description provient du <Description> fichier de projet ou du $descriptionfichier .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 à partir du 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 un package sur la build

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

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Note

Lorsque vous générez automatiquement le package, l’empaquetage augmente le temps de génération de votre projet.

Exécuter dotnet pack sur une solution emballe tous les projets de la solution qui peuvent être emballés, c'est-à-dire, ceux qui ont la propriété IsPackable définie sur la valeur true.

Installation du package de test

Avant de publier un package, vous devez tester l’installation du package dans un projet. Le test garantit que les fichiers nécessaires se retrouvent dans leurs emplacements corrects dans le projet.

Testez l’installation manuellement dans Visual Studio ou sur la ligne de commande à l’aide du 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.

  • Après avoir recréé le package, les nouveaux tests continuent d'utiliser 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 sur chaque build.

É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 pour savoir comment étendre les fonctionnalités de votre package ou prendre en charge d’autres scénarios :

  • Last updated on