Personnaliser votre build

  • Article

Les projets MSBuild qui utilisent le processus de génération standard (importation de Microsoft.Common.props et Microsoft.Common.targets) ont plusieurs crochets d’extensibilité qui permettent de personnaliser le processus.

De nombreuses opérations de génération personnalisables sont contrôlées par des propriétés. Il est important de savoir comment et où définir la valeur d’une propriété afin d’obtenir l’effet souhaité. Vous pouvez définir des propriétés sur la ligne de commande (et dans les fichiers de réponse), dans des fichiers spéciaux commeDirectory.Build.props, dans des fichiers importés ou dans le fichier projet. Il est important de savoir où une propriété est utilisée, définie ou modifiée, ainsi que l’ordre des fichiers importés, comme les importations implicites à partir de kits de développement logiciel (SDK) tels que le Kit de développement logiciel (SDK) .NET.

Pour obtenir la liste des propriétés, consultez Propriétés courantes MSBuild.

Explorer les options de personnalisation

Les options de personnalisation suivantes sont listées par ordre croissant de complexité et de portée d’influence. Nous vous recommandons d’utiliser l’option de personnalisation la moins complexe qui répond à vos besoins, en commençant par le haut de cette liste.

Option de personnalisation Description
Ajouter des arguments à la ligne de commande MSBuild Définissez les propriétés globales qui affectent la build du projet principal et les builds de tous les projets dépendants.
Personnaliser la build pour un seul projet Ajoutez des propriétés aux fichiers .props ou .targets pour personnaliser les paramètres de build.
Gérer les fichiers générés dans le processus de génération Comment vous assurer que vos fichiers générés sont correctement inclus dans la sortie de la build.
Personnaliser la build pour un ou plusieurs projets Ajoutez des propriétés à Directory.Build.props ou ajoutez des propriétés et des cibles à Directory.Build.targets pour personnaliser la build pour tous les projets d’un dossier. Cette technique est utile pour définir des propriétés qui sont définies ou utilisées par un SDK ainsi que pour définir la portée des personnalisations afin qu’elles affectent tous les projets d’un dossier ou d’un sous-dossier.
Personnaliser votre build locale Apportez des modifications à la build uniquement sur votre ordinateur local sans affecter les fichiers sources partagés.
Personnalisation de toutes les builds .NET Personnalisez la build avec une portée à l’échelle du système (pour les builds .NET).
Personnalisation des builds C++ Personnalisez la build C++ avec pour portée un projet, une solution ou un dossier, ou toutes les builds régies par une installation de MSBuild sur un système.

Ajouter des arguments aux appels MSBuild en ligne de commande pour un projet

Vous pouvez définir des propriétés globales sur la ligne de commande. Les propriétés globales affectent toutes les builds du projet, notamment les dépendances. Rappelez-vous que la génération d’un projet déclenche automatiquement une build possible pour l’ensemble des dépendances de projet. Le comportement normal de MSBuild consiste à générer tous les projets dépendants qui sont obsolètes. Ces builds dépendantes du projet sont lancées avec les mêmes paramètres de propriété globale à partir de la ligne de commande que le projet d’origine.

Un fichier Directory.Build.rsp dans ou au-dessus de votre répertoire source est appliqué aux générations à partir de la ligne de commande de votre projet. Pour plus d’informations, consultez Fichiers réponse MSBuild.

Choisir entre l’ajout de propriétés dans un fichier .props ou .targets

MSBuild est dépend de l’ordre d’importation, et la dernière définition d’une propriété (ou d’une UsingTask ou d’une cible) est la définition utilisée.

Lorsque vous utilisez des importations explicites, vous pouvez à tout moment partir d’un fichier .props ou .targets. Voici la convention la plus utilisée :

  • Les fichiers .props sont importés au début de l’ordre d’importation.

  • Les fichiers .targets sont importés à la fin de l’ordre de build.

Cette convention est appliquée par les importations <Project Sdk="SdkName"> (autrement dit, l’importation de Sdk.props passe d’abord, avant tout le contenu du fichier, puis Sdk.targets vient en dernier, après tout le contenu du fichier).

Lorsque vous choisissez où placer les propriétés, utilisez les directives générales suivantes :

  • Pour de nombreuses propriétés, peu importe où elles sont définies, elles ne sont pas remplacées et sont en lecture seule au moment de l’exécution.

  • Pour un comportement personnalisable dans un projet individuel, définissez des valeurs par défaut dans les fichiers .props.

  • Évitez de définir des propriétés dépendantes dans les fichiers .props en lisant la valeur d’une propriété potentiellement personnalisée, car la personnalisation ne se produira qu’une fois que MSBuild aura lu le projet de l’utilisateur.

  • Définissez les propriétés dépendantes dans les fichiers .targets, car ils reprennent les personnalisations des projets individuels.

  • Si vous avez besoin de remplacer des propriétés, faites-le dans un fichier .targets, une fois que toutes les personnalisations de projet de l’utilisateur ont eu l’occasion de s’appliquer. Faites attention lors de l’utilisation de propriétés dérivées, car elles peuvent également être remplacées.

  • Ajoutez des éléments dans les fichiers .props (conditionnés par une propriété). Toutes les propriétés sont prises en compte avant n’importe quel élément, afin que les personnalisations de propriétés du projet de l’utilisateur soient récupérées, et le fait d’avoir des éléments importés dans les fichiers .props donne au projet de l’utilisateur la possibilité de Remove ou Update n’importe quel élément introduit par l’importation.

  • Définissez des cibles dans les fichiers .targets. Toutefois, si le fichier .targets est importé par un kit SDK, n’oubliez pas que ce scénario rend le remplacement de la cible plus difficile, car le projet de l’utilisateur ne comporte pas par défaut d’emplacement pour l’écraser.

  • Si possible, préférez la personnalisation des propriétés au moment de l’évaluation à la modification des propriétés à l’intérieur d’une cible. Cette recommandation vous permettra de charger un projet et comprendre ce qu’il fait plus facilement.

Contenu connexe