NuGet pack et restauration en tant que MSBuild cibles
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-beta ou 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 SuppressDependenciesWhenPacking
true
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 PackageIconUrl
que .
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>
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 content
contentFiles
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 true
par 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
, PackageLicenseFile
et 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
:
NuspecFile
: chemin relatif ou absolu du fichier.nuspec
utilisé pour la compression.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"
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’aidelib
BuildOutputTargetFolder
de .TargetsForTfmSpecificContentInPackage
cible : Utiliser pour les fichiers en dehors duBuildOutputTargetFolder
.
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 danslib\<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 lecontentFiles
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 :
- Lire toutes les références entre projets
- Lire les propriétés du projet pour trouver le dossier intermédiaire et les versions cibles de .NET Framework
- Transmettre des MSBuild données à NuGet.Build.Tasks.dll
- Exécuter la restauration
- Télécharger des packages
- É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 true pas 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" />