PackageReference dans les fichiers projet

Les références de package utilisent des éléments MSBuild <PackageReference> pour spécifier des dépendances de package NuGet directement dans les fichiers projet, et non un fichier packages.config séparé. L’utilisation de PackageReference n’a pas d’impact sur les autres aspects de NuGet. Par exemple, les paramètres des fichiers NuGet.Config (notamment les sources de packages) continuent d’être appliqués, comme cela est expliqué dans Configurations courantes de NuGet.

Avec PackageReference, vous pouvez aussi utiliser des conditions MSBuild pour choisir des références de package par version cible de .NET Framework ou autre type de regroupement. Elle permet également de mieux contrôler les dépendances et les flux de contenu. Pour plus d’informations, consultez Commandes pack et restore NuGet comme cibles MSBuild.

Prise en charge de type de projet

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. Les projets .NET Framework prennent en charge PackageReference, mais utilisent par défaut packages.config. Pour utiliser PackageReference, migrez les dépendances de packages.config dans votre fichier projet, puis supprimez packages.config.

Les applications ASP.NET ciblant le .NET Framework incluent uniquement une prise en charge limitée pour PackageReference. Les types de projets C++ et JavaScript ne sont pas pris en charge.

Ajout d’un PackageReference

Ajoutez une dépendance dans votre fichier projet en utilisant la syntaxe suivante :

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

Contrôle des versions des dépendances

Pour spécifier la version d’un package, la convention est la même que pour 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 >= 3.6.0, avec une préférence pour la version la plus ancienne, comme décrit dans Gestion des versions de package.

Utilisation de PackageReference pour un projet sans dépendances de package

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.

<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). Cela permet aux packages auxquels ces projets font référence d’être référencés « transitivement » par votre projet.

PackageReference et sources

Dans les projets PackageReference, les versions de dépendance transitive sont résolues au moment de la restauration. Par conséquent, dans les projets PackageReference, toutes les sources doivent être disponibles pour toutes les restaurations.

Versions flottantes

Les versions flottantes peuvent être utilisées avec 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épendance

Vous pouvez utiliser une dépendance uniquement comme un atelier de développement et ne pas l’exposer aux projets qui utilisent votre package. Dans ce scénario, vous pouvez utiliser les métadonnées PrivateAssets pour contrôler ce comportement.

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

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

<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</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. Imaginons, par exemple, que la référence ci-dessus soit utilisée dans un projet qui crée un package NuGet appelé AppLogger. AppLogger peut consommer les cibles et les propriétés de Contoso.Utility.UsefulStuff, tout comme les projets peuvent consommer AppLogger.

Ajout d’une condition PackageReference

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. Toutefois, à l’heure actuelle, seule la variable TargetFramework est prise en charge.

Par exemple, supposons que vous souhaitiez cibler netstandard1.4 et net452, mais que l’une de vos dépendances ne s’applique qu’à net452. Dans ce cas, il n’est pas souhaitable qu’un projet netstandard1.4 utilise votre package pour ajouter cette dépendance inutile. Pour éviter cela, spécifiez une condition sur PackageReference de la façon suivante :

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

Les conditions peuvent également être appliquées au niveau d’un ItemGroup, à tous les éléments enfants PackageReference :

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

GeneratePathProperty

Cette fonctionnalité est disponible avec NuGet 5.0 ou ultérieur, et avec Visual Studio 2019 16.0 ou ultérieur.

Il est parfois souhaitable de référencer des fichiers dans un package à partir d’une cible MSBuild. Dans les projets basés sur packages.config, les packages sont installés dans un dossier relatif au fichier projet. Toutefois, dans PackageReference, les packages sont consommés à partir du dossier global-packages, qui peut varier d’un ordinateur à l’autre.

Pour combler cet écart, NuGet a introduit une propriété qui pointe vers l’emplacement à partir duquel le package sera consommé.

Exemple :

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

En plus, NuGet génère automatiquement des propriétés pour les packages contenant un dossier d’outils.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

Les propriétés MSBuild et les identités de package n’ont pas les mêmes restrictions. L’identité du package doit donc être modifiée en nom convivial MSBuild, précédée du mot Pkg. Pour vérifier le nom exact de la propriété générée, examinez le fichier nuget.g.props généré.

Alias PackageReference

Dans certains cas rares, différents packages contiennent des classes dans le même espace de noms. À partir de NuGet 5.7 et Visual Studio 2019 Update 7, équivalent à ProjectReference, PackageReference prend en charge Aliases. Par défaut, aucun alias n’est fourni. Lorsqu’un alias est spécifié, tous les assemblys provenant du package annoté doivent être référencés avec un alias.

Vous pouvez examiner des exemples d’utilisation sur NuGet\Samples

Dans le fichier projet, spécifiez les alias comme suit :

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

et dans le code, utilisez-le comme suit :

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

Avertissements et erreurs Nuget

Cette fonctionnalité est disponible avec NuGet 4.3 ou ultérieur, et avec Visual Studio 2017 15.3 ou ultérieur.

Pour de nombreux packs et scénarios de restauration, tous les avertissements et erreurs NuGet sont codés et commencent par NU****. Tous les avertissements et erreurs NuGet sont répertoriés dans la documentation de référence.

NuGet suit les propriétés d’avertissement suivantes :

• TreatWarningsAsErrors considère tous les avertissements comme des erreurs
• WarningsAsErrors, considère certains avertissements comme des erreurs
• NoWarn, masque certains avertissements, à l’échelle du projet ou à l’échelle du package.

Exemples :

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

Suppression des avertissements NuGet

Bien qu’il soit recommandé de résoudre tous les avertissements NuGet pendant vos opérations de pack et de restauration, dans certaines situations, la suppression de ces avertissements est justifiée. Pour supprimer un avertissement à l’échelle du projet, procédez comme suit :

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

Parfois, les avertissements s’appliquent uniquement à un certain package dans le graphe. Il est possible de choisir de supprimer cet avertissement de manière plus sélective en ajoutant un NoWarn sur l’élément PackageReference.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Suppression des avertissements de package NuGet dans Visual Studio

Dans Visual Studio, vous pouvez également supprimer des avertissements via l’IDE.

Verrouillage des dépendances

Cette fonctionnalité est disponible avec NuGet 4.9 ou ultérieur, et avec Visual Studio 2017 15.9 ou ultérieur.

L’entrée de la restauration NuGet est un ensemble d’éléments de PackageReference provenant du fichier 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. 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. Toutefois, tous les scénarios ne s’y prêtent pas. Par exemple :

• Quand vous utilisez des versions flottantes comme <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.

• Une version plus récente du package correspondant aux exigences de version de PackageReference est publiée. Par exemple,

  • 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. Dans ce cas, NuGet résout la version en 4.1.0 (la plus proche de la version minimale).

  • Deuxième jour : La version 4.0.0 est publiée. NuGet trouve désormais la correspondance exacte et commence à résoudre la version en 4.0.0.

• Une version de package donnée est supprimée du dépôt. Bien que nuget.org n’autorise pas la suppression de packages, d’autres dépôts de packages n’ont pas cette contrainte. NuGet trouve donc la meilleure correspondance quand la version supprimée rend impossible la résolution.

Activation du fichier de verrouillage

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 :

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

Comportement de restore avec fichier de verrouillage

Si un fichier de verrouillage est présent pour le projet, NuGet utilise ce fichier de verrouillage pour exécuter 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. Les dépendances de package ne sont pas réévaluées.

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.

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 :

Pour dotnet.exe, exécutez :

> dotnet.exe restore --locked-mode

Pour msbuild.exe, exécutez :

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

Vous pouvez également définir cette propriété MSBuild conditionnelle dans votre fichier projet :

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

Intégrer le fichier de verrouillage dans votre dépôt source

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.

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

par exemple

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. Toutefois, lorsque ProjectA est généré, son fichier de verrouillage contient une dépendance à PackageX version 2.0.0 et non à 1.0.0 comme référencé dans le fichier de verrouillage pour 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.

Extensibilité du fichier de verrouillage

Vous pouvez contrôler divers comportements de restauration avec un fichier de verrouillage, comme décrit ci-dessous :

Programme de résolution des dépendances NuGet

Le programme de résolution des dépendances NuGet suit les 4 règles décrites dans le document de résolution des dépendances.

Pour améliorer les performances et l’extensibilité de l’opération de restauration, l’algorithme de restauration a été réécrit dans la version 6.12. À compter de la version 6.12, le nouvel algorithme de restauration est activé par défaut pour tous les projets PackageReference. Bien que le nouvel algorithme de restauration soit fonctionnellement équivalent au précédent, comme avec n’importe quel logiciel, des bogues sont possibles. Pour revenir à l’implémentation précédente, définissez la propriété MSBuild RestoreUseLegacyDependencyResolver sur true.

Si vous rencontrez des échecs de restauration dans la version 6.12, .NET 9 ou 17.12, qui n’étaient pas reproductibles dans les versions antérieures, veuillez créer un problème sur GitHub. Toutes les différences entre les anciens algorithmes et les nouveaux peuvent avoir des impacts différents, notamment pendant la compilation ou au moment de l’exécution. Il est également possible que les modifications n’entraînent pas d’échecs, mais que différentes versions des packages soient restaurées. Si vous pensez que des modifications pourraient vous affecter, voici les étapes que vous pouvez suivre pour vérifier si les modifications apportées à l’algorithme de restauration NuGet sont la cause racine.

La restauration écrit ses résultats dans le répertoire MSBuildProjectExtensionsPath. Vous pouvez ainsi comparer les algorithmes nouveaux et anciens pour trouver les différences. Il s’agit généralement du dossier obj de votre build. Vous pouvez utiliser msbuild.exe ou dotnet.exe pour les étapes suivantes.

1. Supprimez le dossier obj de votre projet.
2. Exécutez msbuild -t:restore
3. Enregistrez le contenu de l’emplacement obj, indiquant qu’il s’agit du comportement new.
4. Exécutez msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"
5. Enregistrez le contenu de l’emplacement obj, indiquant qu’il s’agit du comportement legacy.
6. Comparez les fichiers des deux répertoires, en particulier project.assets.json. Les outils qui peuvent mettre en évidence les différences sont particulièrement utiles pour cela (par exemple, dans Visual Studio Code, ouvrez les deux fichiers et utilisez le menu de bouton droit « Sélectionner pour comparer » et « Comparer à la sélection »)

Si vous suivez la méthode ci-dessus, il devrait y avoir exactement 1 différence entre les fichiers project.assets.json :

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

Si vous trouvez d’autres différences, créez un problème sur GitHub avec tous les détails.

AssetTargetFallback

La propriété AssetTargetFallback vous permet de spécifier des versions de framework compatibles supplémentaires pour les projets que les références de projet et les packages NuGet consomment.

Si vous spécifiez une dépendance de package à l’aide de PackageReference, mais que ce package ne contient pas de ressources compatibles avec la version cible de .Net Framework de votre projet, la propriété AssetTargetFallback entre en jeu. La compatibilité du package référencé est vérifiée à nouveau à l’aide de chaque framework cible spécifié dans AssetTargetFallback. Lorsqu’un project ou un package est référencé via AssetTargetFallback, l’avertissement NU1701 est déclenché.

Reportez-vous au tableau suivant pour vois comment AssetTargetFallback affecte la compatibilité.

Plusieurs frameworks peuvent être spécifiés à l’aide de ; en tant que séparateur. Pour ajouter une framework de secours, vous pouvez effectuer les opérations suivantes :

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

Vous pouvez laisser $(AssetTargetFallback) si vous souhaitez remplacer, au lieu d’ajouter aux valeurs existantes AssetTargetFallback.