NuGet pack et restauration en tant que MSBuild cibles

  • Article
  • 22 minutes de lecture

NuGet 4.0+

Avec le format PackageReference , NuGet 4.0+ peut stocker toutes les métadonnées de manifeste directement dans un fichier projet plutôt que d’utiliser un fichier distinct .nuspec .

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

Ordre de génération des cibles

Étant donné que pack et restore sont MSBuild des cibles, vous pouvez y accéder pour améliorer votre flux de travail. Par exemple, supposons que vous souhaitiez copier votre package dans un partage réseau après l’avoir empaquetage. 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 MSBuild tâche, écrire votre propre cible et consommer des NuGet propriétés dans la MSBuild tâche.

Notes

$(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 PackageReference format, en utilisant msbuild -t:pack des entrées du fichier projet à utiliser lors de la création d’un NuGet package.

Le tableau suivant décrit les MSBuild propriétés qui peuvent être ajoutées à un fichier projet dans le premier <PropertyGroup> nœud. 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 plus de commodité, la table est organisée par la propriété équivalente dans un .nuspec fichier.

Notes

Owners et Summary les propriétés à partir de ne .nuspec sont pas prises en charge avec MSBuild.

Attribut/nuspec Valeur PropriétéMSBuild Default Notes
Id PackageId $(AssemblyName) $(AssemblyName) à partir de MSBuild
Version PackageVersion Version Il s’agit d’un semver compatible, par exemple 1.0.0, 1.0.0-betaou 1.0.0-beta-00345. Par défaut, s’il n’est Version pas défini.
VersionPrefix VersionPrefix empty Définition des PackageVersion remplacements VersionPrefix
VersionSuffix VersionSuffix empty Définition des PackageVersion remplacements VersionSuffix
Authors Authors Nom de l’utilisateur actuel Liste séparée par des points-virgules d’auteurs de packages, correspondant aux noms de profil sur nuget.org. Celles-ci sont affichées dans la NuGet galerie sur nuget.org et sont utilisées pour référencer des packages de référence croisée par les mêmes auteurs.
Owners N/A Non présent dans nuspec
Title Title $(PackageId) Titre convivial du package, généralement utilisé dans les affichages de l’interface utilisateur 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 elle n’est pas spécifiée, 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 qui n’a pas été affectée à un identificateur SPDX. Vous devez empaqueter 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 PackageLicenseExpression ou PackageLicenseFile à la place.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Chemin d’accès à une image dans le package à utiliser en tant qu’icône de package. Vous devez empaqueter explicitement le fichier image de l’icône référencée. Pour plus d’informations, consultez Empaquetant un fichier image et icon des métadonnées d’icône.
IconUrl PackageIconUrl empty PackageIconUrl est déconseillé en faveur de PackageIcon. Toutefois, pour la meilleure expérience de bas niveau, vous devez spécifier PackageIconUrl en plus de PackageIcon.
Readme PackageReadmeFile empty Vous devez empaqueter explicitement le fichier readme 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 du 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 facultatifs du référentiel 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 package peuvent être versionnés en ajoutant une , chaîne et une Version chaîne. Voir Définir un NuGet type de package (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 Définissez pour true supprimer les dépendances de package du package généré NuGet .
PackageVersion Spécifie la version du package obtenu. Accepte toutes les formes de chaîne de NuGet version. 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 Liste séparée par des points-virgules des auteurs de packages, correspondant aux noms de profil sur nuget.org. Ceux-ci sont affichés dans la NuGet galerie sur nuget.org et sont utilisés pour les packages de référence croisée par les mêmes auteurs.
Description Description longue de l'assembly. Si PackageDescription elle n’est pas spécifiée, 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 est marqué comme une dépendance de développement uniquement, ce qui empêche l’inclusion du package en tant que dépendance dans d’autres packages. Avec PackageReference (NuGet 4.8+), cet indicateur signifie également que les ressources au moment de la compilation sont exclues de la compilation. Pour plus d'informations, voir Prise en charge de DevelopmentDependency pour PackageReference.
PackageLicenseExpression Identificateur ou expression de licence SPDX , par exemple Apache-2.0. Pour plus d’informations, consultez Empaquetez une expression de licence ou 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 qui n’a pas été affectée à un identificateur SPDX.
PackageLicenseUrl PackageLicenseUrl est déconseillé. Utilisez PackageLicenseExpression ou PackageLicenseFile à la place.
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 Empaquetez un fichier image d’icône.
PackageReleaseNotes Notes de publication du package.
PackageReadmeFile Lisez-moi pour le 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 facultatives sur la branche de référentiel. 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és est créé avec une extension .symbols.nupkg contenant des fichiers PDF, DLL et autres fichiers de sortie. Si « snupkg », un package de symboles snupkg est créé contenant les PDB portables. La valeur par défaut est « symbols.nupkg ».
NoPackageAnalysis Spécifie qu’il pack ne doit pas exécuter l’analyse de package après avoir généré le package.
MinClientVersion Spécifie la version minimale du NuGet client qui peut installer ce package, appliquée par nuget.exe et le Visual Studio Gestionnaire de package.
IncludeBuildOutput Cette valeur booléenne spécifie si les assemblys de sortie de build doivent être compressés dans le fichier .nupkg ou non.
IncludeContentInPack Cette valeur booléenne spécifie si les éléments qui ont un type sont Content inclus automatiquement 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 Assemblys de sortie.
ContentTargetFolders Spécifie l’emplacement par défaut où tous les fichiers de contenu doivent aller s’ils PackagePath ne sont pas spécifiés 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 au fichier utilisé pour l’empaquetage .nuspec . S’il est spécifié, il est utilisé exclusivement pour les informations d’empaquetage, et toutes les informations contenues dans les projets ne sont pas utilisées. Pour plus d’informations, consultez Emballage à l’aide d’un .nuspec.
NuspecBasePath Chemin d’accès de base du .nuspec fichier. Pour plus d’informations, consultez Emballage à l’aide d’un .nuspec.
NuspecProperties Liste de paires clé=valeur séparées par un point-virgule. Pour plus d’informations, consultez Emballage à l’aide d’un .nuspec.

Scénarios avec pack

Suppression des dépendances

Pour supprimer les dépendances de package du package généré NuGet , définissez-la SuppressDependenciesWhenPackingtrue pour permettre d’ignorer toutes les dépendances du fichier nupkg généré.

PackageIconUrl

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

PackageIcon

Conseil

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

Empaquetez un fichier image d’icône

Lors de l’empaquetage d’un fichier image d’icône, utilisez PackageIcon la propriété pour spécifier le chemin du 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 incluent 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 de l’icône.

PackageReadmeFile

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

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

Par exemple :

<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 du fichier lisez-moi.

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 qui MSBuild fournit à partir de la BuiltOutputProjectGroup cible.

Il existe deux MSBuild propriétés que vous pouvez utiliser dans votre fichier projet ou ligne de commande pour contrôler l’emplacement des assemblys 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

Project aux références de projet sont considérées par défaut comme NuGet des références de package. 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 uniquement dans un ou plusieurs dossiers racines spécifiques (au lieu des contentcontentFiles deux), vous pouvez utiliser la MSBuild propriété ContentTargetFolders, qui est définie par défaut sur « content;contentFiles », mais peut être définie sur 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 MSBuild propriété $(IncludeContentInPack), qui est truepar défaut . 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 pack que vous pouvez définir sur l’un des éléments ci-dessus incluent <PackageCopyToOutput> et <PackageFlatten> qui définit CopyToOutput et Flatten valeurs sur l’entrée dans la contentFiles sortie nuspec.

Notes

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 de licence

Lorsque vous utilisez une expression de licence, utilisez la PackageLicenseExpression propriété. 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 PackageLicenseFile la propriété pour spécifier le chemin du 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 de licence.

Notes

Un seul des PackageLicenseExpression, PackageLicenseFileet PackageLicenseUrl peut être spécifié à la fois.

Compression 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&MSBuild traitez les chemins sans extension comme 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 .nuspec fichier

Bien qu’il soit recommandé d’inclure toutes les propriétés qui se trouvent généralement dans le .nuspec fichier du fichier projet, vous pouvez choisir d’utiliser un .nuspec fichier pour packer votre projet. Pour un projet de style non SDK qui utilise PackageReference, vous devez importer NuGet.Build.Tasks.Pack.targets pour que la tâche de pack puisse être exécutée. Vous devez quand même restaurer le projet avant de pouvoir empaqueter 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 la compression d’un nuspecfichier . Les trois MSBuild propriétés suivantes sont pertinentes pour l’emballage à 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 fonctionnement MSBuild de l’analyse de ligne de commande, 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>

Notez que l’empaquetage d’un nuspec dotnet.exe ou msbuild entraîne également la génération du projet par défaut. Cela peut être évité en passant --no-build la propriété à dotnet.exe, ce qui équivaut à définir <NoBuild>true</NoBuild> dans votre fichier projet, ainsi que le paramètre <IncludeBuildOutput>false</IncludeBuildOutput> dans le fichier projet.

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

<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 pack cible fournit deux points d’extension qui s’exécutent dans la build spécifique de l’infrastructure cible interne. Les points d’extension prennent en charge notamment le contenu et les assemblys spécifiques au framework cible dans un package :

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

TargetsForTfmSpecificBuildOutput

Écrivez une cible personnalisée et spécifiez-la comme valeur de la $(TargetsForTfmSpecificBuildOutput) propriété. Pour tous les fichiers qui doivent accéder au BuildOutputTargetFolder fichier (lib par défaut), la cible doit écrire ces fichiers dans le ItemGroup BuildOutputInPackage et définir les deux valeurs de métadonnées suivantes :

  • FinalOutputPath: chemin 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 lorsque le fichier doit accéder à un sous-dossier dans lib\<TargetFramework> , comme les assemblys satellites qui se trouvent 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 tous les fichiers à inclure dans le package, la cible doit écrire ces fichiers dans le 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 contentFiles dossier. 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 des MSBuild données à 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 restore cible fonctionne pour les projets à l’aide du format PackageReference. MSBuild 16.5+ prend également en charge le packages.config format.

Notes

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

Propriétés de restauration

Des paramètres de restauration supplémentaires peuvent provenir de MSBuild propriétés dans le 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.
RestoreNoCache Si la valeur est true, évite d’utiliser des packages mis en cache. 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 des packages utilisateur.
RestoreAdditionalProjectSources Sources supplémentaires à utiliser lors de la restauration.
RestoreAdditionalProjectFallbackFolders Dossiers de secours supplémentaires à utiliser lors de 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 . Lorsqu’il n’est truepas défini, la valeur par défaut est . La conséquence est un comportement d’échec quand les cibles d’un projet ne peuvent pas être importées.
MSBuildProjectExtensionsPath Dossier de sortie, valeur par défaut BaseIntermediateOutputPath et dossier obj .
RestoreForce Dans les projets basés sur PackageReference, force toutes les dépendances à résoudre même si la dernière restauration a réussi. La spécification de cet indicateur est similaire à la suppression du project.assets.json fichier. Cela ne contourne pas le cache http.
RestorePackagesWithLockFile Opte pour l’utilisation 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 récomputer les dépendances et mettre à jour le fichier de verrouillage sans avertissement.
RestorePackagesConfig Commutateur d’opt-in, qui restaure les projets avec packages.config. Prise en charge uniquement MSBuild -t:restore .
RestoreRepositoryPath packages.config uniquement. Spécifie le répertoire des packages auquel les packages doivent être restaurés. SolutionDirectory sera utilisé s’il n’est pas spécifié.
RestoreUseStaticGraphEvaluation Commutateur d’opt-in pour utiliser l’évaluation de graphique MSBuild statique au lieu de l’évaluation standard. L’évaluation statique du graphique est une fonctionnalité expérimentale qui est beaucoup plus rapide pour les grands repos et solutions.

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

Exemples

Ligne de commande :

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

Fichier projet :

<PropertyGroup>
    <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

Sorties de restauration

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

Fichier Description
project.assets.json Contient le graphique de dépendances de toutes les références de package.
{projectName}.projectFileExtension.nuget.g.props Références aux MSBuild propriétés contenues dans les packages
{projectName}.projectFileExtension.nuget.g.targets Références aux MSBuild cibles contenues dans les packages

Restauration et génération avec une MSBuild commande

En raison du fait que NuGet les packages peuvent restaurer des cibles et des props, MSBuild 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

Notes

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

Restauration avec MSBuild l’évaluation statique du graphique

Notes

Avec MSBuild 16.6+, NuGet a ajouté une fonctionnalité expérimentale pour utiliser l’évaluation statique du graphique à 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 répertoire.Build.Props.

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

Notes

Depuis Visual Studio 2019.x et NuGet 5.x, cette fonctionnalité est considérée comme expérimentale et opt-in. Suivez NuGet/Home#9803 pour plus d’informations sur l’activation de cette fonctionnalité 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 NuGet outils (NuGet.exe,.exe, MSBuild 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 faciliter votre esprit, en tant que vérification ponctuelle, lors de la migration vers la restauration de graphique statique, envisagez d’exécuter :

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

NuGetne doit pas signaler de modifications. Si vous voyez une différence, envoyez 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" />