Fichiers MSBuild .props et .targets dans un package

Article
12/22/2023

En plus des assemblys plus traditionnels, les packages NuGet peuvent parfois ajouter des cibles de génération personnalisées ou des propriétés aux projets qui consomment ce package. Pour ce faire, ajoutez un fichier MSBuild valide, sous la forme <package_id>.targets ou <package_id>.props (par exemple Contoso.Utility.UsefulStuff.targets) dans les dossiers de génération du projet.

Dossiers de génération

À mesure que NuGet a évolué, différents dossiers .props et .targets pour la génération ont été ajoutés.

Dossier	Version de NuGet	Utiliser
build	2.5 +	Logique de génération pour chaque framework au sein d’un projet.
buildMultiTargeting	4.0 +	Logique de génération pour les `outer build` pour les projets qui ciblent plusieurs frameworks. PackageReference uniquement.
buildTransitive	5.0 +	Logique de génération pour les ressources transitive qui vont vers n’importe quel projet de consommation. Consultez la page Fonctionnalité. PackageReference uniquement.

Dossier de génération spécifique au framework

Les trois dossiers de génération suivent le même modèle pour décider du fichier le plus approprié en fonction de la version cible de .Net Framework du projet.

Les fichiers du dossier racine de génération, build/<package_id>.targets et build/<package_id>.props, sont considérés comme adaptés pour toutes les versions cibles de .Net Framework.

Pour fournir des fichiers spécifiques au framework, commencez par les placer dans les sous-dossiers appropriés, notamment :

    \build
        \netstandard1.4
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets
        \net462
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets

Préférez l’utilisation des dossiers de génération spécifiques au framework chaque fois que cela est approprié pour éviter les faux positifs d’installations dans les projets qui pourraient ne pas être pris en charge.

Notez que si les dossiers lib et ref du package sont vides, et qu’il n’y a que des fichiers de dossier de génération spécifique à framework, ce package sera considéré comme compatible avec tous les projets. Les versions à jour des outils de pack déclenchent l’avertissement NU5127 lorsque de tels packages sont créés.

Projets consommant des packages avec des fichiers de build

Projets PackageReference

.props et .targets ne sont pas ajoutés au fichier projet, mais sont rendus disponible par le biais de {projectName}.nuget.g.targets et {projectName}.nuget.g.props. Ces fichiers sont générés automatiquement lors de l’exécution de la restauration.

Lorsqu’un projet cible plusieurs frameworks, les importations dans ces fichiers sont conditionnées sur le nom de la version cible de .Net Framework.

Les fichiers MSBuild .props et .targets du ciblage multi-framework peuvent être placés dans le dossier \buildMultiTargeting. Lorsque les importations sont générées, une condition indiquant que la propriété MSBuild $(TargetFramework) est vide, est définie.

projets packages.config

Quand NuGet installe un package avec des fichiers \build, il ajoute des éléments <Import> MSBuild au fichier projet pointant vers les fichiers .targets et .props. (.props est ajouté en haut du fichier projet ; .targets est ajouté en bas.) Un élément MSBuild <Import> conditionnel distinct est ajouté pour chaque version cible de .Net Framework.

Création de package avec des fichiers MSBuild props et targets

Vous pouvez utiliser l’un des outils suivants pour inclure MSBuild .props et .targets dans le package.

Aide pour le contenu des fichiers props et targets MSBuild

NuGet ne limite pas la façon dont vous créez .props et .targets , étant donné qu’ils varient en fonction du besoin de l’auteur du package et des projets cibles eux-mêmes.

Il existe quelques éléments qui ne doivent pas être effectués dans les .props et .targets du package, par exemple, ne pas spécifier pas les propriétés et les éléments qui affectent la restauration, car ceux-ci seront automatiquement exclus.

Voici quelques exemples de propriétés qui ne doivent pas être ajoutées ou mises à jour : TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback, etc.
Voici quelques exemples d’éléments qui ne doivent pas être ajoutés ou mis à jour : PackageReference, PackageVersion, PackageDownload, etc.