Références de package (PackageReference) dans les fichiers projetPackage references (PackageReference) in project files

Les références de package utilisent le nœud PackageReference pour gérer les dépendances NuGet directement dans les fichiers projet, et non un fichier packages.config séparé.Package references, using the PackageReference node, manage NuGet dependencies directly within project files (as opposed to a separate packages.config file). L’utilisation de PackageReference n’affecte pas les autres aspects de NuGet. Par exemple, les paramètres des fichiers NuGet.config (notamment les sources de package) continuent d’être appliqués, comme expliqué dans Configuration du comportement de NuGet.Using PackageReference, as it's called, doesn't affect other aspects of NuGet; for example, settings in NuGet.config files (including package sources) are still applied as explained in Configuring NuGet Behavior.

Avec PackageReference, vous pouvez aussi utiliser des conditions MSBuild pour choisir des références de package par version cible de .NET Framework, configuration, plateforme ou autre type de regroupement.With PackageReference, you can also use MSBuild conditions to choose package references per target framework, configuration, platform, or other groupings. Elle permet également de mieux contrôler les dépendances et les flux de contenu.It also allows for fine-grained control over dependencies and content flow. Pour plus d’informations, consultez Commandes pack et restore NuGet comme cibles MSBuild.(See For more details NuGet pack and restore as MSBuild targets.)

Par défaut, PackageReference est utilisé pour les projets .NET Core, les projets .NET Standard et les projets UWP ciblant Windows 10 Build 15063 (Creators Update) et version ultérieure, excepté les projets C++ UWP.By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. Les projets .NET Framework prennent en charge PackageReference, mais utilisent par défaut packages.config..NET Framework projects support PackageReference, but currently default to packages.config. Pour utiliser PackageReference, migrez les dépendances de packages.config dans votre fichier projet, puis supprimez packages.config.To use PackageReference, migrate the dependencies from packages.config into your project file, then remove packages.config.

Ajout d’un PackageReferenceAdding a PackageReference

Ajoutez une dépendance dans votre fichier projet en utilisant la syntaxe suivante :Add a dependency in your project file using the following syntax:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Contrôle des versions des dépendancesControlling dependency version

Pour spécifier la version d’un package, la convention est la même que pour packages.config :The convention for specifying the version of a package is the same as when using packages.config:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Dans l’exemple ci-dessus, 3.6.0 correspond à n’importe quelle version supérieure ou égale à 3.6.0, avec une préférence pour la version la plus ancienne, comme décrit dans Gestion des versions de package.In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on Package versioning.

Utilisation de PackageReference pour un projet sans PackageReferencesUsing PackageReference for a project with no PackageReferences

Avancé : Si vous n’avez aucun package installé dans un projet (aucune PackageReferences dans le fichier projet et aucun fichier packages.config), mais que vous souhaitez restaurer le projet en tant que style PackageReference, vous pouvez définir une propriété de projet RestoreProjectStyle avec la valeur PackageReference dans votre fichier projet.Advanced: If you have no packages installed in a project (no PackageReferences in project file and no packages.config file), but want the project to be restored as PackageReference style, you can set a Project property RestoreProjectStyle to PackageReference in your project file.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

Cela peut être utile si vous référencez des projets qui sont de style PackageReference (projets csproj ou de style SDK existants).This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). Cela permet aux packages auxquels ces projets font référence d’être référencés « transitivement » par votre projet.This will enable packages that those projects refer to, to be "transitively" referenced by your project.

Versions flottantesFloating Versions

Les versions flottantes peuvent être utilisées avec PackageReference :Floating versions are supported with PackageReference:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta*" />
    <!-- ... -->
</ItemGroup>

Contrôle des ressources de dépendanceControlling dependency assets

Vous pouvez utiliser une dépendance uniquement comme un atelier de développement et ne pas l’exposer aux projets qui utilisent votre package.You might be using a dependency purely as a development harness and might not want to expose that to projects that will consume your package. Dans ce scénario, vous pouvez utiliser les métadonnées PrivateAssets pour contrôler ce comportement.In this scenario, you can use the PrivateAssets metadata to control this behavior.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Les balises de métadonnées suivantes permettent de contrôler les ressources de dépendance :The following metadata tags control dependency assets:

BaliseTag DescriptionDescription Valeur par défautDefault Value
IncludeAssetsIncludeAssets Ces ressources sont consommées.These assets will be consumed allall
ExcludeAssetsExcludeAssets Ces ressources ne sont pas consommées.These assets will not be consumed nonenone
PrivateAssetsPrivateAssets Ces ressources sont consommées, mais ne sont pas acheminées vers le projet parent.These assets will be consumed but won't flow to the parent project contentfiles;analyzers;buildcontentfiles;analyzers;build

Les valeurs autorisées pour ces balises sont les suivantes (les valeurs multiples doivent être séparées par un point-virgule, à l’exception de all et de none qui doivent s’afficher seules) :Allowable values for these tags are as follows, with multiple values separated by a semicolon except with all and none which must appear by themselves:

ValueValue DescriptionDescription
compilecompile Contenu du dossier lib et contrôles permettant de déterminer si votre projet peut être compilé avec les assemblys dans le dossierContents of the lib folder and controls whether your project can compile against the assemblies within the folder
runtimeruntime Contenu des dossiers lib et runtimes contrôles permettant de déterminer si ces assemblys seront copiés vers le répertoire de sortie de buildContents of the lib and runtimes folder and controls whether these assemblies will be copied out to the build output directory
contentFilescontentFiles Contenu du dossier contentfilesContents of the contentfiles folder
buildbuild Propriétés et cibles du dossier buildProps and targets in the build folder
analyzersanalyzers Analyseurs .NET.NET analyzers
nativenative Contenu du dossier nativeContents of the native folder
nonenone Aucune des valeurs ci-dessus n’est utilisée.None of the above are used.
allall Toutes les valeurs ci-dessus sont utilisées (sauf none)All of the above (except none)

Dans l’exemple suivant, tout (à l’exception des fichiers de contenu du package) est consommé par le projet et tout (à l’exception des fichiers de contenu et des analyseurs) est acheminé vers le projet parent.In the following example, everything except the content files from the package would be consumed by the project and everything except content files and analyzers would flow to the parent project.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets>
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Étant donné que build n’est pas inclus dans PrivateAssets, les cibles et les propriétés sont acheminées vers le projet parent.Note that because build is not included with PrivateAssets, targets and props will flow to the parent project. Imaginons, par exemple, que la référence ci-dessus soit utilisée dans un projet qui crée un package NuGet appelé AppLogger.Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger peut consommer les cibles et les propriétés de Contoso.Utility.UsefulStuff, tout comme les projets peuvent consommer AppLogger.AppLogger can consume the targets and props from Contoso.Utility.UsefulStuff, as can projects that consume AppLogger.

Ajout d’une condition PackageReferenceAdding a PackageReference condition

Vous pouvez utiliser une condition pour contrôler si un package doit être inclus, ainsi que l’endroit où les conditions peuvent utiliser une variable MSBuild ou une variable définie dans le fichier de propriétés ou de cibles.You can use a condition to control whether a package is included, where conditions can use any MSBuild variable or a variable defined in the targets or props file. Toutefois, à l’heure actuelle, seule la variable TargetFramework est prise en charge.However, at presently, only the TargetFramework variable is supported.

Par exemple, supposons que vous souhaitiez cibler netstandard1.4 et net452, mais que l’une de vos dépendances ne s’applique qu’à net452.For example, say you're targeting netstandard1.4 as well as net452 but have a dependency that is applicable only for net452. Dans ce cas, il n’est pas souhaitable qu’un projet netstandard1.4 utilise votre package pour ajouter cette dépendance inutile.In this case you don't want a netstandard1.4 project that's consuming your package to add that unnecessary dependency. Pour éviter cela, spécifiez une condition sur PackageReference de la façon suivante :To prevent this, you specify a condition on the PackageReference as follows:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Dans un package créé à l’aide de ce projet, le fichier Newtonsoft.Json est inclus en tant que dépendance uniquement pour une cible net452 :A package built using this project will show that Newtonsoft.Json is included as a dependency only for a net452 target:

Résultat de l’application d’une condition à PackageReference avec VS2017

Les conditions peuvent également être appliquées au niveau d’un ItemGroup, à tous les éléments enfants PackageReference :Conditions can also be applied at the ItemGroup level and will apply to all children PackageReference elements:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Verrouillage des dépendancesLocking dependencies

Cette fonctionnalité est disponible avec NuGet 4.9 ou ultérieur, et avec Visual Studio 2017 15.9 ou ultérieur.This feature is available with NuGet 4.9 or above and with Visual Studio 2017 15.9 or above.

L’entrée de la restauration NuGet est un ensemble de références de package provenant du fichier de projet (dépendances de niveau supérieur ou directes). La sortie est une fermeture complète de toutes les dépendances de package, notamment les dépendances transitives.Input to NuGet restore is a set of Package References from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet s’efforce toujours de produire la même fermeture complète des dépendances de package si la liste PackageReference d’entrée ne change pas.NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. Toutefois, tous les scénarios ne s’y prêtent pas.However, there are some scenarios where it is unable to do so. Par exemple :For example:

  • Quand vous utilisez des versions flottantes comme <PackageReference Include="My.Sample.Lib" Version="4.*"/>.When you use floating versions like <PackageReference Include="My.Sample.Lib" Version="4.*"/>. L’intention ici est de flotter vers la dernière version à chaque restauration de package. Mais dans certains scénarios, les utilisateurs peuvent exiger le verrouillage du graphe à une version récente donnée et son flottement vers une version ultérieure, si celle-ci est disponible, à la suite d’un mouvement explicite.While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture.

  • Une version plus récente du package correspondant aux exigences de version de PackageReference est publiée.A newer version of the package matching PackageReference version requirements is published. Par exemple,E.g.

    • Premier jour : Vous spécifiez <PackageReference Include="My.Sample.Lib" Version="4.0.0"/>, mais les versions disponibles sur les dépôts NuGet sont 4.1.0, 4.2.0 et 4.3.0.Day 1: if you specified <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> but the versions available on the NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. Dans ce cas, NuGet résout la version en 4.1.0 (la plus proche de la version minimale).In this case, NuGet would have resolved to 4.1.0 (nearest minimum version)

    • Deuxième jour : La version 4.0.0 est publiée.Day 2: Version 4.0.0 gets published. NuGet trouve désormais la correspondance exacte et commence à résoudre la version en 4.0.0.NuGet will now find the exact match and start resolving to 4.0.0

  • Une version de package donnée est supprimée du dépôt.A given package version is removed from the repository. Bien que nuget.org n’autorise pas la suppression de packages, d’autres dépôts de packages n’ont pas cette contrainte.Though nuget.org does not allow package deletions, not all package repositories have this constraints. NuGet trouve donc la meilleure correspondance quand la version supprimée rend impossible la résolution.This results in NuGet finding the best match when it cannot resolve to the deleted version.

Activation du fichier de verrouillageEnabling lock file

Pour rendre persistante la fermeture complète des dépendances de package, vous pouvez choisir d’utiliser la fonctionnalité de fichier de verrouillage en définissant la propriété MSBuild RestorePackagesWithLockFile pour votre projet :In order to persist the full closure of package dependencies you can opt-in to the lock file feature by setting the MSBuild property RestorePackagesWithLockFile for your project:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

Si cette propriété est définie, la restauration NuGet génère un fichier de verrouillage (packages.lock.json) au niveau du répertoire racine du projet qui liste toutes les dépendances du package.If this property is set, NuGet restore will generate a lock file - packages.lock.json file at the project root directory that lists all the package dependencies.

Notes

Quand un projet a un fichier packages.lock.json dans son répertoire racine, le fichier de verrouillage est toujours utilisé avec la restauration, même si la propriété RestorePackagesWithLockFile n’est pas définie.Once a project has packages.lock.json file in its root directory, the lock file is always used with restore even if the property RestorePackagesWithLockFile is not set. Une autre façon de choisir cette fonctionnalité consiste à créer un fichier packages.lock.json vide factice dans le répertoire racine du projet.So another way to opt-in to this feature is to create a dummy blank packages.lock.json file in the project's root directory.

Comportement de restore avec fichier de verrouillagerestore behavior with lock file

Si un fichier de verrouillage est présent pour le projet, NuGet utilise ce fichier de verrouillage pour exécuter restore.If a lock file is present for project, NuGet uses this lock file to run restore. NuGet effectue une vérification rapide pour voir si les dépendances de package ont changé, comme indiqué dans le fichier projet (ou les fichiers des projets dépendants). Si aucun changement n’est détecté, il restaure simplement les packages mentionnés dans le fichier de verrouillage.NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. Les dépendances de package ne sont pas réévaluées.There is no re-evaluation of package dependencies.

Si NuGet détecte un changement dans les dépendances définies indiquées dans le ou les fichiers projet, il réévalue le graphe du package et met à jour le fichier de verrouillage pour refléter la nouvelle fermeture de package du projet.If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project.

Dans CI/CD et d’autres scénarios où vous ne voulez pas changer les dépendances de package à la volée, vous pouvez définir lockedmode avec la valeur true :For CI/CD and other scenarios, where you would not want to change the package dependencies on the fly, you can do so by setting the lockedmode to true:

Pour dotnet.exe, exécutez :For dotnet.exe, run:

> dotnet.exe restore --locked-mode

Pour msbuild.exe, exécutez :For msbuild.exe, run:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

Vous pouvez également définir cette propriété MSBuild conditionnelle dans votre fichier projet :You may also set this conditional MSBuild property in your project file:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

Si le mode verrouillé est true, soit la restauration restaure les packages exacts figurant dans la liste du fichier de verrouillage, soit elle échoue si vous avez mis à jour les dépendances de package définies pour le projet une fois le fichier de verrouillage créé.If locked mode is true, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created.

Intégrer le fichier de verrouillage dans votre dépôt sourceMake lock file part of your source repository

Si vous générez un exécutable d’application et que le projet en question se trouve à la début de la chaîne de dépendance, archivez le fichier de verrouillage dans le dépôt de code source pour que NuGet puisse l’utiliser durant la restauration.If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore.

Toutefois, si votre projet est un projet de bibliothèque que vous ne prévoyez pas de distribuer ou un projet de code commun dont dépendent d’autres projets, n’archivez pas le fichier de verrouillage dans le cadre de votre code source.However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you should not check in the lock file as part of your source code. Le fait de conserver le fichier de verrouillage ne pose aucun risque. Toutefois, vous ne pouvez pas utiliser les dépendances de package verrouillées pour le projet de code commun, qui figurent dans la liste du fichier de verrouillage, durant la restauration/génération d’un projet qui dépend de ce projet de code commun.There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project.

Par exemple :Eg.

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Si ProjectA a une dépendance à un PackageX version 2.0.0 et qu’il référence également ProjectB qui dépend de PackageX version 1.0.0, le fichier de verrouillage pour ProjectB liste une dépendance à PackageX version 1.0.0.If ProjectA has a dependency on a PackageX version 2.0.0 and also references ProjectB that depends on PackageX version 1.0.0, then the lock file for ProjectB will list a dependency on PackageX version 1.0.0. Toutefois, quand ProjectA est généré, son fichier de verrouillage contient une dépendance à PackageX version 2.0.0 et non à 1.0.0 (qui figure dans la liste du fichier de verrouillage pour ProjectB).However, when ProjectA is built, its lock file will contain a dependency on PackageX version 2.0.0 and not 1.0.0 as listed in the lock file for ProjectB. Le fichier de verrouillage d’un projet de code commun a donc peu de contrôle sur les packages résolus pour les projets qui en dépendent.Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it.

Extensibilité du fichier de verrouillageLock file extensibility

Vous pouvez contrôler divers comportements de restauration avec un fichier de verrouillage, comme décrit ci-dessous :You can control various behaviors of restore with lock file as described below:

OptionOption Option MSBuild équivalenteMSBuild equivalent option
--use-lock-file Utilisation par les démarrages d’un fichier de verrouillage pour un projet.Bootstraps use of lock file for a project. Vous pouvez également définir la propriété RestorePackagesWithLockFile dans le fichier projet.You can alternatively set RestorePackagesWithLockFile property in the project file
--locked-mode Active le mode verrouillé pour la restauration.Enables locked mode for restore. Ceci est utile dans les scénarios CI/CD dans lesquels vous souhaitez obtenir les builds renouvelables.This is useful in CI/CD scenarios where you would like to get the repeatable builds. Vous pouvez obtenir le même résultat en définissant la propriété MSBuild RestoreLockedMode avec la valeur true.This can be also by setting the RestoreLockedMode MSBuild property to true
--force-evaluate Cette option est utile avec des packages dont la version flottante est définie dans le projet.This option is useful with packages with floating version defined in the project. Par défaut, la restauration NuGet ne met pas automatiquement à jour la version du package à chaque restauration, sauf si vous exécutez la restauration avec l’option --force-evaluate.By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with --force-evaluate option.
--lock-file-path Définit un emplacement de fichier de verrouillage personnalisé pour un projet.Defines a custom lock file location for a project. Vous pouvez obtenir le même résultat en définissant la propriété MSBuild NuGetLockFilePath.This can be also achieved by setting the MSBuild property NuGetLockFilePath. Par défaut, NuGet prend en charge packages.lock.json au niveau du répertoire racine.By default, NuGet supports packages.lock.json at the root directory. Si vous avez plusieurs projets dans le même répertoire, NuGet prend en charge le fichier de verrouillage packages.<project_name>.lock.json spécifique au projet.If you have multiple projects in the same directory, NuGet supports project specific lock file packages.<project_name>.lock.json