Partage via

Pack NuGet et restauration en tant que cibles MSBuild

  • Article

NuGet 4.0+

Avec le format PackageReference , NuGet 4.0+ peut stocker toutes les métadonnées du manifeste directement dans un fichier projet, au lieu d’utiliser un .nuspec fichier distinct.

Avec MSBuild 15.1+, NuGet est également un citoyen MSBuild de première classe avec les cibles pack et restore comme décrit ci-dessous. Ces cibles vous permettent d’utiliser NuGet comme vous utiliseriez toute autre tâche MSBuild ou cible. Pour obtenir des instructions sur la création d’un NuGet package à l’aide de MSBuild, consultez Créer un package NuGet à l’aide de MSBuild. (Pour NuGet 3.x et les versions antérieures, vous utilisez plutôt les commandes pack et restaurer via le CLI NuGet.)

Ordre de génération des cibles

Étant donné que pack et restore sont des cibles MSBuild, vous pouvez y accéder pour améliorer votre flux de travail. Par exemple, supposons que vous souhaitez copier votre package sur un partage réseau après compression. Pour ce faire, ajoutez le code suivant dans votre fichier projet :

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

De même, vous pouvez écrire une tâche MSBuild, écrire votre propre cible et consommer les propriétés NuGet dans la tâche MSBuild.

Remarque

$(OutputPath) est relatif et attend que vous exécutez la commande à partir de la racine du projet.

Cible pack

Pour les projets .NET qui utilisent le format PackageReference, l’utilisation d’entrées du fichier projet msbuild -t:pack à utiliser lors de la création d’un package NuGet.

Le tableau suivant décrit les propriétés MSBuild qui peuvent être ajoutées à un fichier projet dans le premier nœud <PropertyGroup>. Vous pouvez effectuer ces modifications facilement dans Visual Studio 2017 et versions ultérieures en cliquant avec le bouton droit sur le projet et en sélectionnant Modifier {nom_projet} dans le menu contextuel. Pour des raisons pratiques, le tableau est organisé selon la propriété équivalente dans un fichier .nuspec.

Remarque

Les propriétés Owners et Summary de .nuspec ne sont pas prises en charge par MSBuild.

Attribut/ Valeur nuspec PropriétéMSBuild Par défaut Notes
Id PackageId $(AssemblyName) $(AssemblyName) à partir de MSBuild
Version PackageVersion Version Il s’agit d’une compatibilité semver, par exemple 1.0.0, 1.0.0-betaou 1.0.0-beta-00345. Si elle n’est pas définie, la valeur par défaut est Version.
VersionPrefix VersionPrefix empty Le paramètre PackageVersion écrase VersionPrefix
VersionSuffix VersionSuffix empty Le paramètre PackageVersion écrase VersionSuffix
Authors Authors Nom de l’utilisateur actuel Une liste d'auteurs de packages séparés par des points-virgules, correspondant aux identités sur nuget.org. Ils sont affichés dans la Galerie NuGet sur nuget.org et sont utilisés pour croiser les références des packages des mêmes auteurs.
Owners S/O Non présent dans nuspec
Title Title $(PackageId) Titre convivial du package, généralement utilisé dans les affichages de l’IU comme sur nuget.org et dans le gestionnaire de package de Visual Studio.
Description Description « Description du package » Description longue de l'assembly. Si PackageDescription n’est pas spécifié, cette propriété est également utilisée comme description du package.
Copyright Copyright empty Détails de copyright pour le package.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Valeur booléenne qui spécifie si le client doit inviter l’utilisateur à accepter la licence du package avant d’installer le package.
license PackageLicenseExpression empty Correspond à <license type="expression">. Consultez Empaquetage d’une expression de licence ou d’un fichier de licence.
license PackageLicenseFile empty Chemin d'accès à un fichier de licence dans le package si vous utilisez une licence personnalisée ou une licence à laquelle aucun identifiant SPDX n'a été attribué. Vous devez empaquetons explicitement le fichier de licence référencé. Correspond à <license type="file">. Consultez Empaquetage d’une expression de licence ou d’un fichier de licence.
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl est déconseillé. Utilisez plutôt PackageLicenseExpression ou PackageLicenseFile.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Chemin d’accès à une image dans le package à utiliser comme icône de package. Vous devez ajouter explicitement le fichier image d’icône référencé. Pour plus d’informations, consultez Empaqueter un fichier image d’icône et icon des métadonnées.
IconUrl PackageIconUrl empty PackageIconUrl est déprécié en faveur de PackageIcon. Toutefois, pour une expérience de niveau inférieur optimale, vous devez spécifier PackageIconUrl en plus de PackageIcon.
Readme PackageReadmeFile empty Vous devez empaqueté explicitement le fichier lisez-moi référencé.
Tags PackageTags empty Liste de balises séparées par un point-virgule qui désigne le package.
ReleaseNotes PackageReleaseNotes empty Notes de publication du package.
Repository/Url RepositoryUrl empty URL du référentiel utilisée pour cloner ou récupérer le code source. Exemple : https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType empty Type de référentiel. Exemples : git (par défaut), tfs.
Repository/Branch RepositoryBranch empty Informations de branche de référentiel facultatives. RepositoryUrl doit également être spécifié pour que cette propriété soit incluse. Exemple : master (NuGet 4.7.0+).
Repository/Commit RepositoryCommit empty Validation ou ensemble de modifications de référentiel facultatif pour indiquer la source sur laquelle le package a été généré. RepositoryUrl doit également être spécifié pour que cette propriété soit incluse. Exemple : 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Indique l’utilisation prévue du package. Les types de package utilisent le même format que les ID de package et sont délimités par ;. Les types de packages peuvent être versionnés en ajoutant une chaîne , et une chaîne Version. Consultez Définir un type de package NuGet(NuGet 3.5.0+).
Summary Non pris en charge

entrées de cible pack

Propriété Description
IsPackable Valeur booléenne qui spécifie si le projet peut être compressé. La valeur par défaut est true.
SuppressDependenciesWhenPacking La valeur true permet de supprimer les dépendances du package généré par le package NuGet.
PackageVersion Spécifie la version du package obtenu. Accepte toutes les formes de chaîne de version NuGet. La valeur par défaut est la valeur de $(Version), autrement dit, de la propriété Version dans le projet.
PackageId Spécifie le nom du package obtenu. Si non spécifié, l’opération pack utilise par défaut le AssemblyName ou le nom du répertoire comme nom du package.
PackageDescription Description longue du package pour l’affichage de l’interface utilisateur.
Authors Une liste d'auteurs de packages séparés par des points-virgules, correspondant aux identités sur nuget.org. Ils sont affichés dans la Galerie NuGet sur nuget.org et sont utilisés pour croiser les références des packages des mêmes auteurs.
Description Description longue de l'assembly. Si PackageDescription n’est pas spécifié, cette propriété est également utilisée comme description du package.
Copyright Détails de copyright pour le package.
PackageRequireLicenseAcceptance Valeur booléenne qui spécifie si le client doit inviter l’utilisateur à accepter la licence du package avant d’installer le package. Par défaut, il s’agit de false.
DevelopmentDependency Valeur booléenne qui spécifie si le package doit être marqué comme dépendance de développement uniquement, ce qui l’empêche d’être inclus en tant que dépendance dans d’autres packages. Avec PackageReference (NuGet 4.8+), ce drapeau signifie également que les actifs de compilation sont exclus de la compilation. Pour plus d'informations, voir Prise en charge de DevelopmentDependency pour PackageReference.
PackageLicenseExpression Un Identifiant de licence SPDX ou expression, par exemple, Apache-2.0. Pour plus d’informations, consultez Empaqueter une expression de licence ou d’un fichier de licence.
PackageLicenseFile Chemin d'accès à un fichier de licence dans le package si vous utilisez une licence personnalisée ou une licence à laquelle aucun identifiant SPDX n'a été attribué.
PackageLicenseUrl PackageLicenseUrl est déconseillé. Utilisez plutôt PackageLicenseExpression ou PackageLicenseFile.
PackageProjectUrl
PackageIcon Spécifie le chemin d’accès de l’icône de package, par rapport à la racine du package. Pour plus d’informations, consultez Empaqueter un fichier image d’icône.
PackageReleaseNotes Notes de publication du package.
PackageReadmeFile Fichier lisez-moi du package.
PackageTags Liste de balises séparées par un point-virgule qui désigne le package.
PackageOutputPath Détermine le chemin de sortie dans lequel le package compressé est déposé. La valeur par défaut est $(OutputPath).
IncludeSymbols Cette valeur booléenne indique si le package doit créer un package de symboles supplémentaire quand le projet est compressé. Le format du package de symboles est contrôlé par la propriété SymbolPackageFormat. Pour plus d’informations, consultez IncludeSymbols.
IncludeSource Cette valeur booléenne indique si le processus de compression doit créer un package source. Le package source contient le code source de la bibliothèque ainsi que les fichiers PDB. Les fichiers sources sont placés dans le répertoire src/ProjectName dans le fichier de package obtenu. Pour plus d’informations, consultez IncludeSource.
PackageType
IsTool Spécifie si tous les fichiers de sortie sont copiés dans le dossier tools au lieu du dossier lib. Pour plus d’informations, consultez IsTool.
RepositoryUrl URL du référentiel utilisée pour cloner ou récupérer le code source. Exemple : https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Type de référentiel. Exemples : git (par défaut), tfs.
RepositoryBranch Informations de branche de référentiel facultatives. RepositoryUrl doit également être spécifié pour que cette propriété soit incluse. Exemple : master (NuGet 4.7.0+).
RepositoryCommit Validation ou ensemble de modifications de référentiel facultatif pour indiquer la source sur laquelle le package a été généré. RepositoryUrl doit également être spécifié pour que cette propriété soit incluse. Exemple : 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
SymbolPackageFormat Spécifie le format du package de symboles. Si « symbols.nupkg », un package de symboles hérité est créé avec une extension .symbols.nupkg contenant des fichiers PDB, DLL et d’autres fichiers de sortie. Si « snupkg », un package de symboles snupkg est créé, contenant les fichiers PDB portables. La valeur par défaut est « symbols.nupkg ».
NoPackageAnalysis Spécifie que pack ne doit pas exécuter l'analyse du paquet après l'avoir construit.
MinClientVersion Spécifie la version minimale du client NuGet qui peut installer ce package, appliquée par nuget.exe et le gestionnaire de package de Visual Studio.
IncludeBuildOutput Ces valeurs booléennes spécifient si les assemblages de sortie de génération doivent être compressés dans le fichier .nupkg ou non.
IncludeContentInPack Cette valeur booléenne indique si les éléments dont le type est Content sont automatiquement inclus dans le package résultant. Par défaut, il s’agit de true.
BuildOutputTargetFolder Spécifie le dossier où placer les assemblys de sortie. Les assemblys de sortie (et les autres fichiers de sortie) sont copiés dans les dossiers de leur framework respectif. Pour plus d’informations, consultez assemblages de sortie.
ContentTargetFolders Spécifie la localisation par défaut de tous les fichiers de contenu si PackagePath n'est pas spécifié pour eux. La valeur par défaut est « content;contentFiles ». Pour plus d’informations, consultez Inclusion de contenu dans un package.
NuspecFile Chemin d’accès relatif ou absolu du .nuspec fichier utilisé pour l'empaquetage. Si elle est spécifiée, elle est utilisée exclusivement pour les informations relatives à l'empaquetage, et les informations contenues dans les projets ne sont pas utilisées. Pour plus d’informations, consultez Empaqueter à l’aide de.nuspec.
NuspecBasePath Chemin d'accès de base pour le fichier .nuspec. Pour plus d’informations, consultez Empaqueter à l’aide de.nuspec.
NuspecProperties Liste de paires clé=valeur séparées par un point-virgule. Pour plus d’informations, consultez Empaqueter à l’aide de.nuspec.

Scénarios avec pack

Suppression des dépendances

Pour supprimer les dépendances du package NuGet généré, définissez SuppressDependenciesWhenPacking en true, ce qui permettra d'ignorer toutes les dépendances du fichier nupkg généré.

PackageIconUrl

PackageIconUrl est déconseillé en faveur de la propriété PackageIcon. À partir de NuGet 5.3 et Visual Studio 2019 version 16.3, pack lève l'avertissement NU5048 si les métadonnées du package ne spécifient que PackageIconUrl.

PackageIcon

Conseil

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

Empaquetage d’un fichier image d’icône

Lors de l'empaquetage d'un fichier d'image d'icône, utilisez la propriété PackageIcon pour spécifier le chemin d'accès au fichier d'icône, par rapport à la racine du package. En outre, assurez-vous que le fichier est inclus dans le package. La taille du fichier image est limitée à 1 Mo. Les formats de fichiers pris en charge sont JPEG et PNG. Nous recommandons une résolution d’image de 128 x 128.

Par exemple :

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Exemple d’icône de package.

Pour l’équivalent nuspec , examinez nuspec la référence pour l’icône.

PackageReadmeFile

Pris en charge avec NuGet la version 5.10.0 préversion 2.NET / SDK 5.0.300 et versions ultérieures

Lors de l'empaquetage d'un fichier Lisez-moi, vous devez utiliser la propriété PackageReadmeFile pour spécifier le chemin du paquet, relatif à la racine du paquet. En plus de cela, vous devez vous assurer que le fichier est inclus dans le package. Les formats de fichiers pris en charge incluent uniquement Markdown (.md).

Par exemple :

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Pour l’équivalent nuspec , examinez nuspec la référence pour readme.

Assemblys de sortie

nuget pack copie les fichiers de sortie avec les extensions .exe, .dll, .xml, .winmd, .json et .pri. Les fichiers de sortie copiés dépendent de ce que MSBuild fournit à partir de la cible BuiltOutputProjectGroup.

Il existe deux propriétés MSBuild que vous pouvez utiliser dans votre fichier projet ou ligne de commande pour contrôler la destination des assemblages de sortie :

  • IncludeBuildOutput : valeur booléenne qui détermine si les assemblys de sortie de génération doivent être inclus dans le package.
  • BuildOutputTargetFolder : spécifie le dossier dans lequel les assemblys de sortie doivent être placés. Les assemblys de sortie (et les autres fichiers de sortie) sont copiés dans les dossiers de leur framework respectif.

Références de package

Consultez Références de package dans les fichiers projet.

Références entre projets

Les références de projet à projet sont considérées par défaut comme des références de package NuGet. Par exemple :

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

Vous pouvez également ajouter les métadonnées suivantes à votre référence de projet :

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Ajout de contenu dans un package

Pour inclure du contenu, ajoutez des métadonnées supplémentaires à l’élément <Content>. Par défaut, tous les éléments de type « Contenu » sont inclus dans le package, sauf si vous procédez à un remplacement avec des entrées telles que les suivantes :

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

Par défaut, tous les éléments sont ajoutés à la racine de content et du dossier contentFiles\any\<target_framework> au sein d’un package et la structure de dossier relatif est conservée, sauf si vous spécifiez un chemin de package :

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Si vous souhaitez copier tout votre contenu dans un ou plusieurs dossiers racine spécifiques (au lieu de content et contentFiles à la fois), vous pouvez utiliser la propriété MSBuild ContentTargetFolders, qui est par défaut « content;contentFiles », mais qui peut être définie avec n'importe quel autre nom de dossier. Notez que le fait de spécifier uniquement « contentFiles » dans ContentTargetFolders place les fichiers sous contentFiles\any\<target_framework> ou contentFiles\<language>\<target_framework> selon buildAction.

PackagePath peut être un ensemble de chemins cibles séparés par un point-virgule. La spécification d’un chemin de package vide permet d’ajouter le fichier à la racine du package. Par exemple, le code suivant ajoute libuv.txt à content\myfiles, content\samples et la racine du package :

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

Il existe également une propriété MSBuild $(IncludeContentInPack), dont la valeur par défaut est true. Si sa valeur est false sur un projet, le contenu de ce projet ne figure pas dans le package nuget.

D'autres métadonnées spécifiques au package que vous pouvez définir sur l'un des éléments ci-dessus comprennent <PackageCopyToOutput> et <PackageFlatten> qui définissent les valeurs CopyToOutput et Flatten sur l'entrée contentFiles dans le nuspec de sortie.

Remarque

Outre les éléments de contenu, les métadonnées <Pack> et <PackagePath> peuvent aussi être définies sur des fichiers avec l’action de génération Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource ou None.

Pour que la commande pack ajoute le nom de fichier à votre chemin de package lors de l’utilisation de modèles de globbing, votre chemin doit se terminer par le caractère de séparation de dossier, sinon il est traité comme le chemin complet avec le nom de fichier.

IncludeSymbols

Quand vous utilisez MSBuild -t:pack -p:IncludeSymbols=true, les fichiers .pdb correspondants sont copiés avec d’autres fichiers de sortie (.dll, .exe, .winmd, .xml, .json, .pri). Notez que la définition IncludeSymbols=true crée un package standard et un package de symboles.

IncludeSource

Propriété identique à IncludeSymbols, sauf qu’elle copie également les fichiers sources avec les fichiers .pdb. Tous les fichiers de type Compile sont copiés vers src\<ProjectName>\ en conservant la structure de dossiers de chemin relatif dans le package obtenu. La même situation se produit également pour les fichiers sources de n’importe quel ProjectReference dont TreatAsPackageReference a la valeur false.

Si un fichier de type Compile est en dehors du dossier de projet, il est simplement ajouté à src\<ProjectName>\.

Empaquetage d'une expression de licence ou d'un fichier sous licence

Lorsque vous utilisez une expression de licence, utilisez la propriété PackageLicenseExpression. Pour obtenir un exemple, consultez l’exemple d’expression de licence.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Pour en savoir plus sur les expressions de licence et les licences acceptées par NuGet.org, consultez les métadonnées de licence.

Lors de l'empaquetage d'un fichier de licence, utilisez la propriété PackageLicenseFile pour spécifier le chemin d'accès au package, par rapport à la racine du package. En outre, assurez-vous que le fichier est inclus dans le package. Par exemple :

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Pour obtenir un exemple, consultez l’exemple de fichier sous licence.

Remarque

Il n’est pas possible de spécifier plusieurs des éléments suivants à la fois : PackageLicenseExpression, PackageLicenseFile et PackageLicenseUrl.

Empaquetage d’un fichier sans extension

Dans certains scénarios, comme lors de l’empaquetage d’un fichier de licence, vous pouvez inclure un fichier sans extension. Pour des raisons historiques, NuGet et MSBuild traitent les chemins sans extension comme des répertoires.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>

Fichier sans exemple d’extension.

IsTool

Lors de l’utilisation de MSBuild -t:pack -p:IsTool=true, tous les fichiers de sortie, comme spécifié dans le scénario Assemblys de sortie, sont copiés dans le dossier tools au lieu du dossier lib. Notez que cela est différent d’un DotNetCliTool qui est spécifié en définissant PackageType dans le fichier .csproj.

Empaquetage à l’aide d’un fichier .nuspec

Bien qu’il soit recommandé d’inclure toutes les propriétés qui se trouvent habituellement dans le fichier .nuspec dans le fichier projet, vous pouvez choisir d'utiliser un fichier .nuspec pour emballer votre projet. Pour un projet de style non SDK qui utilise PackageReference, vous devez importer NuGet.Build.Tasks.Pack.targets afin que la tâche de pack puisse être exécutée. Vous devez toujours restaurer le projet avant de pouvoir empaquerer un nuspec fichier. (Un projet de style SDK inclut les cibles de pack par défaut.)

L’infrastructure cible du fichier projet n’est pas pertinente et n’est pas utilisée lors de l’empaquetage d’un nuspec. Les trois propriétés MSBuild suivantes sont pertinentes pour l'empaquetage à l'aide d'un .nuspec :

  1. NuspecFile : chemin relatif ou absolu du fichier .nuspec utilisé pour la compression.
  2. NuspecProperties : liste de paires clé=valeur séparées par un point-virgule. En raison du mode de fonctionnement de l’analyse de ligne de commande MSBuild, plusieurs propriétés doivent être spécifiées comme suit : -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath : chemin de base pour le fichier .nuspec.

Si vous utilisez dotnet.exe pour compresser votre projet, utilisez une commande semblable à la suivante :

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Si vous utilisez MSBuild pour compresser votre projet, utilisez une commande semblable à la suivante :

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

Veuillez noter que l'empaquetage d'un nuspec à l'aide de dotnet.exe ou de msbuild entraîne également la construction du projet par défaut. Cela peut être évité en passant la propriété --no-build à dotnet.exe, ce qui équivaut à définir <NoBuild>true</NoBuild> dans votre fichier de projet, ainsi que <IncludeBuildOutput>false</IncludeBuildOutput> dans le fichier projet.

Voici un exemple de fichier .csproj pour packer un fichier nuspec :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Points d’extension avancés pour créer un package personnalisé

La cible pack fournit deux points d'extension qui s'exécutent dans la version cible de .Net Framework interne, spécifique au cadre de la cible. Les points d’extension prennent en charge notamment le contenu et les assemblys spécifiques à la version cible de .Net Framework dans un package :

  • TargetsForTfmSpecificBuildOutput cible : Utiliser pour les fichiers à l’intérieur du dossier lib ou d’un dossier spécifié à l’aide de BuildOutputTargetFolder.
  • TargetsForTfmSpecificContentInPackage cible : Utiliser pour les fichiers en dehors de BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Écrivez une cible personnalisée et spécifiez-la comme valeur de la $(TargetsForTfmSpecificBuildOutput) propriété. Pour tous les fichiers qui doivent être placés dans le BuildOutputTargetFolder (bibliothèque par défaut), la cible doit écrire ces fichiers dans l'ItemGroup BuildOutputInPackage et définir les deux valeurs de métadonnées suivantes :

  • FinalOutputPath : chemin d'accès absolu du fichier ; s’il n’est pas fourni, l’identité est utilisée pour évaluer le chemin d'accès source.
  • TargetPath : (facultatif) définissez quand le fichier doit accéder à un sous-dossier dans lib\<TargetFramework> , comme les assemblys satellites qui passent sous leurs dossiers de culture respectifs. La valeur par défaut est le nom du fichier.

Exemple :

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Écrivez une cible personnalisée et spécifiez-la comme valeur de la $(TargetsForTfmSpecificContentInPackage) propriété. Pour que tous les fichiers à inclure dans le package, la cible doit écrire ces fichiers dans itemGroup TfmSpecificPackageFile et définir les métadonnées facultatives suivantes :

  • PackagePath : chemin d’accès où le fichier doit être généré dans le package. NuGet émet un avertissement si plusieurs fichiers sont ajoutés au même chemin d'accès au package.
  • BuildAction : action de génération à affecter au fichier, obligatoire uniquement si le chemin d'accès au package se trouve dans le dossier contentFiles. La valeur par défaut est « None ».

Exemple :

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>

Cible restore

MSBuild -t:restore (que nuget restore et dotnet restore utilisent avec les projets .NET Core) restaure les packages référencés dans le fichier projet en effectuant les opérations suivantes :

  1. Lire toutes les références entre projets
  2. Lire les propriétés du projet pour trouver le dossier intermédiaire et les versions cibles de .NET Framework
  3. Transmettre les données MSBuild à NuGet.Build.Tasks.dll
  4. Exécuter la restauration
  5. Télécharger des packages
  6. Écrire le fichier de ressources, les cibles et les propriétés

La cible restore fonctionne pour les projets au format PackageReference. MSBuild 16.5+ prend également en charge le format packages.config.

Remarque

La cible restore ne doit pas être exécutée en combinaison avec la cible build.

Propriétés de restauration

D'autres paramètres de restauration peuvent provenir des propriétés MSBuild du fichier projet. Des valeurs peuvent également être définies à partir de la ligne de commande à l’aide du commutateur -p: (consultez Exemples ci-dessous).

Propriété Description
RestoreSources Liste de sources de packages séparées par un point-virgule.
RestorePackagesPath Chemin du dossier de packages de l’utilisateur.
RestoreDisableParallel Limite les téléchargements à un à la fois.
RestoreConfigFile Chemin à un fichier Nuget.Config à appliquer.
RestoreNoHttpCache Si la valeur est true, évite d’utiliser des packages mis en cache http. Consultez Gestion des packages globaux et des dossiers de cache.
RestoreIgnoreFailedSources Si la valeur est true, ignore les sources de packages défectueuses ou manquantes.
RestoreFallbackFolders Dossiers de secours, utilisés de la même façon que le dossier packages utilisateur est utilisé.
RestoreAdditionalProjectSources Sources supplémentaires à utiliser pendant la restauration.
RestoreAdditionalProjectFallbackFolders Dossiers de secours supplémentaires à utiliser pendant la restauration.
RestoreAdditionalProjectFallbackFoldersExcludes Exclut les dossiers de secours spécifiés dans RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile Chemin d’accès à NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Liste de projets à restaurer séparés par un point-virgule, qui doit contenir des chemins absolus.
RestoreUseSkipNonexistentTargets Lorsque les projets sont collectés via MSBuild celui-ci détermine s’ils sont collectés à l’aide de l’optimisation SkipNonexistentTargets. Si non défini, la valeur par défaut est true. La conséquence est un comportement d’échec rapide quand les cibles d’un projet ne peuvent pas être importées.
MSBuildProjectExtensionsPath Dossier de sortie, par défaut BaseIntermediateOutputPath et le dossier obj.
RestoreForce Dans les projets basés sur PackageReference, force la résolution de toutes les dépendances, même si la dernière restauration a réussi. La spécification de cet indicateur est similaire à la suppression du fichier project.assets.json. Cela ne contourne pas le cache http.
RestorePackagesWithLockFile Choisit d’utiliser d’un fichier de verrouillage.
RestoreLockedMode Exécutez la restauration en mode verrouillé. Cela signifie que la restauration ne réévalue pas les dépendances.
NuGetLockFilePath Emplacement personnalisé du fichier de verrouillage. L’emplacement par défaut est en regard du projet et est nommé packages.lock.json.
RestoreForceEvaluate Force la restauration pour recompiler les dépendances et mettre à jour le fichier de verrouillage sans avertissement.
RestorePackagesConfig Un commutateur opt-in, qui restaure les projets avec packages.config. Prise en charge avec MSBuild -t:restore seulement.
RestoreRepositoryPath packages.config uniquement. Spécifie le répertoire des packages dans lequel les packages doivent être restaurés. SolutionDirectory sera utilisé s'il n'est pas spécifié.
RestoreUseStaticGraphEvaluation Un commutateur opt-in pour utiliser l'évaluation statique du graphique MSBuild au lieu de l'évaluation standard. L’évaluation statique des graphiques est une caractéristique expérimentale qui est beaucoup plus rapide pour les dépôts et solutions volumineux.
RestoreUseLegacyDependencyResolver Refus d’utiliser le programme de résolution de dépendance hérité. L’implémentation du programme de résolution de dépendance de NuGet a été réécrite dans la version 6.12. Ce commutateur force à utiliser l’algorithme précédent.

La propriété ExcludeRestorePackageImports est une propriété interne utilisée par NuGet. Il ne doit pas être modifié ou défini dans des fichiers MSBuild.

Exemples

Ligne de commande :

msbuild -t:restore -p:RestoreConfigFile=<path>

Fichier projet :

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Sorties de restauration

La restauration crée les fichiers suivants dans le dossier obj de build :

Fichier Description
project.assets.json Contient la graphe des dépendances de toutes les références de package.
{projectName}.projectFileExtension.nuget.g.props Références aux accessoires MSBuild contenus dans les packages
{projectName}.projectFileExtension.nuget.g.targets Références aux cibles MSBuild contenues dans les packages

Restauration et génération avec une commande MSBuild

En raison du fait que NuGet peut restaurer des cibles MSBuild et des propriétés, les évaluations de restauration et de build sont exécutées avec différentes propriétés globales. Cela signifie que les éléments suivants auront un comportement imprévisible et souvent incorrect.

msbuild -t:restore,build

Au lieu de cela, l’approche recommandée est la suivante :

msbuild -t:build -restore

La même logique s’applique à d’autres cibles similaires à build.

Restauration de projets PackageReference et packages.config avec MSBuild

Avec MSBuild 16.5+, packages.config sont également pris en charge pour msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Remarque

packages.config la restauration est disponible uniquement avec MSBuild 16.5+, et non avec dotnet.exe

Restauration à l'aide de l'évaluation statique du graphe MSBuild

Remarque

Avec MSBuild 16.6+, NuGet a ajouté une caractéristique expérimentale pour utiliser l’évaluation statique des graphiques à partir de la ligne de commande qui améliore considérablement le temps de restauration pour les dépôts volumineux.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Vous pouvez également l'activer en définissant la propriété dans un fichier Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Remarque

À partir de Visual Studio 2019.x et NuGet 5.x, cette caractéristique est considérée comme expérimentale et opt-in. Suivez NuGet/Home#9803 pour plus d’informations sur le moment où cette caractéristique sera activée par défaut.

La restauration de graphique statique modifie la partie msbuild de la restauration, la lecture et l’évaluation du projet, mais pas l’algorithme de restauration ! L’algorithme de restauration est le même pour tous les outils NuGet (NuGet.exe, MSBuild.exe, dotnet.exe et Visual Studio).

Dans très peu de scénarios, la restauration de graphes statiques peut se comporter différemment de la restauration actuelle et certains PackageReferences ou ProjectReferences déclarés peuvent être manquants.

Pour vous faciliter la tâche, lors de la migration vers la restauration des graphes statiques, envisagez de procéder à une vérification ponctuelle :

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet ne doit pas signaler de modifications. Si vous constatez une différence, veuillez déposer un problème à NuGet/Home.

Remplacement d’une bibliothèque à partir d’un graphique de restauration

Si une restauration présente un assembly incorrect, il est possible d’exclure cette option par défaut de package et de la remplacer par votre propre choix. Commencez par exclure toutes les ressources avec un PackageReference de niveau supérieur :

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Ajoutez ensuite votre propre référence à la copie locale appropriée de la DLL :

<Reference Include="Newtonsoft.Json.dll" />