Démarrage rapide : Créer et publier un package avec Visual Studio (.NET Framework, Windows)

  • Article

Grâce à 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 via un outil CLI NuGet.

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

Prérequis

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

    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 .NET est installée.

  • 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

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 Bibliothèque dans les listes déroulantes.

  3. Dans la liste des modèles de projet obtenue, sélectionnez Bibliothèque de classes (.NET Framework), puis sélectionnez Suivant.

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

  5. 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).

  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 le modèle de bibliothèque de classes suffit pour créer un package. Cependant, si vous souhaitez obtenir du code fonctionnel pour ce package, utilisez ce qui suit :

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

    Dans un vrai package NuGet, vous implémenterez bien sûr de nombreuses fonctionnalités utiles, grâce auxquelles d’autres personnes pourront créer des applications. Vous pouvez également définir des versions cibles de .Net Framework. Pour obtenir des exemples, consultez UWP et Xamarin.

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

Un package NuGet inclus un manifest (fichier .nuspec), 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 obtenues directement à partir 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 Projet > Propriétés, puis sélectionnez l’onglet Application.

  2. Dans Nom de l’assembly, donnez à votre package d’un identificateur unique. Si vous tentez de publier un package avec un nom qui existe déjà, une erreur se produira.

    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.

  3. Sélectionnez Informations sur l’assembly pour afficher une zone de dialogue dans laquelle vous pouvez entrer les autres propriétés à passer au manifeste (voir Jetons de remplacement). Les champs les plus couramment utilisés sont Titre, Description, Société, Copyright et Version de l’assembly. Comme ces propriétés apparaissent avec votre package sur un hôte comme nuget.org après que vous l'ayez publié, assurez-vous qu'elles sont entièrement descriptives.

    Screenshot showing the Assembly Information page in a .NET Framework project in Visual Studio.

  4. (Facultatif) Pour afficher et modifier les propriétés directement, ouvrez le fichier Properties/AssemblyInfo.cs dans le projet en sélectionnant Projet>Modifier le fichier projet.

  5. Une fois que vous avez défini ces propriétés, définissez la configuration de la solution active dans Générer>Gestionnaire de configuration pour Mettre en production et régénérer le projet afin de générer le DLL mis à jour.

Générer le manifeste initial

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

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

  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 s’ouvre dans le répertoire de votre projet, où se trouve le fichier AppLogger.csproj.

  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 les jetons de remplacement dans le manifeste.

  3. Ouvrez AppLogger.nuspec dans un éditeur de texte pour en examiner le contenu. Celui-ci 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. Autrement, si vous essayez de créer un package NuGet avec les valeurs par défaut dans votre fichier .nuspec, une erreur se produit. Pour plus d’informations sur ces propriétés, consultez les éléments de métadonnées facultatifs :

    • licenseUrl
    • projectUrl
    • releaseNotes
    • tags

  2. 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.

  3. À ce stade, vous pouvez également ajouter des éléments au manifeste, comme décrit dans Informations de référence sur le fichier .nuspec.

  4. Enregistrez le fichier avant de continuer.

Exécuter la commande pack

  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 : nuget pack.

    NuGet génère un fichier .nupkg au format identifier.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 sur nuget.org. Pour nuget.org, vous devez utiliser nuget.exe version 4.1.0 ou ultérieure.

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

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

  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 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 de package> par le nom de fichier de votre package et remplacez la valeur < de la clé API > par votre clé API. Le nom de fichier du package est une concaténation de l’ID de package et du numéro de version de celui-ci 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 Envoi NuGet.

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.

Étapes suivantes

Félicitations ! Vous avez créé un package NuGet à l’aide du Framework Visual Studio .NET. Passez à l’article suivant pour apprendre à créer un package NuGet à l’aide l’interface CLI NuGet.

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 :