Pack NuGet et restauration en tant que cibles MSBuild

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.

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.

entrées de cible pack

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

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.

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.

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.

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

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 :

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

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

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>

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" />