Partager via

Créer un package à l’aide de l’interface CLI nuget.exe

Peu importe ce que fait votre package ou le code qu’il contient, vous utilisez l’un des outils CLI, soit nuget.exedotnet.exe, pour empaqueter cette fonctionnalité dans un composant qui peut être partagé avec et utilisé par n’importe quel nombre d’autres développeurs. Pour installer les outils de l’interface CLI NuGet, consultez Installer les outils clients NuGet. Notez que Visual Studio n’inclut pas automatiquement un outil CLI.

Techniquement, un package NuGet n’est qu’un fichier ZIP renommé avec l’extension .nupkg et dont le contenu correspond à certaines conventions. Cette rubrique décrit le processus détaillé de création d’un package qui répond à ces conventions.

L’empaquetage commence par le code compilé (assemblys), les symboles et/ou d’autres fichiers que vous souhaitez remettre en tant que package (voir Vue d’ensemble et flux de travail). Ce processus est indépendant de la compilation ou de la génération des fichiers qui entrent dans le package, bien que vous puissiez tirer des informations dans un fichier projet pour conserver les assemblys et packages compilés synchronisés.

Important

Cette rubrique s’applique aux projets non de style SDK, généralement des projets autres que .NET Core et .NET Standard à l’aide de Visual Studio 2017 et versions ultérieures et NuGet 4.0+.

Déterminer les assemblies à packager

La plupart des packages à usage général contiennent un ou plusieurs assemblys que d’autres développeurs peuvent utiliser dans leurs propres projets.

  • En général, il est préférable d’avoir un assembly par package NuGet, à condition que chaque assembly soit utile indépendamment. Par exemple, si vous avez un Utilities.dll qui dépend de Parser.dll et que Parser.dll est utile en soi, créez un paquet pour chacun d'eux. Cela permet aux développeurs d’utiliser Parser.dll indépendamment de Utilities.dll.

  • Si votre bibliothèque est composée de plusieurs assemblys qui ne sont pas utiles indépendamment, il est judicieux de les combiner en un seul package. À partir de l'exemple précédent, si le code dans Parser.dll est utilisé uniquement par Utilities.dll, il est acceptable de conserver Parser.dll dans le même paquet.

  • De même, si Utilities.dll dépend de Utilities.resources.dll, où ce dernier n'est pas utile par lui-même, alors placez les deux dans le même paquet.

Les ressources sont, en fait, un cas particulier. 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 (voir Création de packages localisés). Pour cette raison, évitez d’utiliser .resources.dll pour les fichiers qui contiennent sinon du code de package essentiel.

Si votre bibliothèque contient des assemblys COM Interop, suivez les instructions supplémentaires dans Créer des packages avec des assemblys COM Interop.

Rôle et structure du fichier .nuspec

Une fois que vous savez quels fichiers vous souhaitez empaqueter, l’étape suivante consiste à créer un manifeste de package dans un .nuspec fichier XML.

Manifeste :

  1. Décrit le contenu du package et est lui-même inclus dans le package.
  2. Pilote à la fois la création du package et indique à NuGet comment installer le package dans un projet. Par exemple, le manifeste identifie d’autres dépendances de package afin que NuGet puisse également installer ces dépendances lorsque le package principal est installé.
  3. Contient les propriétés obligatoires et facultatives décrites ci-dessous. Pour plus d’informations exactes, y compris d’autres propriétés non mentionnées ici, consultez la référence .nuspec.

Propriétés requises :

  • Identificateur de package, qui doit être unique dans la galerie qui héberge le package.
  • Numéro de version spécifique sous la forme Major.Minor.Patch[-Suffix] où -Suffix identifie les versions en préversion
  • Titre du package tel qu’il doit apparaître sur l’hôte (comme nuget.org)
  • Informations sur l’auteur et le propriétaire.
  • Description longue du package.

Propriétés facultatives courantes :

Voici un fichier classique (mais fictif), .nuspec avec des commentaires décrivant les propriétés :

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

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</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>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            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="" />
        <file src="icon.png" target="" />
    </files>
</package>

Pour plus d’informations sur la déclaration de dépendances et la spécification des numéros de version, consultez packages.config et le contrôle de version du package. Il est également possible d’exposer des éléments provenant de dépendances directement dans le package à l’aide des attributs include et exclude de l’élément dependency. Consultez la référence .nuspec - Dépendances.

Étant donné que le manifeste est inclus dans le package créé à partir de celui-ci, vous pouvez trouver n’importe quel nombre d’exemples supplémentaires en examinant les packages existants. Une bonne source est le dossier global-packages sur votre ordinateur, dont l’emplacement est retourné par la commande suivante :

nuget locals -list global-packages

Accédez à n’importe quel dossier package\version , copiez le .nupkg fichier dans un .zip fichier, puis ouvrez ce .zip fichier et examinez-le .nuspec dans celui-ci.

Note

Lors de la création d’un .nuspec à partir d'un projet Visual Studio, le manifeste contient des jetons qui sont remplacés par des informations du projet lorsque le package est construit. Consultez Création de .nuspec à partir d’un projet Visual Studio.

Créer le fichier .nuspec

La création d’un manifeste complet commence généralement par un fichier de base .nuspec généré par l’une des méthodes suivantes :

Vous modifiez ensuite le fichier manuellement afin qu’il décrit le contenu exact souhaité dans le package final.

Important

Les fichiers générés .nuspec contiennent des "placeholders" qui doivent être modifiés avant de créer le package avec la commande nuget pack. Cette commande échoue si .nuspec contient des espaces réservés.

À partir d’un répertoire de travail basé sur une convention

Étant donné qu’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 votre système de fichiers local, puis de créer le .nuspec fichier directement à partir de cette structure. La nuget pack commande ajoute ensuite automatiquement tous les fichiers de cette structure de dossiers (à l’exclusion des dossiers qui commencent .par , ce qui vous permet de conserver des fichiers privés dans la même structure).

L’avantage de cette approche est que vous n’avez pas besoin de spécifier dans le manifeste les fichiers que vous souhaitez inclure dans le package (comme expliqué plus loin dans cette rubrique). Vous pouvez simplement configurer votre processus de génération pour produire la structure de dossiers exacte destinée au package, et vous pouvez facilement inclure d'autres fichiers qui pourraient autrement ne pas faire partie d'un projet.

  • Contenu et code source qui doivent être injectés dans le projet cible.
  • Scripts PowerShell
  • Transformations des fichiers de configuration et de code source existants dans un projet.

Les conventions de dossier sont les suivantes :

Dossier Descriptif Action lors de l’installation du package
(root) Emplacement de readme.txt Visual Studio affiche un fichier readme.txt dans la racine du package lorsque le package est installé.
lib/{tfm} Fichiers assembly (.dll), documentation (.xml) et symboles (.pdb) pour le moniker du framework cible (TFM) donné Les assemblys sont ajoutés en tant que références pour la compilation et le runtime ; .xml et .pdb copiés dans des dossiers de projet. Consultez la prise en charge de plusieurs frameworks cibles pour créer des sous-dossiers spécifiquement adaptés aux frameworks cibles.
ref/{tfm} Fichiers d’assembly (.dll) et de symbole (.pdb) pour le moniker du framework cible (TFM) donné Les assemblys sont ajoutés en tant que références uniquement pour le temps de compilation ; Par conséquent, rien ne sera copié dans le dossier bin de projet.
runtimes Fichiers d’assembly spécifiques à l’architecture (.dll), de symboles (.pdb) et de ressources natives (.pri) Les assemblys sont ajoutés en tant que références uniquement pour le runtime ; d’autres fichiers sont copiés dans des dossiers de projet. Il doit toujours y avoir un assembly spécifique (TFM) AnyCPU correspondant sous /ref/{tfm} le dossier pour fournir l’assembly correspondant au moment de la compilation. Consultez Prise en charge de plusieurs frameworks cibles.
contenu Fichiers arbitraires Le contenu est copié à la racine du projet. Considérez le dossier de contenu comme la racine de l’application cible qui consomme finalement le package. Pour que le package ajoute une image dans le dossier /images de l’application, placez-la dans le dossier contenu/images du package.
construire (3.x+) fichiers MSBuild .targets et .props Inséré automatiquement dans le projet.
buildMultiTargeting (4.0+) fichiers MSBuild .targets et .props pour le ciblage multiplateforme Inséré automatiquement dans le projet.
buildTransitive Les fichiers MSBuild (5.0+).targets et .props qui transitent vers n'importe quel projet consommateur. Consultez la page des fonctionnalités . Inséré automatiquement dans le projet.
outils Scripts et programmes PowerShell accessibles à partir de la console du Gestionnaire de package Le tools répertoire est ajouté à la PATH variable d'environnement uniquement pour la console du gestionnaire de packages (plus précisément, pas à la PATH telle que définie pour MSBuild lors de la construction du projet).

Étant donné que votre structure de dossiers peut contenir n’importe quel nombre d’assemblys pour un nombre quelconque de frameworks cibles, cette méthode est nécessaire lors de la création de packages qui prennent en charge plusieurs frameworks.

Dans tous les cas, une fois la structure de dossiers souhaitée en place, exécutez la commande suivante dans ce dossier pour créer le .nuspec fichier :

nuget spec

Là encore, le généré .nuspec ne contient aucune référence explicite aux fichiers de la structure de dossiers. NuGet inclut automatiquement tous les fichiers lors de la création du package. Toutefois, vous devez toujours modifier les valeurs d’espace réservé dans d’autres parties du manifeste.

À partir d’une DLL d’assemblage

Dans le cas simple de la création d’un package à partir d’un assembly, vous pouvez générer un .nuspec fichier à partir des métadonnées de l’assembly à l’aide de la commande suivante :

nuget spec <assembly-name>.dll

L’utilisation de ce formulaire remplace quelques espaces réservés dans le manifeste par des valeurs spécifiques de l’assembly. Par exemple, la <id> propriété est définie sur le nom de l’assembly et <version> est définie sur la version de l’assembly. D'autres propriétés dans le manifeste, cependant, n'ont pas de valeurs correspondantes dans l'assemblage et contiennent toujours des espaces réservés.

À partir d’un projet Visual Studio

La création d’un .nuspec fichier à partir d’un fichier .csproj ou d’un .vbproj fichier est pratique, car d’autres packages qui ont été installés dans ce projet sont automatiquement référencés en tant que dépendances. Utilisez simplement la commande suivante dans le même dossier que le fichier projet :

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

Le fichier résultant <project-name>.nuspec contient des jetons remplacés au moment de l’empaquetage par des valeurs du projet, y compris des références à d’autres packages déjà installés.

Si vous avez des dépendances de package à inclure dans .nuspec, utilisez nuget packà la place et obtenez le fichier .nuspec à partir du fichier .nupkg généré. Par exemple, utilisez la commande suivante.

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

Un jeton est délimité par les symboles $ de chaque côté de la propriété du projet. Par exemple, la <id> valeur d’un manifeste généré de cette façon apparaît généralement comme suit :

<id>$id$</id>

Ce jeton est remplacé par la AssemblyName valeur du fichier projet au moment de l’emballage. Pour obtenir le mappage exact des valeurs de projet aux .nuspec jetons, consultez la référence des jetons de remplacement.

Les jetons vous évitent de devoir mettre à jour des valeurs cruciales, comme le numéro de version, lorsque vous procédez à la mise à jour du projet dans le .nuspec. (Vous pouvez toujours remplacer les jetons par des valeurs littérales, si vous le souhaitez).

Notez qu’il existe plusieurs options d’empaquetage supplémentaires disponibles lors de l’utilisation d’un projet Visual Studio, comme décrit dans l’exécution du pack nuget pour générer le fichier .nupkg ultérieurement.

Packages au niveau de la solution

NuGet 2.x uniquement. Non disponible dans NuGet 3.0+.

NuGet 2.x a pris en charge la notion d’un package au niveau de la solution qui installe des outils ou des commandes supplémentaires pour la console du Gestionnaire de package (le contenu du tools dossier), mais n’ajoute pas de références, de contenu ou de personnalisations de build à des projets de la solution. Ces packages ne contiennent aucun fichier dans ses dossiers directs lib, contentou build dossiers, et aucune de ses dépendances n’a de fichiers dans leurs dossiers respectifs lib, contentou build dossiers.

NuGet effectue le suivi des packages installés au niveau de la solution dans un fichier packages.config dans le dossier .nuget, plutôt que dans le fichier du projet packages.config.

Nouveau fichier avec des valeurs par défaut

La commande suivante crée un manifeste par défaut avec des espaces réservés, ce qui vous permet de commencer par la structure de fichiers appropriée :

nuget spec [<package-name>]

Si vous omettez <le nom> du package, le fichier résultant est Package.nuspec. Si vous fournissez un nom tel que Contoso.Utility.UsefulStuff, le fichier est Contoso.Utility.UsefulStuff.nuspec.

Le .nuspec résultant contient des paramètres pour des valeurs telles que le projectUrl. Veillez à modifier le fichier avant de l’utiliser pour créer le fichier final .nupkg .

Choisir un identificateur de package unique et définir le numéro de version

L’identificateur de package (<id> élément) et le numéro de version (<version> élément) sont les deux valeurs les plus importantes dans le manifeste, car ils identifient de manière unique le code exact contenu dans le package.

Bonnes pratiques pour l’identificateur de package :

  • Unicité : l’identificateur doit être unique entre nuget.org ou la galerie qui héberge le package. Avant de décider d’un identificateur, recherchez la galerie applicable pour vérifier si le nom est déjà utilisé. Pour éviter les conflits, un bon modèle consiste à utiliser le nom de votre entreprise comme première partie de l’identificateur, par Contoso.exemple .
  • Noms similaires à des espaces de noms : suivez un modèle similaire aux espaces de noms dans .NET, en utilisant la notation par points au lieu de traits d’union. Par exemple, utilisez Contoso.Utility.UsefulStuff plutôt que Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Les consommateurs trouvent également utile lorsque l’identificateur de paquet correspond aux espaces de noms utilisés dans le code.
  • Exemples de packages : si vous produisez un package d’exemple de code qui montre comment utiliser un autre package, attacher .Sample en tant que suffixe à l’identificateur, comme dans Contoso.Utility.UsefulStuff.Sample. (L’exemple de package aurait bien sûr une dépendance sur l’autre package.) Lors de la création d’un exemple de package, utilisez la méthode de répertoire de travail basée sur la convention décrite précédemment. Dans le content dossier, organisez l’exemple de code dans un dossier appelé \Samples\<identifier> comme dans \Samples\Contoso.Utility.UsefulStuff.Sample.

Bonnes pratiques pour la version du package :

  • En règle générale, définissez la version du package pour qu’elle corresponde à la bibliothèque, bien qu’elle ne soit pas strictement requise. Il s’agit d’une question simple lorsque vous limitez un package à un seul assembly, comme décrit précédemment dans La détermination des assemblys à empaqueter. Dans l’ensemble, n’oubliez pas que NuGet lui-même traite des versions de package lors de la résolution des dépendances, et non des versions d’assembly.
  • Lorsque vous utilisez un schéma de version non standard, veillez à prendre en compte les règles de contrôle de version NuGet, comme expliqué dans le contrôle de version du package.

La série suivante de brefs billets de blog est également utile pour comprendre le contrôle de version :

Ajouter un README et d'autres fichiers

Pour spécifier directement des fichiers à inclure dans le package, utilisez le <files> nœud du .nuspec fichier, qui suit la <metadata> balise :

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/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 / Astuce

Lorsque vous utilisez l’approche du répertoire de travail basé sur la convention, vous pouvez placer la readme.txt dans la racine du package et d’autres contenus dans le content dossier. Aucun élément <file> n'est nécessaire dans le manifeste.

Lorsque vous incluez un fichier nommé readme.txt dans la racine du package, Visual Studio affiche le contenu de ce fichier sous forme de texte brut immédiatement après l’installation du package directement. (Les fichiers Readme ne sont pas affichés pour les paquets installés en tant que dépendances). Par exemple, voici comment le README du package HtmlAgilityPack s’affiche :

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

Note

Si vous incluez un nœud vide <files> dans le .nuspec fichier, NuGet n’inclut aucun autre contenu dans le package autre que ce qui se trouve dans le lib dossier.

Inclure des propriétés et des cibles MSBuild dans un package

Dans certains cas, vous pouvez ajouter des cibles ou des propriétés de build personnalisées dans des projets qui consomment votre package, comme l’exécution d’un outil personnalisé ou d’un processus pendant la génération. Vous pouvez en savoir plus sur les propriétés et cibles MSBuild dans les packages NuGet

Créez <package_id>.targets ou <package_id>.props (par exemple Contoso.Utility.UsefulStuff.targets) dans les dossiers de build du projet.

Ensuite, dans le .nuspec fichier, veillez à faire référence à ces fichiers dans le <files> nœud :

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

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

Lorsque des packages sont ajoutés à un projet, NuGet inclut automatiquement ces propriétés et cibles.

Exécuter le pack nuget pour générer le fichier .nupkg

Lorsque vous utilisez un assembly ou un répertoire de travail basé sur la convention, créez un package en exécutant nuget pack avec votre fichier .nuspec, et remplacez <project-name> par votre nom de fichier spécifique :

nuget pack <project-name>.nuspec

Lorsque vous utilisez un projet Visual Studio, exécutez nuget pack avec votre fichier de projet, qui charge automatiquement le fichier .nuspec du projet et remplace tous les jetons qu’il contient avec les valeurs du fichier de projet :

nuget pack <project-name>.csproj

Note

L’utilisation directe du fichier projet est nécessaire pour le remplacement du jeton, car le projet est la source des valeurs de jeton. Le remplacement de jeton ne se produit pas si vous utilisez nuget pack avec un fichier .nuspec.

Dans tous les cas, nuget pack exclut les dossiers qui commencent par un point, comme .git ou .hg.

NuGet indique s’il existe des erreurs dans le fichier .nuspec qui doivent être corrigées, par exemple en oubliant de modifier les valeurs d’espace réservé dans le manifeste.

Une fois que nuget pack a réussi, vous disposez d’un fichier .nupkg que vous pouvez publier dans une galerie appropriée, tel que décrit dans Publication d’un package.

Conseil / Astuce

Un moyen utile d’examiner un package après sa création consiste à l’ouvrir dans l’outil Explorateur de packages . Cela vous donne une vue graphique du contenu du package et de son manifeste. Vous pouvez également renommer le fichier résultant .nupkg en fichier .zip et explorer son contenu directement.

Options supplémentaires

Vous pouvez utiliser différents 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. Pour obtenir une liste complète, reportez-vous à la référence de commande pack.

Les options suivantes sont quelques-unes courantes avec les projets Visual Studio :

  • 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 :

    nuget pack MyProject.csproj -IncludeReferencedProjects

    Ce processus d’inclusion est récursif. Par conséquent, si MyProject.csproj des références sont des projets B et C, et que ces projets référencent D, E et F, les fichiers de B, C, D, E et F sont inclus dans le package.

    Si un projet référencé inclut un .nuspec fichier de son propre, NuGet ajoute ce projet référencé en tant que dépendance à la place. Vous devez empaqueter et publier ce projet séparément.

  • Configuration de build : Par défaut, NuGet utilise la configuration de build par défaut définie dans le fichier projet, généralement Débogage. Pour packer des fichiers à partir d’une autre configuration de build, telle que Release, utilisez l’option -properties avec la configuration :

    nuget pack MyProject.csproj -properties Configuration=Release

  • Symboles : pour inclure des symboles qui permettent aux consommateurs de parcourir pas à pas votre code du paquet dans le débogueur, utilisez l’option -Symbols :

    nuget pack MyProject.csproj -symbols

Installation du package de test

Avant de publier un package, vous souhaitez généralement tester le processus d’installation d’un package dans un projet. Les tests s’assurent que les fichiers se retrouvent tous dans leurs emplacements corrects dans le projet.

Vous pouvez tester manuellement les installations dans Visual Studio ou sur la ligne de commande à l’aide des étapes d’installation normales du package.

Pour les tests automatisés, le processus de base est le suivant :

  1. Copiez le .nupkg fichier dans un dossier local.
  2. Ajoutez le dossier à vos sources de package à l’aide de la nuget sources add -name <name> -source <path> commande (voir sources nuget). Notez que vous n’avez besoin de définir cette source locale qu’une seule fois sur un ordinateur donné.
  3. Installez le package à partir de cette source en utilisant nuget install <packageID> -source <name>, où <name> correspond au nom de votre source conformément à nuget sources. La spécification de la source garantit que le package est installé à partir de cette source seule.
  4. Examinez votre système de fichiers pour vérifier que les fichiers sont installés correctement.

Étapes suivantes

Une fois que vous avez créé un package, qui est un .nupkg fichier, vous pouvez le publier dans la galerie de votre choix, comme décrit dans La publication d’un 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 :

Enfin, il existe des types de package supplémentaires à prendre en compte :

  • Last updated on