Partager via

Démarrage rapide : Créer et publier un package NuGet avec Visual Studio (Windows uniquement)

  • Article

Grâce à Microsoft Visual Studio, vous pouvez créer un package NuGet à partir d’une bibliothèque de classes .NET, puis le publier sur nuget.org via un outil de ligne de commande (CLI).

Le guide de démarrage rapide concerne uniquement les utilisateurs Windows. Si vous utilisez Visual Studio pour Mac, consultez Créer un package NuGet à partir de projets de bibliothèque existants ou utilisez l’interface CLI .NET.

Prérequis

  • Installez Visual Studio 2022 pour Windows avec une charge de travail associée à .NET Core.

    Vous pouvez installer l’édition Community 2022 gratuitement à partir de visualstudio.microsoft.com, ou utiliser l’édition Professional ou Enterprise.

    Visual Studio 2017 et versions ultérieures intègrent automatiquement les fonctionnalités NuGet lorsqu’une charge de travail associée à .NET est installée.

  • Installez l’interface CLI .NET si ce n’est pas déjà fait.

    À partir de Visual Studio 2017, l’interface CLI .NET est installée automatiquement avec les charges de travail associées à NET Core. Dans le cas contraire, installez le kit SDK .NET Core pour obtenir l’interface CLI .NET. L’interface CLI .NET est requise pour les projets .NET qui utilisent le format de style SDK (attribut SDK). Le modèle de bibliothèque de classes .NET par défaut dans Visual Studio 2017, et versions ultérieures, utilise l’attribut SDK.

    Important

    Si vous utilisez un projet qui n’est pas de style SDK, suivez plutôt les procédures décrites dans Créer et publier un package .NET Framework (Visual Studio) pour créer et publier le package. Pour cet article, l’interface CLI .NET est recommandée. Bien que vous puissiez publier un package NuGet à l’aide de l’interface CLI NuGet, certaines des étapes décrites dans cet article sont spécifiques aux projets de type SDK et à l’interface CLI .NET. L’interface CLI NuGet est utilisée pour les projets qui ne sont pas de style SDK (généralement .NET Framework).

  • Créez un compte gratuit sur nuget.org si vous n’avez pas encore de compte. Vous devez créer et confirmer le compte avant de pouvoir charger un package NuGet.

  • Installez l’interface CLI NuGet en la téléchargeant sur nuget.org. Ajoutez le fichier nuget.exe dans un dossier approprié et ajoutez ce dossier à votre variable d’environnement PATH.

Créer un projet de bibliothèque de classes

Vous pouvez utiliser un projet de bibliothèque de classes .NET existant pour le code à empaqueter, ou bien en créer un de la façon suivante :

  1. Dans Visual Studio, sélectionnez Fichier>Nouveau>Projet.

  2. Dans la fenêtre Créer un nouveau projet, sélectionnez C#, Windows et Bibliothèque dans les listes déroulantes.

  3. Dans la liste des modèles de projet obtenue, sélectionnez Bibliothèque de classes (avec la description : Projet pour la création d’une bibliothèque de classes qui cible .NET ou .NET Standard), puis sélectionnez Suivant.

  4. Dans la fenêtre Configurer votre nouveau projet, saisissez AppLogger en tant que Nom de projet, puis sélectionnez Suivant.

  5. Dans la fenêtre Informations supplémentaires, sélectionnez un framework approprié, puis sélectionnez Créer.

    Si vous ne savez pas quel framework sélectionner, le dernier est un bon choix. Ce choix peut être facilement modifié ultérieurement. Pour obtenir des informations sur le framework à utiliser, consultez Quand cibler .NET 5.0 ou .NET 6.0 versus .NET Standard.

  6. Pour vous assurer que le projet a été correctement créé, sélectionnez Générer>Générer la solution. La DLL se trouve dans le dossier Debug (ou Release si vous générez cette configuration).

  7. (Facultatif) Pour ce guide de démarrage rapide, vous n’avez pas besoin d’écrire de code supplémentaire pour le package NuGet, car le modèle de bibliothèque de classes suffit pour créer un package. Cependant, si vous souhaitez obtenir du code fonctionnel pour le package, utilisez ce qui suit :

    namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}

Configurer les propriétés de package

Une fois que vous avez créé votre projet, vous pouvez configurer les propriétés du package NuGet en procédant comme suit :

  1. Sélectionnez votre projet dans Explorateur de solutions, puis sélectionnez Projet><nom du projet> Propriétés, où <nom du projet> est le nom de votre projet.

  2. Développez le nœud du Package , puis sélectionnez Général.

    Le nœud du Package s’affiche uniquement pour les projets de style kit SDK dans Visual Studio. Si vous ciblez un projet de style non SDK (généralement .NET Framework), faites migrer le projet ou consultez Créer et publier un package .NET Framework pour obtenir des instructions pas à pas.

    Screenshot showing NuGet package properties in a Visual Studio project.

  3. Dans le cas des packages destinés à une utilisation publique, faites particulièrement attention à la propriété Tags, car les balises aident les utilisateurs à trouver vos packages et à comprendre leur rôle.

  4. Donnez à votre package un ID de package unique et remplissez les propriétés souhaitées. Pour un tableau montrant comment les propriétés MSBuild (projet de type kit SDK) se mappe aux propriétés de fichier .nuspec, consultez cibles de pack. Pour les descriptions des propriétés de fichier .nuspec, voir la référence de fichier .nuspec. Toutes ces propriétés sont ajoutées au manifeste .nuspec créé par Visual Studio pour le projet.

    Important

    Vous devez donner au package un identificateur unique sur nuget.org ou sur l’hôte que vous utilisez. Sinon, une erreur se produit. Pour ce guide de démarrage rapide, nous vous recommandons d’inclure Exemple ou Test dans le nom, car l’étape de publication rend le package visible pour tous.

  5. (Facultatif) Pour afficher les propriétés directement dans le fichier projet AppLogger.csproj, sélectionnez Projet>Modifier le fichier projet.

    L’onglet AppLogger.csproj charge.

    Cette option est disponible à partir de Visual Studio 2017 pour les projets qui utilisent l’attribut de style SDK. Pour les versions antérieures de Visual Studio, vous devez sélectionner Projet>Décharger le projet avant de pouvoir modifier le fichier projet.

Exécuter la commande pack

Pour créer un package NuGet à partir de votre projet, procédez comme suit :

  1. Sélectionnez Générer>Gestionnaire de configuration, puis définissez la configuration de la solution active sur Mise en production.

  2. Sélectionnez le projet AppLogger dans Explorateur de solutions, puis sélectionnez Pack.

    Visual Studio génère le projet et crée le fichier .nupkg.

  3. Lisez les informations qui apparaissent dans la fenêtre Sortie pour obtenir plus de détails, notamment le chemin d’accès du fichier de package. Dans cet exemple, l’assembly généré se trouve dans bin\Release\net6.0 , car il correspond à une cible .NET 6.0 :

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  4. Si vous ne voyez pas la commande Pack dans ce menu, cela signifie que votre projet n’est probablement pas un projet de style kit SDK et que vous devez utiliser l’interface CLI NuGet. Migrez le projet et utilisez l’interface CLI .NET, ou consultez Créer et publier un package .NET Framework pour obtenir des instructions pas à pas.

(Facultatif) Générer le package à la création

Vous pouvez configurer Visual Studio pour générer automatiquement le package NuGet lorsque vous générez le projet :

  1. Sélectionnez votre projet dans Explorateur de solutions, puis sélectionnez Projet><nom du projet> Propriétés, où <nom du projet> est le nom de votre projet (AppLogger dans le cas présent).

  2. Développez le nœud du Package , sélectionnez Général, puis sélectionnez Générer un package NuGet à la création.

    Screenshot showing package properties with Generate NuGet package on build selected.

Remarque

Quand vous générez automatiquement le package, le délai d’attente supplémentaire lors de la compression augmente la durée totale de création de votre projet.

(Facultatif) Compresser avec MSBuild

En guise d’alternative à l’utilisation de la commande de menu Pack, NuGet 4.x+ et MSBuild 15.1+ prennent en charge une cible pack lorsque le projet contient les données de package nécessaires :

  1. Une fois votre projet ouvert dans Explorateur de solutions, ouvrez une invite de commandes en sélectionnant Outils>Ligne de commande>Invite de commande développeur.

    L’invite de commandes ouvre le répertoire du projet.

  2. Exécutez la commande suivante : msbuild -t:pack.

Pour plus d’informations, consultez Créer un package avec MSBuild.

Publier le package

Après avoir créé un fichier .nupkg, publiez-le sur nuget.org à l’aide de l’interface CLI .NET ou CLI NuGet, avec une clé API acquise sur nuget.org.

Remarque

  • Nuget.org analyse tous les packages chargés à la recherche de virus et rejette les packages s’il en trouve. Nuget.org analyse également régulièrement l’ensemble des packages déjà listés.

  • Les packages que vous publiez sur nuget.org sont également visibles publiquement par d’autres développeurs, sauf si vous les retirez de la liste. Pour héberger des packages en privé, consultez Héberger vos propres flux NuGet.

Obtenir une clé API

Avant de publier votre package NuGet, créez une clé API :

  1. Connectez-vous à votre compte nuget.org ou créez un compte si vous ne l’avez pas déjà fait.

  2. Sélectionnez votre nom d’utilisateur dans le coin supérieur droit, puis Clés API.

  3. Sélectionnez Créer et spécifiez un nom pour votre clé.

  4. Dans Sélectionner des étendues, sélectionnez Push.

  5. Dans Sélectionner des packages> Modèle glob, saisissez *.

  6. Sélectionnez Créer.

  7. Sélectionnez Copier pour copier la nouvelle clé.

    Screenshot that shows the new API key with the Copy link.

Important

  • Votre clé API doit rester secrète. La clé API est semblable à un mot de passe qui permet à toute personne de gérer des packages en votre nom. Supprimez ou régénérez votre clé API si elle est accidentellement divulguée.
  • Enregistrez votre clé dans un emplacement sécurisé car vous ne pourrez plus la copier par la suite. Si vous retournez sur la page de la clé API, vous devez régénérer la clé pour la copier. Vous pouvez également supprimer la clé API si vous ne souhaitez plus distribuer des packages.

La définition d’étendue permet de créer des clés API distinctes selon les finalités. Chacune a son délai d’expiration. Vous pouvez étendre une clé à des packages ou à des modèles glob spécifiques. Vous pouvez également étendre chaque clé à des opérations spécifiques : envoyer de nouveaux packages et versions de package, envoyer uniquement de nouvelles versions de package, ou retirer des package de la liste.

La définition d’étendue permet de créer des clés API pour les différentes personnes qui gèrent des packages dans votre organisation pour qu’elles ne disposent que des autorisations dont elles ont besoin.

Pour plus d’informations, consultez Clés API délimitées.

Publier avec l’interface CLI .NET ou CLI NuGet

Chacun des outils CLI suivants vous permet d’envoyer un package au serveur et de le publier. Sélectionnez l'onglet de votre outil CLI, soit la CLI .NET, soit la CLI NuGet.

L’utilisation de l’interface CLI .NET (dotnet.exe) est l’alternative recommandée à l’utilisation de l’interface CLI NuGet.

Dans le dossier contenant le fichier .nupkg, exécutez la commande suivante. Spécifiez le nom de votre fichier.nupkg et remplacez la valeur de clé par la clé API.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

La sortie affiche les résultats du processus de publication :

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Pour plus d’informations, consultez Envoi NuGet dotnet.

Remarque

Si vous souhaitez éviter que votre package de test soit actif sur nuget.org, vous pouvez l’envoyer au site de test nuget.org à l’adresse https://int.nugettest.org. Notez que les packages chargés dans int.nugettest.org peuvent ne pas être conservés.

Erreurs de publication

Les erreurs de la commande push signalent généralement le problème. Par exemple, vous avez peut-être oublié de mettre à jour le numéro de version de votre projet. Par conséquent, vous essayez de publier un package qui existe déjà.

Vous obtiendrez également des erreurs si votre clé API n’est pas valide ou a expiré, ou si vous essayez de publier un package à l’aide d’un identificateur qui existe déjà sur l’hôte. Supposons, par exemple, que l’identificateur AppLogger-test existe déjà sur nuget.org. Si vous essayez de publier un package avec cet identificateur, la commande push génère l’erreur suivante :

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Si vous obtenez cette erreur, vérifiez que vous utilisez une clé API valide qui n’a pas expiré. Si c’est le cas, l’erreur indique alors que l’identificateur du package existe déjà sur l’hôte. Pour corriger cette erreur, modifiez l’identificateur du package afin qu’il soit unique, régénérez le projet, recréez le fichier .nupkg, puis réexécutez la commande push.

Gérer le package publié

Une fois votre package publié avec succès, vous recevez un email de confirmation. Pour afficher le package que vous venez de publier, rendez-vous sur nuget.org, sélectionnez votre nom d’utilisateur en haut à droite, puis sélectionnez Gérer les packages.

Remarque

L’indexation de votre package et son apparition dans les résultats de la recherche peuvent prendre un certain temps. Pendant cette période, votre package apparaît sous la catégorie Packages non répertoriés et la page du package affiche le message suivant :

Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.

Vous venez de publier un package NuGet sur nuget.org. D’autres développeurs peuvent à présent l’utiliser dans leurs projets.

Si vous avez créé un package qui n’est pas utile (par exemple, ce package dont la bibliothèque de classes est vide) ou que vous décidez que vous ne souhaitez pas que le package soit visible, vous pouvez supprime de la liste le package pour qu’il n’apparaisse pas dans les résultats de la recherche :

  1. Une fois le package affiché sous Packages publiés dans la page Gérer les packages , sélectionnez l’icône en forme de crayon à côté de la description du package.

    Screenshot that shows the Edit icon for a package listing on nuget.org.

  2. Sur la page suivante, sélectionnez Liste, décochez la case à cocher Lister dans les résultats de la recherche. Enfin, sélectionnez Enregistrer.

    Screenshot that shows clearing the List checkbox for a package on nuget.org.

Le package apparaît désormais sous la catégorie Packages non répertoriés dans Gérer les packages et n’apparaît plus dans les résultats de la recherche.

Remarque

Pour éviter que votre package de test soit actif sur nuget.org, vous pouvez l’envoyer au site de test nuget.org à l’adresse https://int.nugettest.org. Notez que les packages chargés dans int.nugettest.org peuvent ne pas être conservés.

Ajouter un fichier Lisez-moi ou un autre fichier

Pour spécifier directement les fichiers à inclure dans le package, modifiez le fichier projet et ajoutez la propriété content :

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

Dans cet exemple, la propriété spécifie un fichier nommé readme.txt situé à la racine du projet. Visual Studio affiche le contenu de ce fichier sous forme de texte brut immédiatement après avoir installé le package. Les fichiers Lisez-moi ne s’affichent pas pour les packages installés en tant que dépendances. Par exemple, voici le fichier Lisez-moi du package HtmlAgilityPack :

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Remarque

Si vous ajoutez uniquement readme.txt à la racine du projet sans l’inclure dans la propriété content du fichier projet, il ne sera pas inclus dans le package.

Retrouvez d’autres vidéos à propos de NuGet sur Channel 9 et YouTube.

Félicitations ! Vous avez créé un package NuGet à l’aide d’une bibliothèque de classes Visual Studio .NET. Passez à l’article suivant pour apprendre à créer un package NuGet avec Visual Studio .NET Framework.

Créer un package à l’aide de l’interface CLI NuGet

Pour explorer plus en détail ce que NuGet propose, consultez les articles suivants :