Informations de référence sur le fichier .nuspec

Un fichier .nuspec est un manifeste XML qui contient des métadonnées de package. Ce manifeste est utilisé à la fois pour générer le package et pour fournir des informations aux consommateurs. Le manifeste est toujours inclus dans un package.

Dans cette rubrique :

• Forme générale et schéma
• Jetons de remplacement (lors d’une utilisation avec un projet Visual Studio)
• Dépendances
• Références d’assembly explicite
• Références d’assembly Framework
• Inclusion des fichiers d’assembly
• Inclusion des fichiers de contenu
• Exemples de fichiers .nuspec

Compatibilité des types de projet

• Utilisez .nuspec avec nuget.exe pack pour les projets qui ne sont pas de style SDK utilisant packages.config.

• Un fichier .nuspec n’est pas nécessaire pour créer des packages pour des les projets de style SDK (généralement les projets .NET Core et .NET Standard qui utilisent l’attribut SDK). (Notez qu’un .nuspec est généré lorsque vous créez le package.)

  Si vous créez un package à l’aide de dotnet.exe pack ou msbuild pack target, nous recommandons d’inclure toutes les propriétés qui se trouvent habituellement dans le fichier .nuspec du fichier projet à la place. Toutefois, vous pouvez choisir d’utiliser un fichier .nuspec pour empaqueter à l’aide de dotnet.exe ou msbuild pack target.

• Dans le cas des projets migrés de packages.config à PackageReference, un fichier .nuspec n’est pas requis pour créer le package. Utilisez plutôt msbuild -t:pack.

Forme générale et schéma

Un fichier de schéma nuspec.xsd peut être consulté dans le référentiel GitHub NuGet. Notez que ce fichier ne représente que le schéma le plus récent d’un fichier .nuspec. Aucune version officiellement publiée n’existe et aucune version de ce fichier ne correspond à une version NuGet spécifique.

Dans ce schéma, un fichier .nuspec a la forme générale suivante :

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Pour obtenir une représentation visuelle claire du schéma, ouvrez le fichier de schéma dans Visual Studio en mode Design et cliquez sur le lien Explorateur de schémas XML. Vous pouvez également ouvrir le fichier en tant que code, cliquer avec le bouton droit dans l’éditeur, puis sélectionner Show XML Schema Explorer (Afficher l’Explorateur de schémas XML). Dans les deux cas, vous obtenez un affichage semblable à celui ci-dessous (quand il est en grande partie développé) :

Tous les noms d’éléments XML dans le fichier .nuspec respectent la casse, comme c’est le cas pour XML en général. Par exemple, l’utilisation de l’élément <description> de métadonnées est correcte et <Description> n’est pas correcte. La casse appropriée pour chaque nom d’élément est documentée ci-dessous.

Important

Bien que le fichier .nuspec contient une référence à un schéma (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"), la NuGet-Team n’a jamais publié un fichier de schéma qui peut être utilisé pour la validation automatique de schéma.

Éléments de métadonnées requis

Bien que les éléments suivants correspondent à la configuration minimale requise pour un package, vous devez envisager d’ajouter les éléments de métadonnées facultatifs afin d’améliorer l’expérience globale des développeurs avec votre package.

Ces éléments doivent apparaître dans un élément <metadata>.

id

Identificateur de package ne respectant pas la casse, qui doit être unique dans nuget.org ou dans toute autre galerie susceptible d’héberger le package. Les ID ne peuvent pas contenir d’espaces ni de caractères qui ne sont pas valides pour une URL et suivent généralement les règles d’espace de noms .NET. Pour obtenir des conseils, consultez Choix d’un identificateur de package unique.

Lors du chargement d’un package dans nuget.org, le champ id est limité à 128 caractères.

version

Version du package, selon le modèle version_principale.version_secondaire.version_corrective. Les numéros de version peuvent inclure un suffixe de préversion comme décrit dans Gestion de versions des packages.

Lors du chargement d’un package dans nuget.org, le champ version est limité à 64 caractères.

description

Description du package pour l’affichage de l’interface utilisateur.

Lors du chargement d’un package dans nuget.org, le champ description est limité à 4 000 caractères.

authors

Une liste des packages autorisés séparés par des virgules. Les valeurs authors et owners du fichier nuspec sont ignorées lors du chargement du package sur nuget.org. Pour définir la propriété du package sur nuget.org, consultez Gestion des propriétaires de packages sur nuget.org.

Éléments de métadonnées facultatifs

owners

Important

les propriétaires sont déconseillés. Utilisez les auteurs à la place.

Liste des propriétaires de packages séparés par des virgules. La valeur owners de nuspec est ignorée lors du chargement du package sur nuget.org. Pour définir la propriété du package sur nuget.org, consultez Gestion des propriétaires de packages sur nuget.org.

projectUrl

URL de la page d’accueil du package, souvent affichée dans l’interface utilisateur ainsi que sur nuget.org.

Lors du chargement d’un package dans nuget.org, le champ projectUrl est limité à 4 000 caractères.

licenseUrl

Important

licenseUrl est déconseillé. Utilisez plutôt license.

URL de la licence du package, souvent affichée dans des interfaces utilisateur comme nuget.org.

Lors du chargement d’un package dans nuget.org, le champ licenseUrl est limité à 4 000 caractères.

license

Pris en charge avec NuGet 4.9.0 et versions ultérieures

Expression de licence SPDX ou chemin d’accès à un fichier de licence dans le package, souvent affiché dans des interfaces utilisateur telles que nuget.org. Si vous accordez une licence au package sous une licence commune, comme MIT ou BSD-2-Clause, utilisez l’identificateur de licence SPDX associé. Par exemple :

<license type="expression">MIT</license>

Remarque

NuGet.org accepte uniquement les expressions de licence approuvées par l’Open-Source Initiative ou la Free Software Foundation.

Si votre package est concédé sous licence pour plusieurs licences courantes, vous pouvez spécifier une licence composite à l’aide de la syntaxe d’expression SPDX, version 2.0. Par exemple :

<license type="expression">BSD-2-Clause OR MIT</license>

Si vous utilisez une licence personnalisée qui n’est pas prise en charge par les expressions de licence, vous pouvez empaqueter un fichier .txt ou .md avec le texte de la licence. Par exemple :

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

Pour l’équivalent MSBuild, consultez Packing a license expression or a license file (Compression d’une expression de licence ou d’un fichier de licence).

La syntaxe exacte des expressions de licence de NuGet est décrite ci-dessous dans ABNF.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Important

iconUrl est déconseillé. Utilisez icon à la place.

URL d’une image 128x128 avec un arrière-plan transparent à utiliser comme icône pour le package dans l’affichage de l’interface utilisateur. Vérifiez que cet élément contient l’URL directe de l’image et non l’URL d’une page Web contenant l’image. Par exemple, pour utiliser une image de GitHub, utilisez l’URL du fichier brut comme https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

Lors du chargement d’un package dans nuget.org, le champ iconUrl est limité à 4 000 caractères.

icône

Pris en charge avec NuGet 5.3.0 et versions ultérieures

Il s’agit d’un chemin d’accès à un fichier image au sein du package, souvent affiché dans des interfaces utilisateur comme nuget.org en tant qu’icône de package. La taille du fichier image est limitée à 1 Mo. Les formats de fichiers pris en charge sont JPEG et PNG. Nous recommandons une résolution d’image de 128 x 128.

Par exemple, vous devez ajouter ce qui suit à votre nuspec lors de la création d’un package à l’aide de nuget.exe :

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Exemple nuspec d’icône de package.

Pour l’équivalent MSBuild, consultez Packing an icon image file (Empaquetage d’un fichier image d’icône).

Conseil

Pour maintenir la compatibilité descendante avec les clients et les sources qui ne prennent pas encore en charge icon, spécifiez icon et iconUrl. Visual Studio prend en charge icon pour les packages provenant d’une source basée sur des dossiers.

readme

Pris en charge avec NuGet 5.10.0 Preview 2 et versions ultérieures

Lors de l’empaquetage d’un fichier Lisez-moi, vous devez utiliser l’élément readme pour spécifier le chemin d’accès du package, par rapport à la racine du package. En plus de cela, vous devez vous assurer que le fichier est inclus dans le package. Les formats de fichiers pris en charge incluent uniquement Markdown (.md).

Par exemple, vous devez ajouter ce qui suit à votre nuspec pour créer un package à partir d’un fichier Lisez-moi avec votre projet :

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

Pour l’équivalent MSBuild, consultez Packing a readme file (Empaquetage d’un fichier Lisez-moi).

requireLicenseAcceptance

Valeur booléenne qui spécifie si le client doit inviter l’utilisateur à accepter la licence du package avant d’installer le package.

developmentDependency

(2.8+) Valeur booléenne qui spécifie si le package doit être marqué comme dépendance de développement uniquement, ce qui l’empêche d’être inclus en tant que dépendance dans d’autres packages. Avec PackageReference (NuGet 4.8+), cet indicateur signifie également que la propriété exclura les ressources de la compilation. Consultez Prise en charge de DevelopmentDependency pour PackageReference.

résumé

Important

summary est déconseillé. Utilisez description à la place.

Brève description du package pour l’affichage de l’interface utilisateur. Si cet élément est omis, une version tronquée de description est utilisée.

Lors du chargement d’un package dans nuget.org, le champ summary est limité à 4 000 caractères.

releaseNotes

(1.5+) Description des changements apportés à cette version du package, souvent utilisée dans l’interface utilisateur, par exemple sous l’onglet Mises à jour du Gestionnaire de package Visual Studio à la place de la description du package.

Lors du chargement d’un package sur nuget.org, le champ releaseNotes est limité à 35 000 caractères.

copyright

(1.5+) Détails de copyright pour le package.

Lors du chargement d’un package dans nuget.org, le champ copyright est limité à 4 000 caractères.

language

ID de paramètres régionaux du package. Consultez Création de packages localisés.

tags

Liste de balises et de mots clés délimités par des espaces, qui décrivent le package et permettent de découvrir les packages grâce à des fonctions de recherche et de filtrage.

Lors du chargement d’un package dans nuget.org, le champ tags est limité à 4 000 caractères.

serviceable

(3.3+) Uniquement réservé à un usage NuGet interne.

repository

Métadonnées de référentiel, composées de quatre attributs facultatifs : type et url (4.0+), ainsi que branch et commit (4.6+). Ces attributs vous permettent de mapper .nupkg au référentiel qui l’a créé, avec le potentiel d’obtenir des informations aussi détaillées que le nom de la branche individuelle et/ou valider le hachage SHA-1 qui a créé le package. Il doit s’agir d’une URL disponible publiquement qui peut être appelée directement par un logiciel de gestion de version. Il ne doit pas s’agir d’une page html, car cela est destiné à l’ordinateur. Pour la liaison à la page du projet, utilisez plutôt le champ projectUrl.

Par exemple :

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

Lors du chargement d’un package dans nuget.org, l’attribut type est limité à 100 caractères et l’attribut url est limité à 4 000 caractères.

title

Titre convivial du package qui peut être utilisé dans certains affichages de l’interface utilisateur. (nuget.org et le Gestionnaire de package dans Visual Studio n’affichent pas le titre)

Lors du chargement d’un package dans nuget.org, le champ title est limité à 256 caractères, mais n’est pas utilisé à des fins d’affichage.

Éléments de collection

packageTypes

(3.5+) Collection de zéro ou plusieurs éléments <packageType> spécifiant le type du package s’il est différent du package de dépendances classique. Chaque élément packageType a des attributs name et version. Consultez Définition d’un type de package.

dependencies

Collection de zéro ou plusieurs éléments <dependency> spécifiant les dépendances du package. Chaque dépendance a des attributs id, version, include (3.x+) et exclude (3.x+). Consultez Dépendances ci-dessous.

frameworkAssemblies

(1.2 +) Collection de zéro ou plusieurs éléments <frameworkAssembly> identifiant les références d’assembly .NET Framework nécessaires à ce package, ce qui garantit que les références sont ajoutées à des projets utilisant le package. Chaque élément frameworkAssembly a des attributs assemblyName et targetFramework. Consultez Références d’assembly Framework ci-dessous.

références

(1.5+) Collection de zéro ou plusieurs éléments <reference> nommant des assemblys dans le dossier lib du package qui sont ajoutés en tant que références de projet. Chaque référence a un attribut file. <references> peut également contenir un élément <group> avec un attribut targetFramework qui contient à son tour des éléments <reference>. Si cet élément est omis, toutes les références dans lib sont incluses. Consultez Références d’assembly explicite ci-dessous.

contentFiles

(3.3+) Collection d’éléments <files> qui identifient les fichiers de contenu à inclure dans le projet de consommation. Ces fichiers sont spécifiés avec un ensemble d’attributs qui décrivent comment ils doivent être utilisés dans le système de projet. Consultez Inclusion des fichiers d’assembly ci-dessous.

files

Le nœud <package> peut contenir un nœud <files> en tant que frère de <metadata> et/ou un enfant <contentFiles> sous <metadata> pour indiquer l’assembly et les fichiers de contenu à inclure dans le package. Consultez Inclusion des fichiers d’assembly et Inclusion des fichiers de contenu plus loin dans cette rubrique pour plus d’informations.

Attributs de métadonnées

minClientVersion

Spécifie la version minimale du client NuGet qui peut installer ce package, appliquée par nuget.exe et le gestionnaire de package Visual Studio. Cet attribut est utilisé chaque fois que le package dépend de fonctionnalités spécifiques du fichier .nuspec qui ont été ajoutées dans une version particulière du client NuGet. Par exemple, un package utilisant l’attribut developmentDependency doit spécifier « 2.8 » pour minClientVersion. De même, un package utilisant l’élément contentFiles (consultez la section suivante) doit affecter à minClientVersion la valeur « 3.3 ». Notez également que, comme les clients NuGet antérieurs à 2.5 ne reconnaissent pas cet indicateur, ils refusent toujours d’installer le package, quel que soit le contenu de minClientVersion.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Jetons de remplacement

Lors de la création d’un package, la nuget packcommande remplace les jetons séparés par des $ dans les nœuds <metadata> et <files> du fichier .nuspec par des valeurs provenant d’un fichier projet ou du commutateur pack de la commande -properties.

Sur la ligne de commande, vous spécifiez des valeurs de jeton avec nuget pack -properties <name>=<value>;<name>=<value>. Par exemple, vous pouvez utiliser un jeton tel que $owners$ et $desc$ dans le fichier .nuspec et fournir les valeurs au moment de la compression comme suit :

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Pour utiliser les valeurs à partir d’un projet, spécifiez les jetons décrits dans le tableau ci-dessous (AssemblyInfo fait référence au fichier dans Properties comme AssemblyInfo.cs ou AssemblyInfo.vb).

Pour utiliser ces jetons, exécutez nuget pack avec le fichier projet et non simplement le fichier .nuspec. Par exemple, quand vous utilisez la commande suivante, les jetons $id$ et $version$ dans un fichier .nuspec sont remplacés par les valeurs AssemblyName et AssemblyVersion du projet :

nuget pack MyProject.csproj

En général, quand vous avez un projet, vous créez le fichier .nuspec initialement à l’aide de nuget spec MyProject.csproj qui inclut automatiquement certains de ces jetons standard. Toutefois, si un projet ne possède pas de valeurs pour les éléments .nuspec requis, nuget pack échoue. De plus, si vous modifiez des valeurs de projet, veillez à régénérer avant de créer le package ; pour effectuer cette opération en toute facilité, utilisez le commutateur build de la commande pack.

À l’exception de $configuration$, les valeurs dans le projet sont préférées à celles affectées au même jeton sur la ligne de commande.

par jeton	Source de valeur	Valeur
$id$	Fichier projet	AssemblyName (titre) du fichier projet
$version$	AssemblyInfo	AssemblyInformationalVersion si présente, sinon AssemblyVersion
$author$	AssemblyInfo	AssemblyCompany
$title$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	DLL d’assembly	Configuration utilisée pour générer l’assembly, Debug étant la valeur par défaut. Notez que, pour créer un package à l’aide d’une configuration Release, vous utilisez toujours -properties Configuration=Release sur la ligne de commande.

Les jetons peuvent également être utilisés pour résoudre les chemins quand vous incluez des fichiers d’assembly et fichiers de contenu. Les jetons ont les mêmes noms que les propriétés MSBuild, ce qui permet de sélectionner les fichiers à inclure en fonction de la configuration de build actuelle. Par exemple, si vous utilisez les jetons suivants dans le fichier .nuspec :

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

Et que vous générez un assembly dont AssemblyName est LoggingLibrary avec la configuration Release dans MSBuild, les lignes résultantes dans le fichier .nuspec du package sont les suivantes :

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Élément dependencies

L’élément <dependencies> dans <metadata> contient un nombre quelconque d’éléments <dependency> qui identifient d’autres packages dont dépend le package de niveau supérieur. Les attributs pour chaque élément <dependency> sont les suivants :

Attribut	Description
id	(Obligatoire) ID de package de la dépendance, tel que « EntityFramework » et « NUnit », qui est le nom du package nuget.org affiché sur une page de package.
version	(Obligatoire) Plage de versions acceptables en tant que dépendance. Consultez Gestion de versions des packages pour connaître la syntaxe exacte. Les versions flottantes ne sont pas prises en charge.
include	Liste de balises include/exclude séparées par des virgules (voir ci-dessous) indiquant la dépendance à inclure dans le package final. La valeur par défaut est all.
exclure	Liste de balises include/exclude séparées par des virgules (voir ci-dessous) indiquant la dépendance à exclure dans le package final. La valeur par défaut est build,analyzers, qui peut être surécrite. Mais content/ ContentFiles sont aussi implicitement exclus dans le package final qui ne peut pas être surécrit. Les balises spécifiées avec exclude sont prioritaires sur celles spécifiées avec include. Par exemple, include="runtime, compile" exclude="compile" est identique à include="runtime".

Lors du chargement d’un package dans nuget.org, l’attribut id de chaque dépendance est limité à 128 caractères et l’attribut version est limité à 256 caractères.

Balise include/exclude	Dossiers affectés de la cible
contentFiles	Contenu
runtime	Runtime, Resources et FrameworkAssemblies
compiler	lib
build	build (propriétés et cibles MSBuild)
native	native
Aucune	Aucun dossier
all	Tous les dossiers

Par exemple, les lignes suivantes indiquent les dépendances sur PackageA version 1.1.0 ou ultérieure, et PackageB version 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Les lignes suivantes indiquent les dépendances sur les mêmes packages, mais spécifient d’inclure les dossiers contentFiles et build de PackageA et tous les éléments sauf les dossiers native et compile de PackageB.

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Important

Quand vous créez un fichier .nuspec à partir d’un projet avec nuget spec, les dépendances qui existent dans le projet ne sont pas automatiquement incluses dans le fichier .nuspec obtenu. Utilisez plutôt nuget pack myproject.csproj et récupérez le fichier .nuspec à partir du fichier .nupkg généré. Ce fichier .nuspec contient les dépendances.

Groupes de dépendances

Version 2.0+

Comme alternative à une liste plate unique, les dépendances peuvent être spécifiées selon le profil de framework du projet cible avec les éléments <group> dans <dependencies>.

Chaque groupe possède un attribut nommé targetFramework et contient zéro ou plusieurs éléments <dependency>. Ces dépendances sont installées ensemble quand la version cible de .Net Framework est compatible avec le profil de framework du projet.

L’élément <group> sans un attribut targetFramework est utilisé comme valeur par défaut ou liste de secours de dépendances. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.

Important

Le format de groupe ne peut pas être mélangé avec une liste plate.

Remarque

Le format du moniker de framework cible (TFM) utilisé dans le dossier lib/ref est différent par rapport au TFM utilisé dans dependency groups. Si les frameworks cibles déclarés dans dependencies group et le dossier lib/ref du fichier .nuspecn’ont pas de correspondances exactes, la commande pack déclenche l’avertissement NuGet NU5128.

L’exemple suivant illustre différentes variantes de l’élément <group> :

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Références d’assembly explicite

L’élément <references> est utilisé par des projets employant packages.config pour spécifier explicitement les assemblys que le projet cible doit référencer lors de l’utilisation du package. Des références explicites sont généralement utilisées pour les assemblys uniquement au moment du design. Pour plus d’informations, consultez la page sur la sélection d’assemblys référencés par des projets.

Par exemple, l’élément <references> suivant demande à NuGet d’ajouter des références à xunit.dll et xunit.extensions.dll uniquement même s’il existe d’autres assemblys dans le package :

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Groupes de référence

Comme alternative à une liste plate unique, les références peuvent être spécifiées selon le profil de framework du projet cible avec les éléments <group> dans <references>.

Chaque groupe possède un attribut nommé targetFramework et contient zéro ou plusieurs éléments <reference>. Ces références sont ajoutées à un projet quand la version cible de .NET Framework est compatible avec le profil de framework du projet.

L’élément <group> sans un attribut targetFramework est utilisé comme valeur par défaut ou liste de secours de références. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.

Important

Le format de groupe ne peut pas être mélangé avec une liste plate.

L’exemple suivant illustre différentes variantes de l’élément <group> :

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Références d’assembly Framework

Les assemblys Framework sont ceux qui font partie du .NET Framework et doivent déjà figurer dans le GAC (Global Assembly Cache) pour un ordinateur donné. En identifiant ces assemblys dans l’élément <frameworkAssemblies>, un package peut garantir que les références requises sont ajoutées à un projet si le projet ne dispose pas déjà de telles références. Ces assemblys, bien entendu, ne sont pas directement inclus dans un package.

L’élément <frameworkAssemblies> contient zéro ou plusieurs éléments <frameworkAssembly>, chacun d’eux spécifiant les attributs suivants :

Attribut	Description
assemblyName	(Obligatoire) Nom d’assembly qualifié complet.
targetFramework	(Facultatif) Spécifie la version cible de .NET Framework à laquelle s’applique cette référence. Si cet attribut est omis, indique que la référence s’applique à tous les frameworks. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.

L’exemple suivant montre une référence à System.Net pour toutes les versions cibles de .NET Framework et une référence à System.ServiceModel pour .NET Framework 4.0 uniquement :

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Inclusion des fichiers d’assembly

Si vous suivez les conventions décrites dans Création d’un package, il est inutile de spécifier explicitement une liste de fichiers dans le fichier .nuspec. La commande nuget pack sélectionne automatiquement les fichiers nécessaires.

Important

Quand 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. C’est pourquoi vous devez éviter d’utiliser .resources.dll pour les fichiers qui contiennent du code de package essentiel.

Pour ignorer ce comportement automatique et contrôler explicitement les fichiers qui sont inclus dans un package, placez un élément <files> en tant qu’enfant de <package> (et frère de <metadata>), identifiant chaque fichier avec un élément <file> distinct. Par exemple :

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

Avec NuGet 2.x et versions antérieures, et des projets utilisant packages.config, l’élément <files> est également utilisé pour inclure les fichiers de contenu non modifiables quand un package est installé. Avec NuGet 3.3+ et les projets PackageReference, l’élément <contentFiles> est utilisé à la place. Consultez Inclusion des fichiers de contenu ci-dessous pour plus d’informations.

Attributs des éléments File

Chaque élément <file> spécifie les attributs suivants :

Attribut	Description
src	Emplacement du ou des fichiers à inclure, soumis à des exclusions définies par l’attribut exclude. Le chemin est relatif au fichier .nuspec sauf si un chemin absolu est spécifié. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.
cible	Chemin relatif vers le dossier dans le package où les fichiers sources sont placés, qui doit commencer par lib, content, build ou tools. Consultez Création d’un fichier .nuspec à partir d’un répertoire de travail basé sur une convention.
exclude	Liste de fichiers ou de modèles de fichiers séparés par un point-virgule à exclure de l’emplacement src. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.

Exemples

Assembly unique

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Assembly unique spécifique à une version cible de .NET Framework

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Ensemble de DLL avec un caractère générique

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

DLL de différents frameworks

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Exclusion de fichiers

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Inclusion des fichiers de contenu

Les fichiers de contenu sont des fichiers non modifiables qu’un package doit inclure dans un projet. Comme ils ne sont pas modifiables, ils ne sont pas destinés à être changés par le projet de consommation. Des exemples de fichiers de contenu sont notamment :

• Images incorporées en tant que ressources
• Fichiers sources qui sont déjà compilés
• Scripts qui doivent être inclus avec la sortie de génération du projet
• Fichiers de configuration pour le package qui doivent être inclus dans le projet, mais ne nécessitent aucune modification spécifique au projet

Les fichiers de contenu sont inclus dans un package à l’aide de l’élément <files>, en spécifiant le dossier content dans l’attribut target. Toutefois, ces fichiers sont ignorés quand le package est installé dans un projet utilisant PackageReference, qui utilise à la place l’élément <contentFiles>.

Pour une compatibilité maximale avec les projets de consommation, un package spécifie dans l’idéal les fichiers de contenu dans les deux éléments.

Utilisation de l’élément files pour les fichiers de contenu

Pour les fichiers de contenu, utilisez simplement le même format que pour les fichiers d’assembly, mais spécifiez content comme dossier de base dans l’attribut target comme indiqué dans les exemples suivants.

Fichiers de contenu de base

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Fichiers de contenu avec structure de répertoires

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Fichier de contenu spécifique à une version cible de .NET Framework

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Fichier de contenu copié vers un dossier avec un point dans le nom

Dans ce cas, NuGet détecte que l’extension dans target ne correspond pas à l’extension dans src et traite par conséquent cette partie du nom dans target en tant que dossier :

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Fichiers de contenu sans extensions

Pour inclure les fichiers sans extension, utilisez les caractères génériques * ou ** :

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Fichiers de contenu avec chemin complet et cible complète

Dans ce cas, étant donné que les extensions de fichier de la source et de la cible correspondent, NuGet part du principe que la cible est un nom de fichier et non un dossier :

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Modification du nom d’un fichier de contenu dans le package

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Exclusion de fichiers

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Utilisation de l’élément contentFiles pour les fichiers de contenu

NuGet 4.0 + avec PackageReference

Par défaut, un package place le contenu dans un dossier contentFiles (voir ci-dessous) et nuget pack a mis tous les fichiers dans ce dossier à l’aide des attributs par défaut. Dans ce cas, il n’est pas du tout nécessaire d’inclure un nœud contentFiles dans le fichier .nuspec.

Pour contrôler les fichiers qui sont inclus, l’élément <contentFiles> spécifie une collection d’éléments <files> qui identifient exactement les fichiers à ajouter.

Ces fichiers sont spécifiés avec un ensemble d’attributs qui décrivent comment ils doivent être utilisés dans le système de projet :

Attribut	Description
inclure	(Obligatoire) Emplacement du ou des fichiers à inclure, soumis à des exclusions définies par l’attribut exclude. Le chemin d’accès est relatif au dossier contentFiles sauf si un chemin d’acc+es absolu est spécifié. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.
exclude	Liste de fichiers ou de modèles de fichiers séparés par un point-virgule à exclure de l’emplacement src. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.
buildAction	Action de génération à affecter à l’élément de contenu pour MSBuild, comme Content, None, Embedded Resource, Compile, etc. La valeur par défaut est Compile.
copyToOutput	Valeur booléenne indiquant s’il faut copier des éléments de contenu dans le dossier de sortie de génération (ou de publication). La valeur par défaut est false.
aplatir	Valeur booléenne indiquant s’il faut copier des éléments de contenu dans un dossier unique dans la sortie de génération (true) ou conserver la structure de dossiers dans le package (false). Cet indicateur fonctionne uniquement lorsque l’indicateur copyToOutput est défini sur true. La valeur par défaut est false.

Lors de l’installation d’un package, NuGet applique les éléments enfants de <contentFiles> de haut en bas. Si plusieurs entrées correspondent au même fichier, toutes les entrées sont appliquées. L’entrée supérieure remplace les entrées inférieures s’il existe un conflit pour le même attribut.

Structure de dossiers de package

Le projet de package doit structurer le contenu à l’aide du modèle suivant :

/contentFiles/{codeLanguage}/{TxM}/{any?}

• codeLanguages peut être cs, vb, fs, any, ou l’équivalent en minuscules d’un élément $(ProjectLanguage) donné.
• TxM est n’importe quel moniker du Framework cible légal pris en charge par NuGet (consultez Versions cibles de .NET Framework).
• Toute structure de dossiers peut être ajoutée à la fin de cette syntaxe.

Par exemple :

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

Les dossiers vides peuvent utiliser _._ pour choisir de ne pas fournir de contenu pour certaines combinaisons de langage et TxM, par exemple :

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._

Exemple de section contentFiles

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Groupes de référence d’infrastructure

Version 5.1+ avec PackageReference uniquement

Les références d’infrastructure sont un concept .NET Core représentant des infrastructures partagées telles que WPF ou Windows Forms. En spécifiant une infrastructure partagée, le package garantit que toutes ses dépendances d’infrastructure sont incluses dans le projet de référencement.

Chaque élément <group> nécessite un attribut targetFramework et zéro ou plusieurs éléments <frameworkReference>.

L’exemple suivant montre un fichier nuspec généré pour un projet WPF .NET Core. Notez que les nuspecs de création manuelle qui contiennent des références d’infrastructure ne sont pas recommandés. Envisagez plutôt d’utiliser le pack cibles, qui les déduit automatiquement du projet.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

Exemples de fichiers .nuspec

Fichier .nuspec simple qui ne spécifie pas de dépendances ni de fichiers

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

Fichier .nuspec avec des dépendances

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

Fichier .nuspec avec des fichiers

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

Fichier .nuspec avec des assemblys Framework

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

Dans cet exemple, les éléments suivants sont installés pour les cibles de projets spécifiques :

• .NET4 –>System.Web, System.Net
• .NET4 Client Profile –>System.Net
• Silverlight 3 –>System.Json
• WindowsPhone –>Microsoft.Devices.Sensors