Démarrage rapide : Créer et publier un package à l’aide de l’interface CLI dotnet
Ce guide de démarrage rapide vous montre comment créer rapidement un package NuGet à partir d’une bibliothèque de classes .NET et le publier sur nuget.org à l’aide de l’interface de ligne de commande .NET ou de l’interface CLI dotnet.
Prérequis
Le Kit de développement logiciel (SDK) .NET, qui fournit l’outil en ligne de commande dotnet. À partir de Visual Studio 2017, l’interface CLI dotnet est installée automatiquement avec les charges de travail associées à .NET ou .NET Core.
Un compte gratuit sur nuget.org. Suivez les instructions décrite dans Ajouter un nouveau compte individuel.
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 créer un projet de la façon suivante :
- Créez un dossier nommé AppLogger.
- Ouvrez une invite de commandes et basculez vers le dossier AppLogger. Toutes les commandes d’interface CLI dotnet de ce guide de démarrage rapide s’exécutent sur le dossier actif par défaut.
- Saisissez
dotnet new classlib. Cela crée un projet avec le nom du dossier actuel.
Pour plus d’informations, consultez dotnet new.
Ajouter des métadonnées de package au fichier projet
Chaque package NuGet a un manifeste décrivant son contenu et ses dépendances. Dans le package final, il s’agit d’un fichier .nuspec généré à partir des propriétés de métadonnées NuGet incluses dans le fichier projet.
Ouvrez le fichier projet .csproj, .fsproj ou .vbproj, puis ajoutez les propriétés suivantes à l’intérieur de la balise existante <PropertyGroup>. Utilisez vos propres valeurs pour le nom et la société, et remplacez l’identificateur de package par une valeur unique.
<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>
Important
L’identificateur doit être unique sur nuget.org ainsi que sur toutes les sources de package. La publication rend le package publiquement visible. Par conséquent, si vous utilisez l’exemple de bibliothèque AppLogger ou une autre bibliothèque de test, utilisez un nom unique qui inclut Sample ou Test.
Ajoutez si vous le souhaitez certaines des propriétés facultatives décrites dans Propriétés de métadonnées NuGet.
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.
Exécuter la commande pack
Pour générer un package NuGet ou un fichier .nupkg à partir du projet, exécutez la commande dotnet pack, ce 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 C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.
Générer automatiquement le package à la création
Pour exécuter automatiquement dotnet pack lorsque vous exécutez dotnet build, ajoutez la ligne suivante à votre fichier projet au sein de <PropertyGroup> :
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
Publier le package
Publiez votre fichier .nupkg sur nuget.org à l’aide de la commande dotnet nuget push avec une clé API obtenue à partir de 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 votre clé API
Connectez-vous à votre compte nuget.org ou créez un compte si vous ne l’avez pas déjà fait.
Sélectionnez votre nom d’utilisateur dans le coin supérieur droit, puis Clés API.
Sélectionnez Créer et spécifiez un nom pour votre clé.
Dans Sélectionner des étendues, sélectionnez Push.
Dans Sélectionner des packages> Modèle glob, saisissez *.
Sélectionnez Créer.
Sélectionnez Copier pour copier la nouvelle clé.
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 dotnet nuget push
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 :
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 :
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.
Sur la page suivante, sélectionnez Liste, décochez la case à cocher Lister dans les résultats de la recherche. Enfin, sélectionnez Enregistrer.
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.
Félicitations pour la création et la publication de votre premier package NuGet !
Vidéo connexe
Retrouvez d’autres vidéos à propos de NuGet sur Channel 9 et YouTube.
Étapes suivantes
Pour en savoir plus sur la création de packages avec l’interface CLI dotnet :
Obtenez plus d’informations sur la création et la publication de packages NuGet :