Création de packages NuGetCreating NuGet packages

Quel que soit la fonction de votre package ou le code qu’il contient, vous utilisez l’un des outils CLI, nuget.exe ou dotnet.exe, pour empaqueter cette fonctionnalité dans un composant qui peut être partagé et utilisé avec d’autres développeurs.No matter what your package does or what code it contains, you use one of the CLI tools, either nuget.exe or dotnet.exe, to package that functionality into a component that can be shared with and used by any number of other developers. Pour installer les outils CLI NuGet, consultez Installer les outils clients NuGet.To install NuGet CLI tools, see Install NuGet client tools. Notez que Visual Studio n’inclut pas automatiquement d’outil CLI.Note that Visual Studio does not automatically include a CLI tool.

Techniquement parlant, un package NuGet n’est qu’un fichier ZIP renommé avec l’extension .nupkg et dont le contenu correspond à certaines conventions.Technically speaking, a NuGet package is just a ZIP file that's been renamed with the .nupkg extension and whose contents match certain conventions. Cette rubrique décrit le processus détaillé de création d’un package qui répond à ces conventions.This topic describes the detailed process of creating a package that meets those conventions. Pour consulter une procédure pas à pas ciblée, reportez-vous à Démarrage rapide : créer et publier un package.For a focused walkthrough, refer to Quickstart: create and publish a package.

L’empaquetage commence par le code compilé (assemblys), les symboles et/ou d’autres fichiers à remettre sous forme de package (consultez Vue d’ensemble et flux de travail).Packaging begins with the compiled code (assemblies), symbols, and/or other files that you want to deliver as a package (see Overview and workflow). Ce processus est indépendant de la compilation ou de la génération des fichiers destinés au package, même si vous pouvez tirer des informations contenues dans un fichier projet pour maintenir synchronisés les assemblys et packages compilés.This process is independent from compiling or otherwise generating the files that go into the package, although you can draw from information in a project file to keep the compiled assemblies and packages in sync.

Notes

Cette rubrique concerne les projets qui ne sont pas de style SDK, en général les projets autres que .NET Core et .NET Standard utilisant Visual Studio 2017 et NuGet 4.0+.This topic applies to non-SDK-style projects, typically projects other than .NET Core and .NET Standard projects using Visual Studio 2017 and NuGet 4.0+.

Déterminer quels assemblys empaqueterDeciding which assemblies to package

La plupart des packages à usage général contiennent un ou plusieurs assemblys que d’autres développeurs peuvent utiliser dans leurs propres projets.Most general-purpose packages contain one or more assemblies that other developers can use in their own projects.

  • En règle générale, il est préférable d’avoir un seul assembly par package NuGet, à condition que chaque assembly soit indépendamment utile.In general, it's best to have one assembly per NuGet package, provided that each assembly is independently useful. Par exemple, si vous avez un Utilities.dll qui dépend de Parser.dll, et que Parser.dll est utile tout seul, créez un seul package pour chacun.For example, if you have a Utilities.dll that depends on Parser.dll, and Parser.dll is useful on its own, then create one package for each. Ainsi, les développeurs peuvent utiliser Parser.dll indépendamment de Utilities.dll.Doing so allows developers to use Parser.dll independently of Utilities.dll.

  • Si votre bibliothèque se compose de plusieurs assemblys qui ne sont pas indépendamment utiles, alors il est possible de les combiner en un seul package.If your library is composed of multiple assemblies that aren't independently useful, then it's fine to combine them into one package. À l’aide de l’exemple précédent, si Parser.dll contient du code utilisé uniquement par Utilities.dll, alors il est possible de conserver Parser.dll dans le même package.Using the previous example, if Parser.dll contains code that's used only by Utilities.dll, then it's fine to keep Parser.dll in the same package.

  • De même, si Utilities.dll dépend de Utilities.resources.dll, et que ce dernier n’est pas utile tout seul, alors placez les deux dans le même package.Similarly, if Utilities.dll depends on Utilities.resources.dll, where again the latter is not useful on its own, then put both in the same package.

En réalité, les ressources correspondent à un cas spécial.Resources are, in fact, a special case. Lorsqu’un package est installé dans un projet, NuGet ajoute automatiquement des références d’assembly aux DLL du package, à l’exclusion de celles nommées .resources.dll, car elles sont supposées être des assemblys satellites localisés (consultez Création de packages localisés).When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies (see Creating localized packages). C’est pourquoi vous devez éviter d’utiliser .resources.dll pour les fichiers qui contiennent du code de package essentiel.For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

Si votre bibliothèque contient des assemblys COM Interop, suivez les instructions supplémentaires données dans Création de packages avec des assemblys COM Interop.If your library contains COM interop assemblies, follow additional the guidelines in Authoring packages with COM interop assemblies.

Rôle et structure du fichier .nuspecThe role and structure of the .nuspec file

Une fois que vous savez quels fichiers vous voulez empaqueter, l’étape suivante consiste à créer un manifeste de package dans un fichier XML .nuspec.Once you know what files you want to package, the next step is creating a package manifest in a .nuspec XML file.

Le manifeste :The manifest:

  1. Décrit le contenu du package et est lui-même inclus dans le package.Describes the package's contents and is itself included in the package.
  2. Dirige la création du package et indique à NuGet comment installer le package dans un projet.Drives both the creation of the package and instructs NuGet on how to install the package into a project. Par exemple, le manifeste identifie les autres dépendances de package pour que NuGet puisse également les installer lorsque le package principal est installé.For example, the manifest identifies other package dependencies such that NuGet can also install those dependencies when the main package is installed.
  3. Contient des propriétés à la fois obligatoires et facultatives comme décrit ci-dessous.Contains both required and optional properties as described below. Pour plus de précision, notamment sur les autres propriétés non mentionnées ici, consultez les Informations de référence sur le fichier .nuspec.For exact details, including other properties not mentioned here, see the .nuspec reference.

Propriétés obligatoires :Required properties:

  • Identificateur du package, qui doit être unique dans toute la galerie qui héberge le package.The package identifier, which must be unique across the gallery that hosts the package.
  • Numéro de version spécifique au format version_principale.version_secondaire.version_corrective [-suffixe]-suffixe identifie les préversions.A specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions
  • Titre du package tel qu’il doit apparaître sur l’hôte (par exemple nuget.org)The package title as it should appear on the host (like nuget.org)
  • Informations sur l’auteur et le propriétaire.Author and owner information.
  • Longue description du package.A long description of the package.

Propriétés facultatives communes :Common optional properties:

  • Notes de publicationRelease notes
  • Informations de copyrightCopyright information
  • Brève description de l’interface utilisateur du gestionnaire de package dans Visual StudioA short description for the Package Manager UI in Visual Studio
  • ID de paramètres régionauxA locale ID
  • URL du projetProject URL
  • Licence comme expression ou fichier (licenseUrl est en cours de dépréciation, utilisez l’élément de métadonnées nuspec license )License as an expression or file (licenseUrl is being deprecated, use the license nuspec metadata element)
  • URL de l’icôneAn icon URL
  • Listes des dépendances et référencesLists of dependencies and references
  • Balises facilitant les recherches dans la galerieTags that assist in gallery searches

Voici un fichier .nuspec classique (mais fictif), avec des commentaires décrivant les propriétés :The following is a typical (but fictitious) .nuspec file, with comments describing the properties:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- The identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- The package version number that is used when resolving dependencies -->
        <version>1.8.3-beta</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- The icon is used in Visual Studio's package manager UI -->
        <iconUrl>http://github.com/contoso/UsefulStuff/nuget_icon.png</iconUrl>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
    </files>
</package>

Pour plus d’informations sur la déclaration des dépendances et la spécification des numéros de version, consultez Gestion des versions de package.For details on declaring dependencies and specifying version numbers, see Package versioning. Il est également possible de faire remonter les ressources des dépendances directement dans le package à l’aide des attributs include et exclude sur l’élément dependency.It is also possible to surface assets from dependencies directly in the package by using the include and exclude attributes on the dependency element. Consultez Informations de référence sur le fichier .nuspec - Dépendances.See .nuspec Reference - Dependencies.

Étant donné que le manifeste est inclus dans le package à partir duquel il est créé, vous pouvez en trouver de nombreux autres exemples en examinant les packages existants.Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. Le dossier global-packages, sur votre ordinateur, représente une bonne source ; son emplacement est retourné par la commande suivante :A good source is the global-packages folder on your computer, the location of which is returned by the following command:

nuget locals -list global-packages

Accédez à un dossier package\version quelconque, copiez le fichier .nupkg dans un fichier .zip, puis ouvrez ce fichier .zip et examinez le fichier .nuspec qu’il contient.Go into any package\version folder, copy the .nupkg file to a .zip file, then open that .zip file and examine the .nuspec within it.

Notes

Lorsque vous créez un fichier .nuspec à partir d’un projet Visual Studio, le manifeste contient les jetons qui sont remplacés par des informations du projet lors de la génération du package.When creating a .nuspec from a Visual Studio project, the manifest contains tokens that are replaced with information from the project when the package is built. Consultez Création du fichier .nuspec à partir d’un projet Visual Studio.See Creating the .nuspec from a Visual Studio project.

Création du fichier .nuspecCreating the .nuspec file

La création d’un manifeste complet commence généralement par un fichier .nuspec de base généré par l’intermédiaire de l’une des méthodes suivantes :Creating a complete manifest typically begins with a basic .nuspec file generated through one of the following methods:

Vous modifiez ensuite le fichier manuellement afin qu’il décrive le contenu exact que vous voulez dans le package final.You then edit the file by hand so that it describes the exact content you want in the final package.

Important

Les fichiers .nuspec générés contiennent des espaces réservés qui doivent être modifiés avant de créer le package avec la commande nuget pack.Generated .nuspec files contain placeholders that must be modified before creating the package with the nuget pack command. Cette commande échoue si le fichier .nuspec contient des espaces réservés.That command fails if the .nuspec contains any placeholders.

À partir d’un répertoire de travail basé sur une conventionFrom a convention-based working directory

Dans la mesure où un package NuGet n’est qu’un fichier ZIP renommé avec l’extension .nupkg, il est souvent plus simple de créer la structure de dossiers souhaitée sur le système de fichiers local, puis de créer directement le fichier .nuspec à partir de cette structure.Because a NuGet package is just a ZIP file that's been renamed with the .nupkg extension, it's often easiest to create the folder structure you want on your local file system, then create the .nuspec file directly from that structure. La commande nuget pack ajoute alors automatiquement tous les fichiers dans cette structure de dossiers (à l’exclusion des dossiers qui commencent par ., ce qui vous permet de conserver les fichiers privés dans la même structure).The nuget pack command then automatically adds all files in that folder structure (excluding any folders that begin with ., allowing you to keep private files in the same structure).

L’avantage de cette approche est que vous n’avez pas besoin de spécifier, dans le manifeste, les fichiers à inclure dans le package (comme expliqué plus loin dans cette rubrique).The advantage to this approach is that you don't need to specify in the manifest which files you want to include in the package (as explained later in this topic). Vous pouvez simplement demander à votre processus de génération de produire la structure de dossiers exacte qui est placée dans le package et vous pouvez facilement inclure d’autres fichiers qui ne font peut-être pas partie d’un projet :You can simply have your build process produce the exact folder structure that goes into the package, and you can easily include other files that might not be part of a project otherwise:

  • Contenu et code source à injecter dans le projet cible.Content and source code that should be injected into the target project.
  • Scripts PowerShellPowerShell scripts
  • Transformations des fichiers de configuration et de code source existants dans un projet.Transformations to existing configuration and source code files in a project.

Les conventions de dossier sont les suivantes :The folder conventions are as follows:

DossierFolder DescriptionDescription Action à l’installation du packageAction upon package install
(racine)(root) Emplacement du fichier Lisez-moi.txtLocation for readme.txt Visual Studio affiche un fichier Lisez-moi.txt à la racine du package lorsque le package est installé.Visual Studio displays a readme.txt file in the package root when the package is installed.
lib/{tfm}lib/{tfm} Fichiers d’assembly (.dll), de documentation (.xml) et de symbole (.pdb) du TFM (moniker de la version cible de .NET Framework) donnéAssembly (.dll), documentation (.xml), and symbol (.pdb) files for the given Target Framework Moniker (TFM) Les assemblys sont ajoutés comme références pour la compilation et l’exécution. .xml et .pdb sont copiés dans les dossiers du projet.Assemblies are added as references for compile as well as runtime; .xml and .pdb copied into project folders. Consultez Prise en charge de plusieurs frameworks cibles pour créer des sous-dossiers propres à la cible du framework.See Supporting multiple target frameworks for creating framework target-specific sub-folders.
ref/{tfm}ref/{tfm} Fichiers d’assembly (.dll) et de symbole (.pdb) du TFM (moniker de framework cible) donnéAssembly (.dll), and symbol (.pdb) files for the given Target Framework Moniker (TFM) Les assemblys étant uniquement ajoutés comme références pour la compilation, rien n’est copié dans le dossier bin du projet.Assemblies are added as references only for compile time; So nothing will be copied into project bin folder.
runtimesruntimes Fichiers d’assemblies propres à l’architecture (.dll), de symboles (.pdb) et de ressources natives (.pri)Architecture-specific assembly (.dll), symbol (.pdb), and native resource (.pri) files Les assemblys sont uniquement ajoutés comme références pour l’exécution. Les autres fichiers sont copiés dans les dossiers du projet.Assemblies are added as references only for runtime; other files are copied into project folders. Il doit toujours y avoir un assembly spécifique à AnyCPU (TFM) correspondant sous le dossier /ref/{tfm} pour fournir l’assembly correspondant au moment de la compilation.There should always be a corresponding (TFM) AnyCPU specific assembly under /ref/{tfm} folder to provide corresponding compile time assembly. Consultez Prise en charge de plusieurs frameworks cibles.See Supporting multiple target frameworks.
contenucontent Fichiers arbitrairesArbitrary files Le contenu est copié à la racine du projet.Contents are copied to the project root. Considérez que le dossier content est la racine de l’application cible qui consomme le package en définitive.Think of the content folder as the root of the target application that ultimately consumes the package. Pour que le package ajoute une image dans le dossier /images de l’application, placez-le dans le dossier content/images du package.To have the package add an image in the application's /images folder, place it in the package's content/images folder.
buildbuild Fichiers .targets et .props MSBuildMSBuild .targets and .props files Automatiquement insérés dans le fichier projet ou project.lock.json (NuGet 3.x+).Automatically inserted into the project file or project.lock.json (NuGet 3.x+).
outilstools Scripts PowerShell et programmes accessibles à partir de la console du gestionnaire de packagePowershell scripts and programs accessible from the Package Manager Console Le dossier tools est ajouté à la variable d’environnement PATH de la console du gestionnaire de package uniquement (et non à PATH comme défini pour MSBuild lors de la génération du projet).The tools folder is added to the PATH environment variable for the Package Manager Console only (Specifically, not to the PATH as set for MSBuild when building the project).

Dans la mesure où la structure de dossiers peut contenir n’importe quel nombre d’assemblys pour n’importe quel nombre de frameworks cibles, cette méthode est nécessaire pour créer des packages qui prennent en charge plusieurs frameworks.Because your folder structure can contain any number of assemblies for any number of target frameworks, this method is necessary when creating packages that support multiple frameworks.

Dans tous les cas, une fois que la structure de dossiers voulue est en place, exécutez la commande suivante dans ce dossier pour créer le fichier .nuspec :In any case, once you have the desired folder structure in place, run the following command in that folder to create the .nuspec file:

nuget spec

Là encore, le fichier .nuspec généré ne contient aucune référence explicite aux fichiers inclus dans la structure de dossiers.Again, the generated .nuspec contains no explicit references to files in the folder structure. NuGet inclut automatiquement tous les fichiers lorsque le package est créé.NuGet automatically includes all files when the package is created. Vous devez quand même modifier les valeurs d’espace réservé dans d’autres parties du manifeste.You still need to edit placeholder values in other parts of the manifest, however.

À partir d’une DLL d’assemblyFrom an assembly DLL

Dans le cas simple d’une création de package à partir d’un assembly, vous pouvez générer un fichier .nuspec à partir des métadonnées incluses dans l’assembly à l’aide de la commande suivante :In the simple case of creating a package from an assembly, you can generate a .nuspec file from the metadata in the assembly using the following command:

nuget spec <assembly-name>.dll

L’utilisation de cette forme remplace quelques espaces réservés dans le manifeste par des valeurs spécifiques de l’assembly.Using this form replaces a few placeholders in the manifest with specific values from the assembly. Par exemple, la propriété <id> est définie sur le nom de l’assembly et <version> est définie sur la version de l’assembly.For example, the <id> property is set to the assembly name, and <version> is set to the assembly version. Les autres propriétés dans le manifeste, en revanche, n’ont pas de valeurs correspondantes dans l’assembly et contiennent donc toujours des espaces réservés.Other properties in the manifest, however, don't have matching values in the assembly and thus still contain placeholders.

À partir d’un projet Visual StudioFrom a Visual Studio project

La création d’un fichier .nuspec à partir d’un fichier .csproj ou .vbproj s’avère pratique, car les autres packages installés dans ces projets sont automatiquement référencés en tant que dépendances.Creating a .nuspec from a .csproj or .vbproj file is convenient because other packages that have been installed into those project are automatically referenced as dependencies. Utilisez simplement la commande suivante dans le même dossier que le fichier projet :Simply use the following command in the same folder as the project file:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

Le fichier <project-name>.nuspec obtenu contient les jetons qui sont remplacés au moment de l’empaquetage par des valeurs du projet, notamment des références à tous les autres packages qui ont déjà été installés.The resulting <project-name>.nuspec file contains tokens that are replaced at packaging time with values from the project, including references to any other packages that have already been installed.

Un jeton est délimité par des symboles $ des deux côtés de la propriété de projet.A token is delimited by $ symbols on both sides of the project property. Par exemple, la valeur <id> dans un manifeste généré de cette manière se présente généralement comme suit :For example, the <id> value in a manifest generated in this way typically appears as follows:

<id>$id$</id>

Ce jeton est remplacé par la valeur AssemblyName du fichier projet au moment de l’empaquetage.This token is replaced with the AssemblyName value from the project file at packing time. Pour connaître le mappage exact des valeurs de projet sur les jetons .nuspec, consultez les Informations de référence sur les jetons de remplacement.For the exact mapping of project values to .nuspec tokens, see the Replacement Tokens reference.

Les jetons vous évite d’avoir à mettre à jour des valeurs cruciales comme le numéro de version dans le fichier .nuspec quand vous mettez à jour le projet.Tokens relieve you from needing to update crucial values like the version number in the .nuspec as you update the project. (Vous pouvez toujours remplacer les jetons par des valeurs littérales, si vous le souhaitez).(You can always replace the tokens with literal values, if desired).

Notez qu’il existe plusieurs autres options d’empaquetage disponibles quand vous utilisez un projet Visual Studio, comme décrit plus loin dans Exécution de nuget pack pour générer le fichier .nupkg.Note that there are several additional packaging options available when working from a Visual Studio project, as described in Running nuget pack to generate the .nupkg file later on.

Packages au niveau de la solutionSolution-level packages

NuGet 2.x uniquement. Non disponible dans NuGet 3.0+.NuGet 2.x only. Not available in NuGet 3.0+.

NuGet 2.x prenait en charge la notion de package au niveau de la solution qui permettait d’installer des outils ou des commandes supplémentaires pour la console du gestionnaire de package (contenu du dossier tools), sans ajouter de références, de contenu, ni générer des personnalisations pour les projets de la solution.NuGet 2.x supported the notion of a solution-level package that installs tools or additional commands for the Package Manager Console (the contents of the tools folder), but does not add references, content, or build customizations to any projects in the solution. De tels packages ne contiennent aucun fichier dans leurs dossiers lib, content ou build directs et aucune de leurs dépendances n’ont des fichiers dans leurs dossiers lib, content ou build respectifs.Such packages contain no files in its direct lib, content, or build folders, and none of its dependencies have files in their respective lib, content, or build folders.

NuGet assure le suivi des packages installés au niveau de la solution dans un fichier packages.config du dossier .nuget, au lieu du fichier packages.config du projet.NuGet tracks installed solution-level packages in a packages.config file in the .nuget folder, rather than the project's packages.config file.

Nouveau fichier avec des valeurs par défautNew file with default values

La commande suivante crée un manifeste par défaut avec des espaces réservés, ce qui vous permet d’être sûr de commencer avec la structure de fichiers appropriée :The following command creates a default manifest with placeholders, which ensures you start with the proper file structure:

nuget spec [<package-name>]

Si vous omettez le <nom_du_package>, le fichier obtenu est Package.nuspec.If you omit <package-name>, the resulting file is Package.nuspec. Si vous fournissez un nom comme Contoso.Utility.UsefulStuff, le fichier est Contoso.Utility.UsefulStuff.nuspec.If you provide a name such as Contoso.Utility.UsefulStuff, the file is Contoso.Utility.UsefulStuff.nuspec.

Le fichier .nuspec obtenu contient des espaces réservés pour des valeurs telles que projectUrl.The resulting .nuspec contains placeholders for values like the projectUrl. Veillez à modifier le fichier avant de l’utiliser pour créer le fichier .nupkg final.Be sure to edit the file before using it to create the final .nupkg file.

Choix d’un identificateur de package unique et définition du numéro de versionChoosing a unique package identifier and setting the version number

L’identificateur de package (élément <id>) et le numéro de version (élément <version>) sont les deux valeurs les plus importantes dans le manifeste, car ils identifient de façon unique le code exact contenu dans le package.The package identifier (<id> element) and the version number (<version> element) are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package.

Bonnes pratiques en matière d’identificateur de package :Best practices for the package identifier:

  • Unicité : L’identificateur doit être unique sur nuget.org ou dans la galerie qui héberge le package, quelle qu’elle soit.Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. Avant de déterminer un identificateur, faites une recherche dans la galerie applicable pour vérifier si le nom est déjà en cours d’utilisation.Before deciding on an identifier, search the applicable gallery to check if the name is already in use. Pour éviter les conflits, utilisez le nom de votre société comme première partie de l’identificateur, par exemple Contoso..To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • Noms comme les espaces de noms : Suivez un modèle similaire aux espaces de noms dans .NET, en utilisant la notation à points au lieu de traits d’union.Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. Par exemple, utilisez Contoso.Utility.UsefulStuff plutôt que Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff.For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. Les consommateurs trouvent également pratique de faire correspondre l’identificateur du package aux espaces de noms utilisés dans le code.Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • Exemples de package : Si vous produisez un package d’exemple de code qui montre comment utiliser un autre package, attachez .Sample comme suffixe à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample.Sample Packages: If you produce a package of sample code that demonstrates how to use another package, attach .Sample as a suffix to the identifier, as in Contoso.Utility.UsefulStuff.Sample. (L’exemple de package dépend naturellement de l’autre package.) Lorsque vous créez un exemple de package, utilisez la méthode du répertoire de travail basé sur une convention décrite précédemment.(The sample package would of course have a dependency on the other package.) When creating a sample package, use the convention-based working directory method described earlier. Dans le dossier content, réorganisez l’exemple de code dans un dossier appelé \Samples\<identifier> comme dans \Samples\Contoso.Utility.UsefulStuff.Sample.In the content folder, arrange the sample code in a folder called \Samples\<identifier> as in \Samples\Contoso.Utility.UsefulStuff.Sample.

Bonnes pratiques en matière de version de package :Best practices for the package version:

  • En général, définissez la version du package pour qu’elle corresponde à la bibliothèque, bien que cela ne soit pas strictement obligatoire.In general, set the version of the package to match the library, though this is not strictly required. C’est très simple lorsque vous limitez un package à un seul assembly, comme décrit précédemment dans Déterminer quels assemblys empaqueter.This is a simple matter when you limit a package to a single assembly, as described earlier in Deciding which assemblies to package. Globalement, n’oubliez pas que NuGet lui-même traire les versions de package lors de la résolution des dépendances, pas les versions d’assembly.Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • Lorsque vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de gestion de versions NuGet, comme expliqué dans Gestion des versions de package.When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning.

Les séries suivantes de courts billets de blog s’avèrent également utiles pour comprendre la gestion de versions :The following series of brief blog posts are also helpful to understand versioning:

Définition d’un type de packageSetting a package type

Avec NuGet 3.5+, les packages peuvent être marqués avec un type de package spécifique pour indiquer leur usage prévu.With NuGet 3.5+, packages can be marked with a specific package type to indicate its intended use. Les packages non marqués avec un type, notamment tous les packages créés avec des versions antérieures de NuGet, sont du type Dependency par défaut.Packages not marked with a type, including all packages created with earlier versions of NuGet, default to the Dependency type.

  • Les packages de type Dependency ajoutent des ressources de build ou d’exécution aux bibliothèques et applications et peuvent être installés dans n’importe quel type de projet (en supposant qu’ils soient compatibles).Dependency type packages add build- or run-time assets to libraries and applications, and can be installed in any project type (assuming they are compatible).

  • Les packages de type DotnetCliTool sont des extensions de l’interface de ligne de commande .NET et ils sont appelés à partir de la ligne de commande.DotnetCliTool type packages are extensions to the .NET CLI and are invoked from the command line. De tels packages peuvent être installés uniquement dans des projets .NET Core et n’ont aucun effet sur les opérations de restauration.Such packages can be installed only in .NET Core projects and have no effect on restore operations. Plus d’informations sur ces extensions par projet sont disponibles dans la documentation Extensibilité de .NET Core.More details about these per-project extensions are available in the .NET Core extensibility documentation.

  • Les packages de type personnalisé utilisent un identificateur de type arbitraire qui respecte les mêmes règles de format que les ID de package.Custom type packages use an arbitrary type identifier that conforms to the same format rules as package IDs. Tous les types autres que Dependency et DotnetCliTool, en revanche, ne sont pas reconnus par le gestionnaire de package NuGet dans Visual Studio.Any type other than Dependency and DotnetCliTool, however, are not recognized by the NuGet Package Manager in Visual Studio.

Les types de package sont définis dans le fichier .nuspec.Package types are set in the .nuspec file. Il est préférable pour la compatibilité descendante de ne pas définir explicitement le type Dependency et de plutôt compter sur le fait que NuGet supposera qu’il s’agit de ce type quand aucun type n’est spécifié.It's best for backwards compatibility to not explicitly set the Dependency type and to instead rely on NuGet assuming this type when no type is specified.

  • .nuspec: Indique le type de package dans un nœud packageTypes\packageType sous l’élément <metadata> :.nuspec: Indicate the package type within a packageTypes\packageType node under the <metadata> element:

    <?xml version="1.0" encoding="utf-8"?>
    <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
        <metadata>
        <!-- ... -->
        <packageTypes>
            <packageType name="DotnetCliTool" />
        </packageTypes>
        </metadata>
    </package>
    

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, utilisez le nœud <files> dans le fichier .nuspec, ce qui suit la balise <metadata> :To directly specify files to include in the package, use the <files> node in the .nuspec file, which follows the <metadata> tag:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Conseil

Lorsque vous utilisez la méthode du répertoire de travail basé sur une convention, vous pouvez placer le fichier Lisez-moi.txt à la racine du package et le reste du contenu dans le dossier content.When using the convention-based working directory approach, you can place the readme.txt in the package root and other content in the content folder. Aucun élément <file> n’est nécessaire dans le manifeste.No <file> elements are necessary in the manifest.

Lorsque vous incluez un fichier nommé readme.txt à la racine du package, Visual Studio affiche le contenu de ce fichier sous forme de texte brut immédiatement après avoir installé le package directement.When you include a file named readme.txt in the package root, 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

Si vous incluez un nœud <files> vide dans le fichier .nuspec, NuGet n’inclut aucun autre contenu dans le package autre que celui du dossier lib.If you include an empty <files> node in the .nuspec file, NuGet doesn't include any other content in the package other than what's in the lib folder.

Inclusion de cibles et de propriétés MSBuild dans un packageIncluding MSBuild props and targets in a package

Vous pouvez être amené à ajouter des cibles ou propriétés de build personnalisées dans les projets qui utilisent votre package, comme dans le cas de l’exécution d’un processus ou outil personnalisé pendant la génération.In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. Pour cela, vous placez les fichiers sous la forme de <package_id>.targets ou <package_id>.props (par exemple, Contoso.Utility.UsefulStuff.targets) dans le dossier \build du projet.You do this by placing files in the form <package_id>.targets or <package_id>.props (such as Contoso.Utility.UsefulStuff.targets) within the \build folder of the project.

Les fichiers inclus dans le dossier \build racine sont considérés comme appropriés à toutes les versions cibles de .Net Framework.Files in the root \build folder are considered suitable for all target frameworks. Pour fournir des fichiers spécifiques au framework, commencez par les placer dans les sous-dossiers appropriés, notamment :To provide framework-specific files, first place them within appropriate subfolders, such as the following:

\build
    \netstandard1.4
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets
    \net462
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets

Ensuite, dans le fichier .nuspec, veillez à faire référence à ces fichiers dans le nœud <files> :Then in the .nuspec file, be sure to refer to these files in the <files> node:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

L’inclusion des propriétés et des cibles MSBuild dans un package a été introduite avec NuGet 2.5. Il est donc recommandé d’ajouter l’attribut minClientVersion="2.5" à l’élément metadata pour indiquer la version minimale du client NuGet nécessaire pour utiliser le package.Including MSBuild props and targets in a package was introduced with NuGet 2.5, therefore it is recommended to add the minClientVersion="2.5" attribute to the metadata element, to indicate the minimum NuGet client version required to consume the package.

Quand NuGet installe un package avec des fichiers \build, il ajoute des éléments <Import> MSBuild au fichier projet pointant vers les fichiers .targets et .props.When NuGet installs a package with \build files, it adds MSBuild <Import> elements in the project file pointing to the .targets and .props files. (.props est ajouté en haut du fichier projet. .targets est ajouté en bas.) Un élément <Import> MSBuild conditionnel distinct est ajouté pour chaque version cible de .NET Framework.(.props is added at the top of the project file; .targets is added at the bottom.) A separate conditional MSBuild <Import> element is added for each target framework.

Les fichiers .props et .targets MSBuild du ciblage multi-infrastructure peuvent être placés dans le dossier \buildMultiTargeting.MSBuild .props and .targets files for cross-framework targeting can be placed in the \buildMultiTargeting folder. Lors de l’installation de package, NuGet ajoute les éléments <Import> correspondants au fichier projet à la condition que la version cible de .NET Framework ne soit pas définie (la propriété MSBuild $(TargetFramework) doit être vide).During package installation, NuGet adds the corresponding <Import> elements to the project file with the condition, that the target framework is not set (the MSBuild property $(TargetFramework) must be empty).

Avec NuGet 3.x, les cibles ne sont pas ajoutées au projet, mais accessibles via project.lock.json.With NuGet 3.x, targets are not added to the project but are instead made available through the project.lock.json.

Création de packages avec des assemblys COM InteropAuthoring packages with COM interop assemblies

Les packages qui contiennent des assemblys COM Interop doivent inclure un fichier de cibles approprié afin que les bonnes métadonnées EmbedInteropTypes soient ajoutées aux projets en utilisant le format PackageReference.Packages that contain COM interop assemblies must include an appropriate targets file so that the correct EmbedInteropTypes metadata is added to projects using the PackageReference format. Par défaut, les métadonnées EmbedInteropTypes sont toujours fausses pour tous les assemblys lorsque PackageReference est utilisé, si bien que le fichier de cibles ajoute ces métadonnées explicitement.By default, the EmbedInteropTypes metadata is always false for all assemblies when PackageReference is used, so the targets file adds this metadata explicitly. Pour éviter les conflits, le nom de la cible doit être unique ; dans l’idéal, utilisez une combinaison du nom de votre package et de l’assembly incorporé, en remplaçant {InteropAssemblyName} dans l’exemple ci-dessous par cette valeur.To avoid conflicts, the target name should be unique; ideally, use a combination of your package name and the assembly being embedded, replacing the {InteropAssemblyName} in the example below with that value. (Consultez également NuGet.Samples.Interop pour obtenir un exemple.)(Also see NuGet.Samples.Interop for an example.)

<Target Name="Embedding**AssemblyName**From**PackageId**" AfterTargets="ResolveReferences" BeforeTargets="FindReferenceAssembliesForReferences">
  <ItemGroup>
    <ReferencePath Condition=" '%(FileName)' == '{InteropAssemblyName}' AND '%(ReferencePath.NuGetPackageId)' == '$(MSBuildThisFileName)' ">
      <EmbedInteropTypes>true</EmbedInteropTypes>
    </ReferencePath>
  </ItemGroup>
</Target>

Notez que, si le format de gestion packages.config est utilisé, l’ajout de références aux assemblys à partir des packages amène NuGet et Visual Studio à rechercher des assemblys COM Interop et à affecter à EmbedInteropTypes la valeur true dans le fichier projet.Note that when using the packages.config management format, adding references to the assemblies from the packages causes NuGet and Visual Studio to check for COM interop assemblies and set the EmbedInteropTypes to true in the project file. Dans ce cas, les cibles sont remplacées.In this case the targets are overriden.

De plus, les ressources de build ne circulent pas de manière transitive par défaut.Additionally, by default the build assets do not flow transitively. Les packages créés comme décrit ici fonctionnent différemment quand ils sont extraits en tant que dépendance transitive d’un projet vers une référence de projet.Packages authored as described here work differently when they are pulled as a transitive dependency from a project to project reference. Le consommateur du package peut les autoriser à circuler en modifiant la valeur par défaut PrivateAssets de sorte à ce qu’elle n’inclue pas de build.The package consumer can allow them to flow by modifying the PrivateAssets default value to not include build.

Exécution de nuget pack pour générer le fichier .nupkgRunning nuget pack to generate the .nupkg file

Lorsque vous utilisez un assembly ou le répertoire de travail basé sur une convention, créez un package en exécutant nuget pack avec votre fichier .nuspec, en remplaçant <project-name> par votre nom de fichier spécifique :When using an assembly or the convention-based working directory, create a package by running nuget pack with your .nuspec file, replacing <project-name> with your specific filename:

nuget pack <project-name>.nuspec

Lorsque vous utilisez un projet Visual Studio, exécutez nuget pack avec votre fichier projet, ce qui charge automatiquement le fichier .nuspec du projet et remplace tous les jetons qu’il contient en utilisant les valeurs contenues dans le fichier projet :When using a Visual Studio project, run nuget pack with your project file, which automatically loads the project's .nuspec file and replaces any tokens within it using values in the project file:

nuget pack <project-name>.csproj

Notes

Il est nécessaire d’utiliser le fichier projet directement pour le remplacement des jetons, car le projet est la source des valeurs de jeton.Using the project file directly is necessary for token replacement because the project is the source of the token values. Le remplacement des jetons ne se produit pas si vous utilisez nuget pack avec un fichier .nuspec.Token replacement does not happen if you use nuget pack with a .nuspec file.

Dans tous les cas, nuget pack exclut les dossiers qui commencent par un point, comme .git ou .hg.In all cases, nuget pack excludes folders that start with a period, such as .git or .hg.

NuGet indique s’il existe des erreurs dans le fichier .nuspec à corriger, comme l’oubli de modifier des valeurs d’espace réservé dans le manifeste.NuGet indicates if there are any errors in the .nuspec file that need correcting, such as forgetting to change placeholder values in the manifest.

Une fois que nuget pack réussit, vous avez un fichier .nupkg que vous pouvez publier dans une galerie appropriée, comme décrit dans Publication d’un package.Once nuget pack succeeds, you have a .nupkg file that you can publish to a suitable gallery as described in Publishing a Package.

Conseil

Une manière utile d’examiner un package après l’avoir créé consiste à l’ouvrir dans l’outil Explorateur de package.A helpful way to examine a package after creating it is to open it in the Package Explorer tool. Vous obtenez ainsi une vue graphique du contenu du package et de son manifeste.This gives you a graphical view of the package contents and its manifest. Vous pouvez également renommer le fichier .nupkg obtenu en fichier .zip et explorer son contenu directement.You can also rename the resulting .nupkg file to a .zip file and explore its contents directly.

Options supplémentairesAdditional options

Vous pouvez utiliser divers commutateurs de ligne de commande avec nuget pack pour exclure des fichiers, remplacer le numéro de version dans le manifeste et modifier le dossier de sortie, entre autres fonctionnalités.You can use various command-line switches with nuget pack to exclude files, override the version number in the manifest, and change the output folder, among other features. Pour en obtenir la liste complète, reportez-vous aux informations de référence sur la commande pack.For a complete list, refer to the pack command reference.

Les options suivantes figurent parmi les quelques options communes aux projets Visual Studio :The following options are a few that are common with Visual Studio projects:

  • Projets référencés : Si le projet fait référence à d’autres projets, vous pouvez ajouter les projets référencés dans le cadre du package, ou en tant que dépendances, à l’aide de l’option -IncludeReferencedProjects :Referenced projects: If the project references other projects, you can add the referenced projects as part of the package, or as dependencies, by using the -IncludeReferencedProjects option:

    nuget pack MyProject.csproj -IncludeReferencedProjects
    

    Ce processus d’inclusion est récursif, donc si MyProject.csproj fait référence aux projets B et C, et que ces projets font référence aux projets D, E et F, alors les fichiers de B, C, D, E et F sont inclus dans le package.This inclusion process is recursive, so if MyProject.csproj references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F are included in the package.

    Si un projet référencé inclut un fichier .nuspec bien à lui, alors NuGet ajoute ce projet référencé plutôt en tant que dépendance.If a referenced project includes a .nuspec file of its own, then NuGet adds that referenced project as a dependency instead. Vous devez empaqueter et publier ce projet séparément.You need to package and publish that project separately.

  • Configuration de build : Par défaut, NuGet utilise la configuration de build par défaut définie dans le fichier projet, généralement Debug.Build configuration: By default, NuGet uses the default build configuration set in the project file, typically Debug. Pour compresser des fichiers d’une configuration de build différente, comme Release, utilisez l’option -properties avec la configuration :To pack files from a different build configuration, such as Release, use the -properties option with the configuration:

    nuget pack MyProject.csproj -properties Configuration=Release
    
  • Symboles : pour inclure les symboles qui permettent aux utilisateurs de parcourir votre code de package dans le débogueur, utilisez l’option -Symbols :Symbols: to include symbols that allow consumers to step through your package code in the debugger, use the -Symbols option:

    nuget pack MyProject.csproj -symbols
    

Test de l’installation du packageTesting package installation

Avant de publier un package, il est d’usage de tester son processus d’installation dans un projet de test.Before publishing a package, you typically want to test the process of installing a package into a project. Les tests permettent de s’assurer que les fichiers nécessaires se placent tous au bon endroit dans le projet.The tests make sure that the necessarily files all end up in their correct places in the project.

Vous pouvez tester des installations manuellement dans Visual Studio ou à partir de la ligne de commande en suivant les étapes d’installation normales du package.You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

Pour les tests automatisés, le processus de base est le suivant :For automated testing, the basic process is as follows:

  1. Copiez le fichier .nupkg dans un dossier local.Copy the .nupkg file to a local folder.
  2. Ajoutez le dossier à vos sources de package à l’aide de la commande nuget sources add -name <name> -source <path> (consultez Sources nuget).Add the folder to your package sources using the nuget sources add -name <name> -source <path> command (see nuget sources). Notez que vous ne devez définir cette source locale qu’une seule fois sur un ordinateur donné.Note that you need only set this local source once on any given computer.
  3. Installez le package à partir de cette source en utilisant nuget install <packageID> -source <name><name> correspond au nom de votre source tel qu’il est donné à nuget sources.Install the package from that source using nuget install <packageID> -source <name> where <name> matches the name of your source as given to nuget sources. La spécification de la source permet de s’assurer que le package est installé à partir de cette source uniquement.Specifying the source ensures that the package is installed from that source alone.
  4. Examinez votre système de fichiers pour vérifier que les fichiers sont correctement installés.Examine your file system to check that files are installed correctly.

Étapes suivantesNext Steps

Une fois que vous avez créé un package, qui est un fichier .nupkg, vous pouvez le publier dans la galerie de votre choix comme décrit dans Publication d’un package.Once you've created a package, which is a .nupkg file, you can publish it to the gallery of your choice as described on Publishing a Package.

Vous pouvez également étendre les fonctionnalités de votre package ou prendre en charge d’autres scénarios comme décrit dans les rubriques suivantes :You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Enfin, il existe d’autres types de package à connaître :Finally, there are additional package types to be aware of: