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

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. Pour installer les outils CLI NuGet, consultez Installer les outils clients NuGet. Notez que Visual Studio n’inclut pas automatiquement d’outil CLI.

• Pour les projets qui ne sont pas de style SDK, généralement des projets .NET Framework, suivez les étapes décrites dans cet article pour créer un package. Pour obtenir des instructions pas à pas à l’aide de Visual Studio et de l’interface CLI nuget.exe, consultez Créer et publier un package .NET Framework.

• Pour les projets .NET Core et .NET Standard qui utilisent le format SDK-style, et tout autre projet SDK-style, consultez Créer un package NuGet avec l’interface CLI dotnet.

• Pour les projets migrés à partir de packages.config vers PackageReference, utilisez msbuild -t:pack.

Techniquement parlant, 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 à remettre sous forme de package (consultez Vue d’ensemble et flux de travail). 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.

Déterminer quels assemblys empaqueter

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 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. 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. Ainsi, les développeurs peuvent utiliser Parser.dll indépendamment de 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. À 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.

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

En réalité, les ressources correspondent à un cas spécial. 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). C’est pourquoi vous devez éviter d’utiliser .resources.dll pour les fichiers qui contiennent du code de package essentiel.

Si votre bibliothèque contient des assemblys COM Interop, suivez les instructions supplémentaires données 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 voulez empaqueter, l’étape suivante consiste à créer un manifeste de package dans un fichier XML .nuspec.

Le manifeste :

1. Décrit le contenu du package et est lui-même inclus dans le package.
2. Dirige la création du package et indique à NuGet comment installer le package dans un projet. Par exemple, le manifeste identifie les autres dépendances de package pour que NuGet puisse également les installer lorsque le package principal est installé.
3. Contient des propriétés à la fois obligatoires et facultatives comme décrit ci-dessous. 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.

Propriétés obligatoires :

• Identificateur du package, qui doit être unique dans toute la galerie qui héberge le package.
• Numéro de version spécifique au format version_principale.version_secondaire.version_corrective [-suffixe] où -suffixe identifie les préversions.
• Titre du package tel qu’il doit apparaître sur l’hôte (par exemple nuget.org)
• Informations sur l’auteur et le propriétaire.
• Longue description du package.

Propriétés facultatives communes :

• Notes de publication
• Informations de copyright
• Brève description de l’interface utilisateur du gestionnaire de package dans Visual Studio
• ID de paramètres régionaux
• URL du projet
• Licence en tant qu’expression ou fichier (licenseUrl est déconseillé, utilisez l’élément de métadonnées nuspec license à la place)
• Un fichier d’icône (iconUrl est déconseillé, utilisez l’élément de métadonnées nuspecicon à la place)
• Listes des dépendances et références
• Balises facilitant les recherches dans la galerie

Voici un fichier .nuspec classique (mais fictif), 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 des dépendances et la spécification des numéros de version, consultez packages.config et Gestion des versions de package. 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. Consultez Informations de référence sur le fichier .nuspec - Dépendances.

É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. Le dossier global-packages, sur votre ordinateur, représente une bonne source ; son emplacement est retourné par la commande suivante :

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.

Créer le fichier .nuspec

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 :

• Un répertoire de travail basé sur une convention
• Une DLL d’assembly
• Un projet Visual Studio
• Un nouveau fichier avec des valeurs par défaut

Vous modifiez ensuite le fichier manuellement afin qu’il décrive le contenu exact que vous voulez dans le package final.

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

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

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

• Contenu et code source à injecter 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 :

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.

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 :

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. NuGet inclut automatiquement tous les fichiers lorsque le package est créé. Vous devez quand même modifier les valeurs d’espace réservé dans d’autres parties du manifeste.

À partir d’une DLL d’assembly

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 :

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

À partir d’un projet Visual Studio

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

Si vous avez des dépendances de package à inclure dans .nuspec, utilisez plutôt nuget pack et récupérez 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 des symboles $ des deux côtés de la propriété de projet. Par exemple, la valeur <id> dans un manifeste généré de cette manière se présente généralement comme suit :

<id>$id$</id>

Ce jeton est remplacé par la valeur AssemblyName du fichier projet au moment de l’empaquetage. 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.

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. (Vous pouvez toujours remplacer les jetons par des valeurs littérales, si vous le souhaitez).

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.

Packages au niveau de la solution

NuGet 2.x uniquement. Non disponible dans 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. 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.

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.

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 d’être sûr de commencer avec la structure de fichiers appropriée :

nuget spec [<package-name>]

Si vous omettez le <nom_du_package>, le fichier obtenu est Package.nuspec. Si vous fournissez un nom comme Contoso.Utility.UsefulStuff, le fichier est Contoso.Utility.UsefulStuff.nuspec.

Le fichier .nuspec obtenu contient des espaces réservés pour des valeurs telles que projectUrl. Veillez à modifier le fichier avant de l’utiliser pour créer le fichier .nupkg final.

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

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.

Bonnes pratiques en matière d’identificateur de package :

• Unicité : l’identificateur doit être unique sur nuget.org ou dans la galerie qui héberge le package, quelle qu’elle soit. 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. Pour éviter les conflits, utilisez le nom de votre société comme première partie de l’identificateur, par exemple 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. Par exemple, utilisez Contoso.Utility.UsefulStuff plutôt que Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Les consommateurs trouvent également pratique de faire correspondre l’identificateur du package aux espaces de noms utilisés dans le 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. (L’exemple de package aurait bien sûr eu 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 dossier content, réorganisez l’exemple de code dans un dossier appelé \Samples\<identifier> comme dans \Samples\Contoso.Utility.UsefulStuff.Sample.

Bonnes pratiques en matière de version de package :

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

Les séries suivantes de courts billets de blog s’avèrent également utiles pour comprendre la gestion de versions :

• Partie 1 : Affronter les difficultés liées aux DLL
• Partie 2 : L’algorithme principal
• Partie 3 : Unification par le biais de redirections de liaison

Ajouter un fichier Lisez-moi et d’autres fichiers

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

<?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>

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. (Les fichiers Lisez-moi ne s’affichent pas pour les packages installés en tant que dépendances). Par exemple, voici comment s’affiche le fichier Lisez-moi du package HtmlAgilityPack :

Inclure des cibles et des propriétés MSBuild dans un 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. Pour en savoir plus sur les fichiers MSBuild props et targets dans les packages NuGet

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

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

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

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

Quand des packages sont ajoutés à un projet, NuGet inclut automatiquement ces fichier props et targets.

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

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 :

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 :

nuget pack <project-name>.csproj

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 à corriger, comme l’oubli de modifier des valeurs d’espace réservé dans le manifeste.

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.

Options supplémentaires

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. Pour en obtenir la liste complète, reportez-vous aux informations de référence sur la commande pack.

Les options suivantes figurent parmi les quelques options communes aux 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, 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.

  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. 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 Debug. Pour compresser des fichiers d’une configuration de build différente, comme Release, utilisez l’option -properties avec la 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 :

  nuget pack MyProject.csproj -symbols
  

Tester l’installation de package

Avant de publier un package, il est d’usage de tester son processus d’installation dans un projet de test. Les tests permettent de s’assurer que les fichiers nécessaires se placent tous au bon endroit dans le projet.

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.

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

1. Copiez le fichier .nupkg dans un dossier local.
2. Ajoutez le dossier à vos sources de package à l’aide de la commande nuget sources add -name <name> -source <path> (consultez Sources nuget). Notez que vous ne devez 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 tel qu’il est donné à nuget sources. La spécification de la source permet de s’assurer que le package est installé à partir de cette source uniquement.
4. Examinez votre système de fichiers pour vérifier que les fichiers sont correctement installés.

Étapes suivantes

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.

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 :

• Gestion des versions de package
• Prise en charge de plusieurs frameworks cibles
• Transformations de fichiers sources et de configuration
• Localisation
• Préversions
• Définir un type de package
• Créer des packages avec des assemblys COM Interop

Enfin, il existe d’autres types de package à connaître :

• Packages natifs
• Packages de symboles