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

Un fichier .nuspec est un manifeste XML qui contient des métadonnées de package.A .nuspec file is an XML manifest that contains package metadata. Ce manifeste est utilisé à la fois pour générer le package et pour fournir des informations aux consommateurs.This manifest is used both to build the package and to provide information to consumers. Le manifeste est toujours inclus dans un package.The manifest is always included in a package.

Dans cette rubrique :In this topic:

Compatibilité des types de projetProject type compatibility

Forme générale et schémaGeneral form and schema

Le fichier de schéma nuspec.xsd actuel se trouve dans le dépôt GitHub NuGet.The current nuspec.xsd schema file can be found in the NuGet GitHub repository.

Dans ce schéma, un fichier .nuspec a la forme générale suivante :Within this schema, a .nuspec file has the following general form:

<?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.For a clear visual representation of the schema, open the schema file in Visual Studio in Design mode and click on the XML Schema Explorer link. 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).Alternately, open the file as code, right-click in the editor, and select Show XML Schema Explorer. Dans les deux cas, vous obtenez un affichage semblable à celui ci-dessous (quand il est en grande partie développé) :Either way you get a view like the one below (when mostly expanded):

Explorateur de schémas Visual Studio avec nuspec.xsd ouvert

Éléments de métadonnées requisRequired metadata elements

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.Although the following elements are the minimum requirements for a package, you should consider adding the optional metadata elements to improve the overall experience developers have with your package.

Ces éléments doivent apparaître dans un élément <metadata>.These elements must appear within a <metadata> element.

idid

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.The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package resides in. 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.IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. Pour obtenir des conseils, consultez Choix d’un identificateur de package unique.See Choosing a unique package identifier for guidance.

versionversion

Version du package, selon le modèle version_principale.version_secondaire.version_corrective.The version of the package, following the major.minor.patch pattern. Les numéros de version peuvent inclure un suffixe de préversion comme décrit dans Gestion de versions des packages.Version numbers may include a pre-release suffix as described in Package versioning.

descriptiondescription

Description longue du package pour l’affichage de l’interface utilisateur.A long description of the package for UI display.

authorsauthors

Liste séparée par des virgules des auteurs de packages, qui correspondent aux noms de profil sur nuget.org. Ceux-ci sont affichés dans la galerie NuGet sur nuget.org et servent à croiser les références des packages de mêmes auteurs.A comma-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

Éléments de métadonnées facultatifsOptional metadata elements

ownersowners

Liste des créateurs de packages séparés par des virgules, qui utilisent des noms de profil sur nuget.org. Il s’agit souvent de la même liste que dans authors et elle est ignorée lors du chargement du package sur nuget.org. Consultez Gestion des propriétaires de packages sur nuget.org.A comma-separated list of the package creators using profile names on nuget.org. This is often the same list as in authors, and is ignored when uploading the package to nuget.org. See Managing package owners on nuget.org.

projectUrlprojectUrl

URL de la page d’accueil du package, souvent affichée dans l’interface utilisateur ainsi que sur nuget.org.A URL for the package's home page, often shown in UI displays as well as nuget.org.

licenseUrllicenseUrl

Important

licenseUrl est déconseillé.licenseUrl is being deprecated. Utilisez plutôt la licence.Use license instead.

URL de la licence du package, souvent présentée dans des interfaces utilisateur telles que nuget.org.A URL for the package's license, often shown in UIs like nuget.org.

Licencelicense

Une expression de licence SPDX ou un chemin d’accès à un fichier de licence dans le package, souvent affiché dans des interfaces utilisateur telles que nuget.org. Si vous configurez le package sous une licence commune, comme MIT ou BSD-2-clause, utilisez l' identificateur de licence SPDXassocié.An SPDX license expression or path to a license file within the package, often shown in UIs like nuget.org. If you're licensing the package under a common license, like MIT or BSD-2-Clause, use the associated SPDX license identifier. Par exemple :For example:

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

Notes

NuGet.org accepte uniquement les expressions de licence approuvées par l’initiative Open source ou la Fondation logicielle gratuite.NuGet.org only accepts license expressions that are approved by the Open Source Initiative or the Free Software Foundation.

Si votre package est concédé sous licence sous plusieurs licences courantes, vous pouvez spécifier une licence composite à l’aide de la syntaxe d’expression SPDX version 2,0.If your package is licensed under multiple common licenses, you can specify a composite license using the SPDX expression syntax version 2.0. Par exemple :For example:

<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 .txt licence .md , vous pouvez empaqueter un fichier ou avec le texte de la licence.If you use a custom license that isn't supported by license expressions, you can package a .txt or .md file with the license's text. Par exemple :For example:

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

Pour l’équivalent MSBuild, jetez un coup d’œil sur l’empaquetage d’une expression de licence ou d’un fichier de licence.For the MSBuild equivalent, take a look at Packing a license expression or a license file.

La syntaxe exacte des expressions de licence de NuGet est décrite ci-dessous dans ABNF.The exact syntax of NuGet's license expressions is described below in 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)

iconUrliconUrl

URL d’une image 64x64 avec un arrière-plan transparent à utiliser comme icône pour le package dans l’affichage de l’interface utilisateur.A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. Vérifiez que cet élément contient l’URL directe de l’image et non l’URL d’une page web contenant l’image.Be sure this element contains the direct image URL and not the URL of a web page containing the image. Par exemple, pour utiliser une image de GitHub, utilisez l’URL de fichier brut https://github.com/<username>/<repository>/raw/<branch>/<logo.png>comme.For example, to use an image from GitHub, use the raw file URL like https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

requireLicenseAcceptancerequireLicenseAcceptance

Valeur booléenne qui spécifie si le client doit inviter l’utilisateur à accepter la licence du package avant d’installer le package.A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package.

developmentDependencydevelopmentDependency

(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.(2.8+) A Boolean value specifying whether the package is be marked as a development-only-dependency, which prevents the package from being included as a dependency in other packages. Avec PackageReference (NuGet 4.8 +), cet indicateur signifie également qu’il exclura les éléments multimédias de compilation de la compilation.With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. Voir prise en charge de DevelopmentDependency pour PackageReferenceSee DevelopmentDependency support for PackageReference

résumésummary

Brève description du package pour l’affichage de l’interface utilisateur.A short description of the package for UI display. Si cet élément est omis, une version tronquée de description est utilisée.If omitted, a truncated version of description is used.

releaseNotesreleaseNotes

(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.(1.5+) A description of the changes made in this release of the package, often used in UI like the Updates tab of the Visual Studio Package Manager in place of the package description.

(1.5+) Détails de copyright pour le package.(1.5+) Copyright details for the package.

langagelanguage

ID de paramètres régionaux du package.The locale ID for the package. Consultez Création de packages localisés.See Creating localized packages.

balisestags

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.A space-delimited list of tags and keywords that describe the package and aid discoverability of packages through search and filtering.

une maintenanceserviceable

(3.3+) Uniquement réservé à un usage NuGet interne.(3.3+) For internal NuGet use only.

repositoryrepository

Métadonnées de référentiel, composées de quatre attributs facultatifs: type et URL (4.0 +) et Branch et Commit (4.6 +) .Repository metadata, consisting of four optional attributes: type and url (4.0+), and branch and commit (4.6+). Ces attributs vous permettent de mapper le fichier. nupkg au référentiel qui l’a créé, avec la possibilité d’obtenir le même détail que la branche individuelle ou la validation qui a créé le package.These attributes allow you to map the .nupkg to the repository that built it, with the potential to get as detailed as the individual branch or commit that built the package. Il doit s’agir d’une URL disponible publiquement qui peut être appelée directement par un logiciel de contrôle de version.This should be a publicly available url that can be invoked directly by a version control software. Il ne doit pas s’agir d’une page HTML, car cela est destiné à l’ordinateur.It should not be an html page as this is meant for the computer. Pour la liaison à la page de projet projectUrl , utilisez le champ à la place.For linking to project page, use the projectUrl field, instead.

minClientVersionminClientVersion

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.Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager. 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.This is used whenever the package depends on specific features of the .nuspec file that were added in a particular version of the NuGet client. Par exemple, un package utilisant l’attribut developmentDependency doit spécifier « 2.8 » pour minClientVersion.For example, a package using the developmentDependency attribute should specify "2.8" for minClientVersion. De même, un package utilisant l’élément contentFiles (consultez la section suivante) doit affecter à minClientVersion la valeur « 3.3 ».Similarly, a package using the contentFiles element (see the next section) should set minClientVersion to "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.Note also that because NuGet clients prior to 2.5 do not recognize this flag, they always refuse to install the package no matter what minClientVersion contains.

titletitle

Un titre convivial du package qui peut être utilisé dans certaines interfaces utilisateur s’affiche.A human-friendly title of the package which may be used in some UI displays. (nuget.org et le gestionnaire de package dans Visual Studio n’affichent pas le titre)(nuget.org and the Package Manager in Visual Studio do not show title)

Éléments de collectionCollection elements

packageTypespackageTypes

(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.(3.5+) A collection of zero or more <packageType> elements specifying the type of the package if other than a traditional dependency package. Chaque élément packageType a des attributs name et version.Each packageType has attributes of name and version. Consultez Définition d’un type de package.See Setting a package type.

dépendancesdependencies

Collection de zéro ou plusieurs éléments <dependency> spécifiant les dépendances du package.A collection of zero or more <dependency> elements specifying the dependencies for the package. Chaque dépendance a des attributs id, version, include (3.x+) et exclude (3.x+).Each dependency has attributes of id, version, include (3.x+), and exclude (3.x+). Consultez Dépendances ci-dessous.See Dependencies below.

frameworkAssembliesframeworkAssemblies

(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.(1.2+) A collection of zero or more <frameworkAssembly> elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. Chaque élément frameworkAssembly a des attributs assemblyName et targetFramework.Each frameworkAssembly has assemblyName and targetFramework attributes. Consultez Références d’assembly Framework ci-dessous.See Specifying framework assembly references GAC below. |

Référencesreferences

(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.(1.5+) A collection of zero or more <reference> elements naming assemblies in the package's lib folder that are added as project references. Chaque référence a un attribut file.Each reference has a file attribute. <references> peut également contenir un élément <group> avec un attribut targetFramework qui contient à son tour des éléments <reference>.<references> can also contain a <group> element with a targetFramework attribute, that then contains <reference> elements. Si cet élément est omis, toutes les références dans lib sont incluses.If omitted, all references in lib are included. Consultez Références d’assembly explicite ci-dessous.See Specifying explicit assembly references below.

contentFilescontentFiles

(3.3+) Collection d’éléments <files> qui identifient les fichiers de contenu à inclure dans le projet de consommation.(3.3+) A collection of <files> elements that identify content files to include in the consuming project. 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.These files are specified with a set of attributes that describe how they should be used within the project system. Consultez Inclusion des fichiers d’assembly ci-dessous.See Specifying files to include in the package below.

fichiers d'entréefiles

Le <package> nœud peut contenir un <files> nœud en tant que frère <metadata>pour, et <contentFiles> un enfant <metadata>sous, pour spécifier l’assembly et les fichiers de contenu à inclure dans le package.The <package> node may contain a <files> node as a sibling to <metadata>, and a <contentFiles> child under <metadata>, to specify which assembly and content files to include in the package. Consultez Inclusion des fichiers d’assembly et Inclusion des fichiers de contenu plus loin dans cette rubrique pour plus d’informations.See Including assembly files and Including content files later in this topic for details.

Jetons de remplacementReplacement tokens

Lors de la création d’un package, la commande nuget pack remplace les jetons séparés par des $ dans le nœud <metadata> du fichier .nuspec par des valeurs provenant d’un fichier projet ou du commutateur -properties de la commande pack.When creating a package, the nuget pack command replaces $-delimited tokens in the .nuspec file's <metadata> node with values that come from either a project file or the pack command's -properties switch.

Sur la ligne de commande, vous spécifiez des valeurs de jeton avec nuget pack -properties <name>=<value>;<name>=<value>.On the command line, you specify token values with 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 :For example, you can use a token such as $owners$ and $desc$ in the .nuspec and provide the values at packing time as follows:

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).To use values from a project, specify the tokens described in the table below (AssemblyInfo refers to the file in Properties such as AssemblyInfo.cs or AssemblyInfo.vb).

Pour utiliser ces jetons, exécutez nuget pack avec le fichier projet et non simplement le fichier .nuspec.To use these tokens, run nuget pack with the project file rather than just the .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 :For example, when using the following command, the $id$ and $version$ tokens in a .nuspec file are replaced with the project's AssemblyName and AssemblyVersion values:

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.Typically, when you have a project, you create the .nuspec initially using nuget spec MyProject.csproj which automatically includes some of these standard tokens. Toutefois, si un projet ne possède pas de valeurs pour les éléments .nuspec requis, nuget pack échoue.However, if a project lacks values for required .nuspec elements, then nuget pack fails. De plus, si vous modifiez des valeurs de projet, veillez à regénérer avant de créer le package ; pour effectuer cette opération en toute facilité, utilisez le commutateur build de la commande pack.Furthermore, if you change project values, be sure to rebuild before creating the package; this can be done conveniently with the pack command's build switch.

À 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.With the exception of $configuration$, values in the project are used in preference to any assigned to the same token on the command line.

TokenToken Source de la valeurValue source ValeurValue
$id$$id$ Fichier projetProject file AssemblyName (titre) à partir du fichier projetAssemblyName (title) from the project file
$version$$version$ AssemblyInfoAssemblyInfo AssemblyInformationalVersion si présente, sinon AssemblyVersionAssemblyInformationalVersion if present, otherwise AssemblyVersion
$author$$author$ AssemblyInfoAssemblyInfo AssemblyCompanyAssemblyCompany
$title$$title$ AssemblyInfoAssemblyInfo AssemblyTitleAssemblyTitle
$description$$description$ AssemblyInfoAssemblyInfo AssemblyDescriptionAssemblyDescription
$copyright$$copyright$ AssemblyInfoAssemblyInfo AssemblyCopyrightAssemblyCopyright
$configuration$$configuration$ DLL d’assemblyAssembly DLL Configuration utilisée pour générer l’assembly, Debug étant la valeur par défaut.Configuration used to build the assembly, defaulting to Debug. Notez que, pour créer un package à l’aide d’une configuration Release, vous utilisez toujours -properties Configuration=Release sur la ligne de commande.Note that to create a package using a Release configuration, you always use -properties Configuration=Release on the command line.

Les jetons peuvent également être utilisés pour résoudre les chemins quand vous incluez des fichiers d’assembly et fichiers de contenu.Tokens can also be used to resolve paths when you include assembly files and content files. 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.The tokens have the same names as the MSBuild properties, making it possible to select files to be included depending on the current build configuration. Par exemple, si vous utilisez les jetons suivants dans le fichier .nuspec :For example, if you use the following tokens in the .nuspec file:

<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 :And you build an assembly whose AssemblyName is LoggingLibrary with the Release configuration in MSBuild, the resulting lines in the .nuspec file in the package is as follows:

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

Élément DependenciesDependencies element

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.The <dependencies> element within <metadata> contains any number of <dependency> elements that identify other packages upon which the top-level package depends. Les attributs pour chaque élément <dependency> sont les suivants :The attributes for each <dependency> are as follows:

AttributAttribute DescriptionDescription
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.(Required) The package ID of the dependency, such as "EntityFramework" and "NUnit", which is the name of the package nuget.org shows on a package page.
version (Obligatoire) Plage de versions acceptables en tant que dépendance.(Required) The range of versions acceptable as a dependency. Consultez Gestion de versions des packages pour connaître la syntaxe exacte.See Package versioning for exact syntax.
includeinclude Liste de balises include/exclude séparées par des virgules (voir ci-dessous) indiquant la dépendance à inclure dans le package final.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to include in the final package. La valeur par défaut est all.The default value is all.
excludeexclude Liste de balises include/exclude séparées par des virgules (voir ci-dessous) indiquant la dépendance à exclure dans le package final.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to exclude in the final package. La valeur build,analyzers par défaut peut être trop écrite.The default value is build,analyzers which can be over-written. Mais content/ ContentFiles sont également implicitement exclus dans le package final qui ne peut pas être trop écrit.But content/ ContentFiles are also implicitly excluded in the final package which can't be over-written. Les balises spécifiées avec exclude sont prioritaires sur celles spécifiées avec include.Tags specified with exclude take precedence over those specified with include. Par exemple, include="runtime, compile" exclude="compile" est identique à include="runtime".For example, include="runtime, compile" exclude="compile" is the same as include="runtime".
Balise include/excludeInclude/Exclude tag Dossiers affectés de la cibleAffected folders of the target
contentFilescontentFiles ContenuContent
runtimeruntime Runtime, Resources et FrameworkAssembliesRuntime, Resources, and FrameworkAssemblies
compilecompile liblib
buildbuild build (propriétés et cibles MSBuild)build (MSBuild props and targets)
nativenative nativenative
nonenone Aucun dossierNo folders
allall Tous les dossiersAll folders

Par exemple, les lignes suivantes indiquent les dépendances sur PackageA version 1.1.0 ou ultérieure, et PackageB version 1.x.For example, the following lines indicate dependencies on PackageA version 1.1.0 or higher, and 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.The following lines indicate dependencies on the same packages, but specify to include the contentFiles and build folders of PackageA and everything but the native and compile folders of PackageB"

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

Remarque : Lors de la .nuspec création d’un à nuget specpartir d’un projet à l’aide de, les dépendances qui .nuspec existent dans ce projet sont automatiquement incluses dans le fichier résultant.Note: When creating a .nuspec from a project using nuget spec, dependencies that exist in that project are automatically included in the resulting .nuspec file.

Groupes de dépendancesDependency groups

Version 2.0+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>.As an alternative to a single flat list, dependencies can be specified according to the framework profile of the target project using <group> elements within <dependencies>.

Chaque groupe possède un attribut nommé targetFramework et contient zéro ou plusieurs éléments <dependency>.Each group has an attribute named targetFramework and contains zero or more <dependency> elements. Ces dépendances sont installées ensemble quand la version cible de .NET Framework est compatible avec le profil de framework du projet.Those dependencies are installed together when the target framework is compatible with the project's framework profile.

L’élément <group> sans un attribut targetFramework est utilisé comme valeur par défaut ou liste de secours de dépendances.The <group> element without a targetFramework attribute is used as the default or fallback list of dependencies. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.See Target frameworks for the exact framework identifiers.

Important

Le format de groupe ne peut pas être mélangé avec une liste plate.The group format cannot be intermixed with a flat list.

L’exemple suivant illustre différentes variantes de l’élément <group> :The following example shows different variations of the <group> element:

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

    <group targetFramework="net40">
        <dependency id="jQuery" />
        <dependency id="WebActivator" />
    </group>

    <group targetFramework="sl30">
    </group>
</dependencies>

Références d’assembly expliciteExplicit assembly references

L' <references> élément est utilisé par les projets packages.config qui utilisent pour spécifier explicitement les assemblys que le projet cible doit référencer lors de l’utilisation du package.The <references> element is used by projects using packages.config to explicitly specify the assemblies that the target project should reference when using the package. Des références explicites sont généralement utilisées pour les assemblys uniquement au moment du design.Explicit references are typically used for design-time only assemblies. Pour plus d’informations, consultez la page sur la sélection des assemblys référencés par les projets pour plus d’informations.For more information, see the page on selecting assemblies referenced by projects for more information.

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 :For example, the following <references> element instructs NuGet to add references to only xunit.dll and xunit.extensions.dll even if there are additional assemblies in the package:

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

Groupes de référenceReference groups

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>.As an alternative to a single flat list, references can be specified according to the framework profile of the target project using <group> elements within <references>.

Chaque groupe possède un attribut nommé targetFramework et contient zéro ou plusieurs éléments <reference>.Each group has an attribute named targetFramework and contains zero or more <reference> elements. 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.Those references are added to a project when the target framework is compatible with the project's framework profile.

L’élément <group> sans un attribut targetFramework est utilisé comme valeur par défaut ou liste de secours de références.The <group> element without a targetFramework attribute is used as the default or fallback list of references. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.See Target frameworks for the exact framework identifiers.

Important

Le format de groupe ne peut pas être mélangé avec une liste plate.The group format cannot be intermixed with a flat list.

L’exemple suivant illustre différentes variantes de l’élément <group> :The following example shows different variations of the <group> element:

<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 FrameworkFramework assembly references

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é.Framework assemblies are those that are part of the .NET framework and should already be in the global assembly cache (GAC) for any given machine. 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.By identifying those assemblies within the <frameworkAssemblies> element, a package can ensure that required references are added to a project in the event that the project doesn't have such references already. Ces assemblys, bien entendu, ne sont pas directement inclus dans un package.Such assemblies, of course, are not included in a package directly.

L’élément <frameworkAssemblies> contient zéro ou plusieurs éléments <frameworkAssembly>, chacun d’eux spécifiant les attributs suivants :The <frameworkAssemblies> element contains zero or more <frameworkAssembly> elements, each of which specifies the following attributes:

AttributAttribute DescriptionDescription
assemblyNameassemblyName (Obligatoire) Nom d’assembly qualifié complet.(Required) The fully qualified assembly name.
targetFrameworktargetFramework (Facultatif) Spécifie la version cible de .NET Framework à laquelle s’applique cette référence.(Optional) Specifies the target framework to which this reference applies. Si cet attribut est omis, indique que la référence s’applique à tous les frameworks.If omitted, indicates that the reference applies to all frameworks. Consultez Versions cibles de .NET Framework pour connaître les identificateurs de framework exacts.See Target frameworks for the exact framework identifiers.

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 :The following example shows a reference to System.Net for all target frameworks, and a reference to System.ServiceModel for .NET Framework 4.0 only:

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

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

Inclusion des fichiers d’assemblyIncluding assembly files

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.If you follow the conventions described in Creating a Package, you do not have to explicitly specify a list of files in the .nuspec file. La commande nuget pack sélectionne automatiquement les fichiers nécessaires.The nuget pack command automatically picks up the necessary files.

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.When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies. C’est pourquoi vous devez éviter d’utiliser .resources.dll pour les fichiers qui contiennent du code de package essentiel.For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

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.To bypass this automatic behavior and explicitly control which files are included in a package, place a <files> element as a child of <package> (and a sibling of <metadata>), identifying each file with a separate <file> element. Par exemple :For example:

<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é.With NuGet 2.x and earlier, and projects using packages.config, the <files> element is also used to include immutable content files when a package is installed. Avec NuGet 3.3+ et les projets PackageReference, l’élément <contentFiles> est utilisé à la place.With NuGet 3.3+ and projects PackageReference, the <contentFiles> element is used instead. Consultez Inclusion des fichiers de contenu ci-dessous pour plus d’informations.See Including content files below for details.

Attributs des éléments FileFile element attributes

Chaque élément <file> spécifie les attributs suivants :Each <file> element specifies the following attributes:

AttributAttribute DescriptionDescription
srcsrc Emplacement du ou des fichiers à inclure, soumis à des exclusions définies par l’attribut exclude.The location of the file or files to include, subject to exclusions specified by the exclude attribute. Le chemin est relatif au fichier .nuspec sauf si un chemin absolu est spécifié.The path is relative to the .nuspec file unless an absolute path is specified. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
targettarget Chemin relatif vers le dossier dans le package où les fichiers sources sont placés, qui doit commencer par lib, content, build ou tools.The relative path to the folder within the package where the source files are placed, which must begin with lib, content, build, or tools. Consultez Création d’un fichier .nuspec à partir d’un répertoire de travail basé sur une convention.See Creating a .nuspec from a convention-based working directory.
excludeexclude Liste de fichiers ou de modèles de fichiers séparés par un point-virgule à exclure de l’emplacement src.A semicolon-delimited list of files or file patterns to exclude from the src location. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.

ExemplesExamples

Assembly uniqueSingle assembly

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 FrameworkSingle assembly specific to a target 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ériqueSet of DLLs using a wildcard

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 frameworksDLLs for different 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 fichiersExcluding files

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 contenuIncluding content files

Les fichiers de contenu sont des fichiers non modifiables qu’un package doit inclure dans un projet.Content files are immutable files that a package needs to include in a project. Comme ils ne sont pas modifiables, ils ne sont pas destinés à être changés par le projet de consommation.Being immutable, they are not intended to be modified by the consuming project. Des exemples de fichiers de contenu sont notamment :Example content files include:

  • Images incorporées en tant que ressourcesImages that are embedded as resources
  • Fichiers sources qui sont déjà compilésSource files that are already compiled
  • Scripts qui doivent être inclus avec la sortie de génération du projetScripts that need to be included with the build output of the project
  • Fichiers de configuration pour le package qui doivent être inclus dans le projet, mais ne nécessitent aucune modification spécifique au projetConfiguration files for the package that need to be included in the project but don't need any project-specific changes

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.Content files are included in a package using the <files> element, specifying the content folder in the target attribute. Toutefois, ces fichiers sont ignorés quand le package est installé dans un projet utilisant PackageReference, qui utilise à la place l’élément <contentFiles>.However, such files are ignored when the package is installed in a project using PackageReference, which instead uses the <contentFiles> element.

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.For maximum compatibility with consuming projects, a package ideally specifies the content files in both elements.

Utilisation de l’élément files pour les fichiers de contenuUsing the files element for content files

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.For content files, simply use the same format as for assembly files, but specify content as the base folder in the target attribute as shown in the following examples.

Fichiers de contenu de baseBasic content files

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épertoiresContent files with directory structure

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 FrameworkContent file specific to a target 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 nomContent file copied to a folder with dot in name

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 :In this case, NuGet sees that the extension in target does not match the extension in src and thus treats that part of the name in target as a folder:

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 extensionsContent files without extensions

Pour inclure les fichiers sans extension, utilisez les caractères génériques * ou ** :To include files without an extension, use the * or ** wildcards:

Source file:
    flags\installed

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

Packaged result:
    flags\installed

Fichiers de contenu avec chemin complet et cible complèteContent files with deep path and deep target

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 :In this case, because the file extensions of the source and target match, NuGet assumes that the target is a file name and not a folder:

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 packageRenaming a content file in the 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 fichiersExcluding files

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 contenuUsing the contentFiles element for content files

NuGet 4.0 + avec PackageReferenceNuGet 4.0+ with 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.By default, a package places content in a contentFiles folder (see below) and nuget pack included all files in that folder using default attributes. Dans ce cas, il n’est pas du tout nécessaire d’inclure un nœud contentFiles dans le fichier .nuspec.In this case it's not necessary to include a contentFiles node in the .nuspec at all.

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.To control which files are included, the <contentFiles> element specifies is a collection of <files> elements that identify the exact files include.

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 :These files are specified with a set of attributes that describe how they should be used within the project system:

AttributAttribute DescriptionDescription
includeinclude (Obligatoire) Emplacement du ou des fichiers à inclure, soumis à des exclusions définies par l’attribut exclude.(Required) The location of the file or files to include, subject to exclusions specified by the exclude attribute. Le chemin est relatif au fichier .nuspec sauf si un chemin absolu est spécifié.The path is relative to the .nuspec file unless an absolute path is specified. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
excludeexclude Liste de fichiers ou de modèles de fichiers séparés par un point-virgule à exclure de l’emplacement src.A semicolon-delimited list of files or file patterns to exclude from the src location. Le caractère générique * est autorisé et le caractère générique double ** implique une recherche de dossier récursive.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
buildActionbuildAction 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.The build action to assign to the content item for MSBuild, such as Content, None, Embedded Resource, Compile, etc. The default is Compile.
copyToOutputcopyToOutput Valeur booléenne indiquant si les éléments de contenu doivent être copiés dans le dossier de sortie de la génération (ou de la publication).A Boolean indicating whether to copy content items to the build (or publish) output folder. La valeur par défaut est false.The default is false.
flattenflatten 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).A Boolean indicating whether to copy content items to a single folder in the build output (true), or to preserve the folder structure in the package (false). Cet indicateur fonctionne uniquement lorsque l’indicateur copyToOutput est défini sur true.This flag only works when copyToOutput flag is set to true. La valeur par défaut est false.The default is false.

Lors de l’installation d’un package, NuGet applique les éléments enfants de <contentFiles> de haut en bas.When installing a package, NuGet applies the child elements of <contentFiles> from top to bottom. Si plusieurs entrées correspondent au même fichier, toutes les entrées sont appliquées.If multiple entries match the same file then all entries are applied. L’entrée supérieure remplace les entrées inférieures s’il existe un conflit pour le même attribut.The top-most entry overrides the lower entries if there is a conflict for the same attribute.

Structure de dossiers de packagePackage folder structure

Le projet de package doit structurer le contenu à l’aide du modèle suivant :The package project should structure content using the following pattern:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages peut être cs, vb, fs, any, ou l’équivalent en minuscules d’un élément $(ProjectLanguage) donné.codeLanguages may be cs, vb, fs, any, or the lowercase equivalent of a given $(ProjectLanguage)
  • TxM est n’importe quel moniker du Framework cible légal pris en charge par NuGet (consultez Versions cibles de .NET Framework).TxM is any legal target framework moniker that NuGet supports (see Target frameworks).
  • Toute structure de dossiers peut être ajoutée à la fin de cette syntaxe.Any folder structure may be appended to the end of this syntax.

Par exemple :For example:

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 :Empty folders can use . to opt out of providing content for certain combinations of language and TxM, for example:

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

Exemple de section contentFilesExample contentFiles section

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

Exemples de fichiers NuSpecExample nuspec files

Fichier .nuspec simple qui ne spécifie pas de dépendances ni de fichiersA simple .nuspec that does not specify dependencies or files

<?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épendancesA .nuspec with dependencies

<?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 fichiersA .nuspec with files

<?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 FrameworkA .nuspec with framework assemblies

<?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 :In this example, the following are installed for specific project targets:

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