Démarrage rapide : Créer et publier un package NuGet avec Visual Studio (.NET Standard, Windows uniquement)Quickstart: Create and publish a NuGet package using Visual Studio (.NET Standard, Windows only)

La création d’un package NuGet à partir d’une bibliothèque de classes .NET Standard dans Visual Studio sous Windows est un processus simple, de même que sa publication sur nuget.org avec un outil de ligne de commande (CLI).It's a simple process to create a NuGet package from a .NET Standard Class Library in Visual Studio on Windows, and then publish it to nuget.org using a CLI tool.

Notes

Si vous utilisez Visual Studio pour Mac, consultez ces informations sur la création d’un package NuGet ou utilisez les outils CLI dotnet.If you are using Visual Studio for Mac, refer to this information on creating a NuGet package, or use the dotnet CLI tools.

Configuration requisePrerequisites

  1. Installez une édition de Visual Studio 2019 à l’adresse visualstudio.com avec n’importe quelle charge de travail liée à .NET Core.Install any edition of Visual Studio 2019 from visualstudio.com with a .NET Core related workload.

  2. Si ce n'est déjà fait, installez l’interface CLI dotnet.If it's not already installed, install the dotnet CLI.

    Pour la CLI dotnet, à compter de Visual Studio 2017, la CLI dotnet est installée automatiquement avec les charges de travail associées à NET Core.For the dotnet CLI, starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. Dans le cas contraire, installez le SDK .NET Core pour obtenir la CLI dotnet.Otherwise, install the .NET Core SDK to get the dotnet CLI. La CLI dotnet dotnet est requise pour les projets .NET Standard qui utilisent le format de style SDK (attribut SDK).The dotnet CLI is required for .NET Standard projects that use the SDK-style format (SDK attribute). Le modèle de bibliothèque de classes .NET Standard par défaut dans Visual Studio 2017 et les versions ultérieures, qui est utilisé dans cet article, utilise l’attribut SDK.The default .NET Standard class library template in Visual Studio 2017 and higher, which is used in this article, uses the SDK attribute.

    Important

    Si vous utilisez un projet qui n’est pas de type SDK, suivez les procédures décrites dans Créer et publier un package .NET Framework (Visual Studio) pour créer et publier le package à la place.If you are working with a non-SDK-style project, follow the procedures in Create and publish a .NET Framework package (Visual Studio) to create and publish the package instead. Pour cet article, la CLI dotnet est recommandée.For this article, the dotnet CLI is recommended. Bien que vous puissiez publier un package NuGet à l’aide de la CLI nuget.exe, certaines des étapes décrites dans cet article sont spécifiques aux projets de type SDK et à la CLI dotnet.Although you can publish any NuGet package using the nuget.exe CLI, some of the steps in this article are specific to SDK-style projects and the dotnet CLI. La cLI nuget.exe est utilisée pour les projets qui ne sont pas de type SDK (généralement .NET Framework).The nuget.exe CLI is used for non-SDK-style projects (typically .NET Framework).

  3. Créez un compte gratuit sur nuget.org si vous n’avez pas encore de compte.Register for a free account on nuget.org if you don't have one already. La création d’un compte envoie un e-mail de confirmation.Creating a new account sends a confirmation email. Vous devez confirmer le compte avant de pouvoir charger un package.You must confirm the account before you can upload a package.

Créer un projet de bibliothèque de classesCreate a class library project

Vous pouvez utiliser un projet de bibliothèque de classes .NET Standard existant pour le code à empaqueter, ou bien en créer un de la façon suivante :You can use an existing .NET Standard Class Library project for the code you want to package, or create a simple one as follows:

  1. Dans Visual Studio, choisissez Fichier > Nouveau > Projet, développez le nœud Visual C# > .NET Standard, sélectionnez le modèle « Bibliothèque de classes (.NET Standard) », nommez le projet AppLogger, puis cliquez sur OK.In Visual Studio, choose File > New > Project, expand the Visual C# > .NET Standard node, select the "Class Library (.NET Standard)" template, name the project AppLogger, and click OK.

    Conseil

    Sauf cas particulier, .NET Standard est la cible privilégiée pour les packages NuGet, car c’est celle qui assure la compatibilité avec le plus grand nombre de projets.Unless you have a reason to choose otherwise, .NET Standard is the preferred target for NuGet packages, as it provides compatibility with the widest range of consuming projects.

  2. Cliquez avec le bouton droit sur le fichier projet résultant et sélectionnez Générer pour être sûr que le projet a été créé correctement.Right-click on the resulting project file and select Build to make sure the project was created properly. La DLL se trouve dans le dossier Debug (ou Release si vous générez cette configuration).The DLL is found within the Debug folder (or Release if you build that configuration instead).

Dans un package NuGet réel, vous implémenterez bien sûr de nombreuses fonctionnalités utiles, grâce auxquelles d’autres personnes pourront créer des applications.Within a real NuGet package, of course, you implement many useful features with which others can build applications. Pour cette procédure pas à pas, toutefois, vous n’écrirez pas de code supplémentaire, car une bibliothèque de classes à partir du modèle suffit pour créer un package.For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. Néanmoins, si vous souhaitez obtenir du code fonctionnel pour le package, utilisez ce qui suit :Still, if you'd like some functional code for the package, use the following:

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

Configurer les propriétés de packageConfigure package properties

  1. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions et choisissez la commande de menu Propriétés, puis sélectionnez l’onglet Package.Right-click the project in Solution Explorer, and choose Properties menu command, then select the Package tab.

    L’onglet Package s’affiche uniquement pour les projets de type SDK dans Visual Studio, généralement les projets de bibliothèque de classes .NET Standard ou .NET Core. Si vous ciblez un projet qui n’est pas de style SDK (généralement .NET Framework), migrez le projet ou consultez Créer et publier un package .NET Framework à la place des instructions pas à pas.The Package tab appears only for SDK-style projects in Visual Studio, typically .NET Standard or .NET Core class library projects; if you are targeting a non-SDK style project (typically .NET Framework), either migrate the project or see Create and publish a .NET Framework package instead for step-by-step instructions.

    Propriétés de package NuGet dans un projet Visual Studio

    Notes

    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.For packages built for public consumption, pay special attention to the Tags property, as tags help others find your package and understand what it does.

  2. Donnez à votre package un identificateur unique et remplissez les propriétés souhaitées.Give your package a unique identifier and fill out any other desired properties. Pour un mappage des propriétés MSBuild (projet de type SDK) aux propriétés d'un fichier .nuspec, voir Cibles de pack.For a mapping of MSBuild properties (SDK-style project) to properties in a .nuspec, see pack targets. Pour les descriptions des propriétés, voir la référence du fichier .nuspec .For descriptions of properties, see the .nuspec file reference. Toutes ces propriétés sont ajoutées au manifeste .nuspec créé par Visual Studio pour le projet.All of the properties here go into the .nuspec manifest that Visual Studio creates for the project.

    Important

    Vous devez donner au package un identificateur unique sur nuget.org ou sur l’hôte que vous utilisez.You must give the package an identifier that's unique across nuget.org or whatever host you're using. Dans le cadre de cette procédure pas à pas, nous vous recommandons d’inclure « Exemple » ou « Test » dans le nom, car l’étape de publication ultérieure rend le package visible publiquement (même s’il est peu probable que quelqu’un l’utilise vraiment).For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it).

    Si vous tentez de publier un package avec un nom qui existe déjà, une erreur se produira.If you attempt to publish a package with a name that already exists, you see an error.

  3. (Facultatif) Pour afficher les propriétés directement dans le fichier projet, cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions et sélectionnez Modifier AppLogger.csproj.(Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select Edit AppLogger.csproj.

    Cette option n’est disponible qu’à partir de Visual Studio 2017 pour les projets qui utilisent l’attribut de style SDK.This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. Sinon, cliquez avec le bouton droit sur le projet et choisissez Décharger le projet.Otherwise, right-click the project and choose Unload Project. Cliquez ensuite avec le bouton droit sur le projet déchargé, puis choisissez Modifier AppLogger.csproj.Then right-click the unloaded project and choose Edit AppLogger.csproj.

Exécuter la commande packRun the pack command

  1. Définissez la configuration en Release.Set the configuration to Release.

  2. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez la commande Empaqueter :Right click the project in Solution Explorer and select the Pack command:

    Commande pack de NuGet dans le menu contextuel du projet Visual Studio

    Si vous ne voyez pas la commande Pack, cela signifie que votre projet n’est probablement pas un projet de type SDK et que vous devez utiliser la CLI nuget.exe.If you don't see the Pack command, your project is probably not an SDK-style project and you need to use the nuget.exe CLI. Migrez le projet et utilisez la CLI dotnet, ou consultez Créer et publier un package .NET Framework à la place pour obtenir des instructions détaillées.Either migrate the project and use dotnet CLI, or see Create and publish a .NET Framework package instead for step-by-step instructions.

  3. Visual Studio génère le projet et crée le fichier .nupkg.Visual Studio builds the project and creates the .nupkg file. Lisez les informations qui apparaissent sur la fenêtre Sortie (comme dans la capture d’écran suivante), notamment le chemin d’accès du fichier de package.Examine the Output window for details (similar to the following), which contains the path to the package file. Notez également que l’assembly généré est dans bin\Release\netstandard2.0 comme il convient à la cible .NET Standard 2.0.Note also that the built assembly is in bin\Release\netstandard2.0 as befits the .NET Standard 2.0 target.

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
    1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.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 ==========
    

(Facultatif) Générer le package à la création(Optional) Generate package on build

Vous pouvez configurer Visual Studio pour générer automatiquement le package NuGet lorsque vous générez le projet.You can configure Visual Studio to automatically generate the NuGet package when you build the project.

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet et choisissez Propriétés.In Solution Explorer, right-click the project and choose Properties.

  2. Dans l’onglet Package, sélectionnez Générer le package NuGet à la création.In the Package tab, select Generate NuGet package on build.

    Générer automatiquement le package à la création

Notes

Lorsque vous créez automatiquement le package, le délai d’attente augmente la durée de création de votre projet.When you automatically generate the package, the time to pack increases the build time for your project.

(Facultatif) Compresser avec MSBuild(Optional) pack with 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 quand le projet contient les données de package nécessaires.As an alternate to using the Pack menu command, NuGet 4.x+ and MSBuild 15.1+ supports a pack target when the project contains the necessary package data. Ouvrez une invite de commandes, accédez au dossier de votre projet et exécutez la commande suivante.Open a command prompt, navigate to your project folder and run the following command. (Il est généralement recommandé de démarrer l’invite de commandes développeur pour Visual Studio à partir du menu Démarrer, car elle est configurée avec tous les chemins nécessaires pour MSBuild.)(You typically want to start the "Developer Command Prompt for Visual Studio" from the Start menu, as it will be configured with all the necessary paths for MSBuild.)

Pour plus d’informations, consultez Créer un package avec MSBuild.For more information, see Create a package using MSBuild.

Publier le packagePublish the package

Maintenant que vous disposez d’un fichier .nupkg, publiez-le sur nuget.org à l’aide de l’interface CLI nuget.exe ou dotnet.exe, avec une clé API acquise sur nuget.org.Once you have a .nupkg file, you publish it to nuget.org using either the nuget.exe CLI or the dotnet.exe CLI along with an API key acquired from nuget.org.

Notes

Analyse antivirus : tous les packages chargés sur nuget.org sont analysés et rejetés si des virus sont détectés.Virus scanning: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. Tous les packages répertoriés sur nuget.org sont aussi analysés régulièrement.All packages listed on nuget.org are also scanned periodically.

Les packages publiés sur nuget.org sont également visibles publiquement par d’autres développeurs, sauf si vous les retirez de la liste.Packages published to nuget.org are also publicly visible to other developers unless you unlist them. Pour héberger des packages en privé, consultez Hébergement de packages.To host packages privately, see Hosting packages.

Obtenir une clé APIAcquire your API key

  1. Connectez-vous à votre compte nuget.org ou créez un compte si vous ne l’avez pas déjà fait.Sign into your nuget.org account or create an account if you don't have one already.

    Pour plus d’informations sur la création de votre compte, consultez Comptes individuels.For more information on creating your account, see Individual accounts.

  2. Sélectionnez votre nom d’utilisateur (dans le coin supérieur droit), puis Clés API.Select your user name (on the upper right), then select API Keys.

  3. Sélectionnez Créer, donnez un nom à votre clé et sélectionnez Sélectionner les étendues > Envoyer (push) .Select Create, provide a name for your key, select Select Scopes > Push. Entrez * pour Modèle Glob, puis sélectionnez Créer.Enter * for Glob pattern, then select Create. (Consultez la suite pour plus d’informations sur les étendues.)(See below for more about scopes.)

  4. Une fois la clé créée, sélectionnez Copier pour récupérer la clé d’accès dont vous avez besoin dans l’interface CLI :Once the key is created, select Copy to retrieve the access key you need in the CLI:

    Copie de la clé d’API dans le Presse-papiers

  5. Important : Enregistrez votre clé dans un emplacement sécurisé car vous ne pourrez plus la recopier par la suite.Important: Save your key in a secure location because you cannot copy the key again later on. Si vous retournez sur la page de la clé API, vous devez régénérer la clé pour la copier.If you return to the API key page, you need to regenerate the key to copy it. Vous pouvez également supprimer la clé API si vous ne souhaitez plus distribuer des packages par le biais de l’interface CLI.You can also remove the API key if you no longer want to push packages via the CLI.

La définition d’étendue permet de créer des clés API distinctes selon les finalités.Scoping allows you to create separate API keys for different purposes. Chacune a son délai d’expiration et peut être restreinte à des packages (ou des modèles Glob) spécifiques.Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Chaque clé est également limitée à certaines opérations : transmission de nouveaux packages et de mises à jour, transmission de mises à jour uniquement ou retrait d’une liste.Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. 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, de sorte qu’elles disposent uniquement des autorisations dont elles ont besoin.Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. Pour plus d’informations, consultez Clés API délimitées.For more information, see scoped API keys.

Publier avec l’interface CLI dotnet ou nuget.exePublish with the dotnet CLI or nuget.exe CLI

Sélectionnez l'onglet de votre outil CLI, soit .NET Core CLI (CLI dotnet) ou NuGet (CLI nuget.exe).Select the tab for your CLI tool, either .NET Core CLI (dotnet CLI) or NuGet (nuget.exe CLI).

Cette étape est l’alternative recommandée à l’utilisation de nuget.exe.This step is the recommended alternative to using nuget.exe.

Avant de pouvoir publier le package, vous devez d’abord ouvrir une ligne de commande.Before you can publish the package, you must first open a command line.

  1. Accédez au dossier contenant le fichier .nupkg.Change to the folder containing the .nupkg file.

  2. Exécutez la commande suivante, en spécifiant le nom de votre package (ID de package unique) et en remplaçant la valeur de la clé par celle de votre clé API :Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key:

    dotnet nuget push AppLogger.1.0.0.nupkg -k qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -s https://api.nuget.org/v3/index.json
    
  3. dotnet affiche les résultats du processus de publication :dotnet displays the results of the publishing process:

    info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
    info :   PUT https://www.nuget.org/api/v2/package/
    info :   Created https://www.nuget.org/api/v2/package/ 12620ms
    info : Your package was pushed.
    

Voir dotnet nuget push.See dotnet nuget push.

Erreurs de publicationPublish errors

Les erreurs de la commande push signalent généralement le problème.Errors from the push command typically indicate the problem. Par exemple, vous avez peut-être oublié de mettre à jour le numéro de version de votre projet et, par conséquent, vous essayez de publier un package qui existe déjà.For example, you may have forgotten to update the version number in your project and are therefore trying to publish a package that already exists.

Des erreurs s’affichent également lorsque vous tentez de publier un package à l’aide d’un identificateur qui existe déjà sur l’hôte.You also see errors when trying to publish a package using an identifier that already exists on the host. Le nom « AppLogger », par exemple, existe déjà.The name "AppLogger", for example, already exists. Dans ce cas, la commande push génère l’erreur suivante :In such a case, the push command gives the following error:

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 utilisez une clé API valide que vous venez de créer, ce message indique un conflit d’affectation de nom, ce qui n’est pas évident dans la partie « autorisation » de l’erreur.If you're using a valid API key that you just created, then this message indicates a naming conflict, which isn't entirely clear from the "permission" part of the error. Modifiez l’identificateur de package, régénérez le projet, recréez le fichier .nupkg, puis réexécutez la commande push.Change the package identifier, rebuild the project, recreate the .nupkg file, and retry the push command.

Gérer le package publiéManage the published package

À partir de votre profil sur nuget.org, sélectionnez Manage Packages (Gérer les packages) pour voir celui que vous venez de publier.From your profile on nuget.org, select Manage Packages to see the one you just published. Vous recevrez aussi un e-mail de confirmation.You also receive a confirmation email. Notez que l’indexation de votre package et son apparition dans les résultats de la recherche peuvent prendre un certain temps.Note that it might take a while for your package to be indexed and appear in search results where others can find it. Pendant ce temps, la page de votre package contient le message ci-dessous :During that time your package page shows the message below:

This package has not been indexed yet. (Ce package n’a pas encore été indexé.)

Et voilà !And that's it! Vous venez de publier votre premier package NuGet sur nuget.org. D’autres développeurs peuvent maintenant l’utiliser dans leurs propres projets.You've just published your first NuGet package to nuget.org that other developers can use in their own projects.

Si, dans cette procédure pas à pas, vous avez créé un package qui n’est pas réellement utile (par exemple, un package créé avec une bibliothèque de classes vide), vous devez retirer de la liste le package pour le masquer dans les résultats de la recherche :If in this walkthrough you created a package that isn't actually useful (such as a package created with an empty class library), you should unlist the package to hide it from search results:

  1. Sur nuget.org, choisissez votre nom d’utilisateur (en haut à droite de la page), puis sélectionnez Gérer les packages.On nuget.org, select your user name (upper right of the page), then select Manage Packages.

  2. Recherchez le package que vous souhaitez retirer de la liste sous Publié puis sélectionnez l’icône Corbeille à droite :Locate the package you want to unlist under Published and select the trash can icon on the right:

    Icône Corbeille affichée pour un package répertorié sur nuget.org

  3. Sur la page suivante, désactivez la case Liste (nom du package) dans les résultats de la recherche puis sélectionnez Enregistrer :On the subsequent page, clear the box labeled List (package-name) in search results and select Save:

    Désactivation de la case à cocher Liste pour un package sur nuget.org

Ajout d’un fichier Lisez-moi et d’autres fichiersAdding a readme and other files

Pour spécifier directement les fichiers à inclure dans le package, modifiez le fichier projet et utilisez la propriété content :To directly specify files to include in the package, edit the project file and use the content property:

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

Cela inclut un fichier nommé readme.txt dans la racine du package.This will include a file named readme.txt in the package root. Visual Studio affiche le contenu de ce fichier sous forme de texte brut immédiatement après avoir installé le package directement.Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Les fichiers Lisez-moi ne s’affichent pas pour les packages installés en tant que dépendances).(Readme files are not displayed for packages installed as dependencies). Par exemple, voici comment s’affiche le fichier Lisez-moi du package HtmlAgilityPack :For example, here's how the readme for the HtmlAgilityPack package appears:

Affichage d’un fichier Lisez-moi pour un package NuGet lors de l’installation

Notes

Le simple ajout du fichier readme.txt à la racine du projet ne permet pas de l’ajouter dans le package résultant.Merely adding the readme.txt at the project root will not result in it being included in the resulting package.