Démarrage rapide : Créer et publier un package avec 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 dotnet CLI.

Prerequisites

  • Kit de développement logiciel (SDK) .NET, qui fournit l’outil en ligne de commande dotnet. À compter de Visual Studio 2017, l’interface CLI dotnet s’installe automatiquement avec des charges de travail .NET ou .NET Core associées.

  • Un compte gratuit sur nuget.org. Suivez les instructions à l’adresse 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 que vous souhaitez empaqueter ou créer un projet simple comme suit :

  1. Créez un dossier nommé AppLogger.
  2. Ouvrez une invite de commandes et basculez vers le dossier AppLogger . Toutes les commandes cli dotnet de ce guide de démarrage rapide s’exécutent sur le dossier actif par défaut.
  3. Entrez dotnet new classlib, qui 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 qui décrit le contenu et les dépendances du package. Dans le package final, le manifeste est un fichier .nuspec , qui utilise les propriétés de métadonnées NuGet que vous incluez 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é, puis 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 de package doit être unique entre nuget.org et d’autres sources de package. La publication rend le package publiquement visible. Par conséquent, si vous utilisez l’exemple de bibliothèque AppLogger ou d’une autre bibliothèque de test, utilisez un nom unique qui inclut Sample ou Test.

Vous pouvez ajouter toutes les propriétés facultatives décrites dans les propriétés de métadonnées NuGet.

Remarque

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.

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 , 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 un package sur la build

Pour exécuter automatiquement dotnet pack chaque fois que vous exécutez dotnet build, ajoutez la ligne suivante à votre fichier projet dans <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 que vous obtenez à partir de nuget.org.

Remarque

  • Nuget.org analyse tous les packages chargés pour détecter les virus et rejette tous les packages contenant des virus. Nuget.org analyse également régulièrement tous les packages répertoriés existants.

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

Obtenir votre clé API

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

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

  3. Sélectionnez Créer, puis entrez un nom pour votre clé.

  4. Sous Sélectionner des périmètres, sélectionnez Push.

  5. Sous Sélectionner des packages, pour modèle Glob, entrez un astérisque (*).

  6. Cliquez sur Créer.

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

    Capture d’écran d’une page nuget.org montrant la nouvelle clé API, un message sur la copie de la clé maintenant et le bouton Copier, qui est mis en surbrillance.

Important

  • Conservez toujours votre clé API comme secret. La clé API est semblable à un mot de passe que tout le monde peut utiliser pour gérer des packages en votre nom. Supprimez ou régénérez votre clé API si elle est accidentellement révélée.
  • Enregistrez votre clé dans un emplacement sécurisé, car vous ne pouvez pas copier la clé ultérieurement. Si vous revenez à la page de 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 envoyer de packages.

Délimitation permet de créer des clés API distinctes à des fins différentes. Chaque clé a un délai d’expiration et vous pouvez limiter la clé à des packages ou des modèles glob spécifiques. Vous devez également étendre chaque clé à des opérations spécifiques : envoyer (push) de nouveaux packages et versions de package, envoyer (push) uniquement de nouvelles versions de package ou annuler la liste.

Grâce à la définition de périmètre, vous pouvez créer des clés API pour différentes personnes qui gèrent des packages pour votre organisation afin qu’elles aient uniquement les autorisations dont elles ont besoin.

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

Publier avec dotnet nuget push

Dans le dossier qui contient le fichier .nupkg , exécutez la commande suivante. Remplacez <package-file> par le nom de votre fichier .nupkg , puis remplacez <API-key> par votre clé API.

dotnet nuget push <package-file> --api-key <API-key> --source https://api.nuget.org/v3/index.json

Les résultats affichent les résultats du processus de publication :

Pushing <package-file> to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
  Created https://www.nuget.org/api/v2/package/ 2891ms
Your package was pushed.

Pour plus d’informations, consultez dotnet nuget push.

Erreurs de publication

Lorsque vous exécutez la push commande, vous rencontrez parfois une erreur. Par exemple, vous pouvez obtenir une erreur dans les situations suivantes :

  • Votre clé API n’est pas valide ou a expiré.
  • Vous essayez de publier un package qui a un identificateur qui existe déjà sur l’hôte.
  • Vous apportez des modifications à un package publié, mais vous oubliez de mettre à jour le numéro de version avant de réessayer de le publier.

Le message d’erreur indique généralement la source du problème.

Par exemple, supposons que l’identificateur Contoso.App.Logger.Test existe sur nuget.org. Si vous essayez de publier un package avec cet identificateur, vous obtenez 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.).

Pour résoudre ce problème, vérifiez l’étendue, la date d’expiration et la valeur de votre clé API. Si la clé est valide, l’erreur indique que l’identificateur du package existe déjà sur l’hôte. Pour résoudre le problème, modifiez l’identificateur du package de façon à ce qu’il soit unique, régénérez le projet, recréez le fichier .nupkg et réessayez la push commande.

Gérer le package publié

Une fois votre package publié, vous recevez un e-mail de confirmation. Pour afficher le package publié, accédez à nuget.org, sélectionnez votre nom d’utilisateur dans le coin supérieur droit, puis sélectionnez Gérer les packages.

Remarque

L’indexation de votre package peut prendre un certain temps et s’afficher dans les résultats de recherche où d’autres personnes peuvent la trouver. Pendant cette période, votre package apparaît sous Packages non répertoriés et la page du package affiche le message suivant :

Capture d’écran d’un message d’avertissement nuget.org sur le package qui n’est pas encore publié. Le texte indique que la validation et l’indexation peuvent prendre une heure.

Maintenant que votre package NuGet est publié à nuget.org, d’autres développeurs peuvent l’utiliser dans leurs projets.

Si vous créez un package qui n’est pas utile (par exemple, cet exemple de package à partir d’une bibliothèque de classes vide) ou si vous ne souhaitez pas que le package soit visible, vous pouvez annuler la liste du package pour le masquer 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 de crayon en regard de la description du package.

    Capture d’écran de la page packages nuget.org. La section Packages publiés répertorie un package. Son icône de modification est mise en surbrillance.

  2. Dans la page suivante, sélectionnez Listing, décochez la case Liste dans les résultats de recherche, puis sélectionnez Enregistrer.

    Capture d’écran d’une page nuget.org. Dans la section Liste, l’option permettant de répertorier le package dans les résultats de recherche est mise en surbrillance.

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

Remarque

Pour éviter que votre package de test soit actif sur nuget.org, vous pouvez envoyer (push) 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 !

Trouvez d’autres vidéos NuGet sur Channel 9 et YouTube.

Étapes suivantes

Consultez plus d’informations sur la création de packages avec l’interface CLI dotnet :

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

Obtenez plus d’informations sur la création et la publication de packages NuGet :

  • Last updated on