Démarrage rapide : Créer et publier un package à l’aide de Visual Studio (.NET Framework, Windows)

Avec Microsoft Visual Studio, vous pouvez créer un package NuGet à partir d’une bibliothèque de classes .NET Framework, puis le publier sur nuget.org à l’aide de l’outil CLI NuGet.

Le guide de démarrage rapide concerne uniquement les utilisateurs Windows. Si vous utilisez Visual Studio pour Mac, consultez plutôt les outils dotnet CLI.

Prerequisites

• Installez Visual Studio 2022 pour Windows avec n’importe quelle charge de travail liée à .NET.

  Vous pouvez installer gratuitement l’édition Community 2022 de visualstudio.microsoft.com, ou utiliser l’édition Professionnel ou Entreprise.

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

• Inscrivez-vous pour un compte gratuit sur nuget.org si vous n’en avez pas déjà un. Vous devez inscrire et confirmer le compte avant de pouvoir charger un package NuGet.

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

Créer un projet de bibliothèque de classes

Pour créer un projet de bibliothèque de classes, procédez comme suit :

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

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

3. Dans la liste résultante des modèles de projet, sélectionnez Class Library (.NET Framework), puis sélectionnez Next.

4. Dans la fenêtre Configurez votre nouvelle fenêtre project, entrez AppLogger pour le nom Project, puis sélectionnez Create.

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

6. (Facultatif) Pour ce guide de démarrage rapide, vous n’avez pas besoin d’écrire de code supplémentaire pour le package NuGet, car la bibliothèque de classes de modèle est suffisante pour créer un package. Toutefois, si vous souhaitez obtenir du code fonctionnel pour cet exemple de package, incluez le code suivant :

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

   Dans un package NuGet réel, vous allez probablement implémenter de nombreuses fonctionnalités utiles avec lesquelles d’autres peuvent créer des applications. Vous pouvez également définir les frameworks cibles. Pour obtenir un exemple, consultez UWP.

Configurer les propriétés du projet pour le package

Un package NuGet inclut un manifeste (un .nuspec fichier), qui contient des métadonnées pertinentes telles que l’identificateur du package, le numéro de version, la description, etc. Certaines de ces métadonnées peuvent être extraites directement des propriétés du projet, ce qui évite d’avoir à les mettre à jour séparément dans le projet et le manifeste. Les étapes suivantes décrivent comment définir les propriétés applicables :

1. Sélectionnez Project > Propriétés, puis sélectionnez l’onglet Application.

2. Pour le nom de l’assembly, donnez à votre package un identificateur unique. Si vous tentez de publier un package avec un nom qui existe déjà, une erreur s’affiche.

   Important

   Vous devez donner au package un identificateur unique entre nuget.org ou l’hôte que vous utilisez. Dans le cas contraire, une erreur se produit. Pour ce guide de démarrage rapide, nous vous recommandons d’inclure l’exemple ou le test dans le nom, car l’étape de publication rend le package publiquement visible.

3. Sélectionnez Informations sur l’assembly, qui affiche une boîte de dialogue dans laquelle vous pouvez entrer d’autres propriétés qui sont contenues dans le manifeste (voir Jetons de remplacement). Les champs les plus couramment utilisés sont Title, Description, Company, Copyright et Assembly version. Étant donné que ces propriétés apparaissent avec votre package sur un hôte comme nuget.org après sa publication, assurez-vous qu’elles sont entièrement descriptives.

   

4. (Facultatif) Pour afficher et modifier les propriétés directement, ouvrez le fichier Properties/AssemblyInfo.cs dans le project en sélectionnant Project>Edit Project Fichier.

5. Une fois que vous avez défini ces propriétés, définissez la configuration de la solution Active dans Build>Configuration Manager sur Release et régénérez le projet pour générer la DLL mise à jour.

Générer le manifeste initial

Une fois que vous avez défini les propriétés du projet et créé la DLL, vous pouvez maintenant générer un fichier .nuspec initial à partir du projet. Cette étape inclut les jetons de remplacement appropriés pour extraire des informations à partir du fichier de projet.

Exécutez nuget spec une seule fois pour générer le manifeste initial. Si vous mettez à jour le package, modifiez les valeurs de votre projet ou modifiez le manifeste directement :

1. Une fois votre projet ouvert dans Solution Explorer, ouvrez une invite de commandes en sélectionnant Tools>Command Line>Developer Command Prompt.

   L’invite de commandes s’ouvre dans le répertoire de votre projet où se trouve le AppLogger.csproj fichier.

2. Exécutez la commande suivante : nuget spec AppLogger.csproj.

   NuGet crée un manifeste qui correspond au nom du projet, dans ce cas AppLogger.nuspec. Il inclut également des jetons de remplacement dans le manifeste.

3. Ouvrez AppLogger.nuspec dans un éditeur de texte pour examiner son contenu, qui sera similaire au code suivant :

   <?xml version="1.0"?>
   <package >
     <metadata>
       <id>Package</id>
       <version>1.0.0</version>
       <authors>Your username</authors>
       <owners>Your username</owners>
       <license type="expression">MIT</license>
       <!-- <icon>icon.png</icon> -->
       <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
       <requireLicenseAcceptance>false</requireLicenseAcceptance>
       <description>Package description</description>
       <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
       <copyright>Copyright 2022</copyright>
       <tags>Tag1 Tag2</tags>
     </metadata>
   </package>
   

Modifier le manifeste

1. Modifiez les propriétés suivantes avant de continuer. Sinon, si vous essayez de créer un package NuGet avec les valeurs par défaut dans votre .nuspec fichier, une erreur se produit. Pour plus d’informations sur ces propriétés, consultez les éléments de métadonnées facultatifs :

   • URL de licence
   • projectUrl
   • releaseNotes
   • tags

2. Pour les packages créés pour la consommation publique, portez une attention particulière à la propriété Tags , car les balises aident d’autres personnes à trouver votre package et à comprendre ce qu’il fait.

3. Vous pouvez également ajouter tous les autres éléments au manifeste pour l’instant, comme décrit dans la référence du fichier .nuspec.

4. Enregistrez le fichier avant de continuer.

Exécuter la commande pack

1. Une fois votre projet ouvert dans Solution Explorer, ouvrez une invite de commandes en sélectionnant Tools>Command Line>Developer Command Prompt.

   L’invite de commandes s’ouvre dans le répertoire de votre projet.

2. Exécutez la commande suivante : nuget pack.

   NuGet génère un fichier .nupkg sous la forme d’identificateur.version.nupkg dans le dossier actif.

Publier le package

Une fois que vous avez créé un fichier .nupkg , publiez-le sur nuget.org à l’aide de l’interface CLI NuGet avec une clé API acquise à partir de nuget.org. Pour nuget.org, vous devez utiliser nuget.exe la version 4.1.0 ou ultérieure.

Si vous souhaitez tester et valider votre package avant de le publier dans une galerie publique, vous pouvez le charger dans un environnement de test comme int.nugettest.org au lieu de nuget.org. Notez que les packages chargés dans int.nugettest.org peuvent ne pas être conservés.

Acquérir 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é.

   

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 l’interface CLI NuGet

L’utilisation de l’interface CLI NuGet (nuget.exe) est une alternative à l’utilisation de l’interface CLI .NET :

1. Ouvrez une invite de commandes et accédez au dossier contenant le fichier .nupkg .

2. Exécutez la commande suivante : Remplacez le nom de fichier< par le nom de fichier de votre package et remplacez ><la valeur> de clé API par votre clé API. Le nom de fichier du package est une concaténation de votre ID de package et du numéro de version avec une extension .nupkg . Par exemple, AppLogger.1.0.0.nupkg :

   nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json
   

   Le résultat du processus de publication s’affiche comme suit :

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

Pour plus d’informations, consultez 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.

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.

   

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

   

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.

Étapes suivantes

Félicitations pour la création d’un package NuGet à l’aide de l’infrastructure Visual Studio .NET. Passez à l’article suivant pour apprendre à créer un package NuGet avec l’interface CLI NuGet.

Pour en savoir plus sur l’offre de NuGet, consultez les articles suivants :

• Publier un package
• Générer un package de préversion
• Prendre en charge plusieurs frameworks cibles
• Contrôle de version du package
• Création d’un package localisé