Personnaliser votre build

Cet article fournit une vue d’ensemble des options de personnalisation de build et des conseils sur le moment où utiliser chaque approche. Les options sont présentées dans l’ordre de complexité, des arguments de ligne de commande aux personnalisations à l’échelle du système.

Prerequisites

• Connaissance de la structure de fichiers projet MSBuild (.csprojou .vbprojsimilaire)
• Compréhension de base des propriétés et des cibles MSBuild

Vue d’ensemble

Les projets MSBuild qui utilisent le processus de génération standard (importation de Microsoft.Common.props et Microsoft.Common.targets) ont plusieurs hooks d’extensibilité que vous pouvez utiliser pour personnaliser votre processus de génération.

De nombreuses opérations de build personnalisables sont contrôlées par les propriétés. Il est important de savoir comment et d’où définir une valeur de propriété afin d’avoir 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 tels que Directory.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 et l’ordre des fichiers importés, y compris les importations implicites à partir de kits SDK tels que le Kit de développement logiciel (SDK) .NET.

Pour obtenir la liste des propriétés, consultez les propriétés MSBuild communes.

Explorer les options de personnalisation

Les options de personnalisation suivantes sont répertoriées dans l’ordre d’augmentation de la complexité et de l’étendue de l’influence. Nous vous recommandons d’utiliser l’option de personnalisation la moins complexe qui répond à votre objectif, en commençant par la partie supérieure de cette liste.

Ajouter des arguments aux appels MSBuild de ligne de commande pour votre projet

Vous pouvez définir des propriétés globales sur la ligne de commande. Les propriétés globales affectent toutes les compilations de projet, y compris les dépendances. Rappelez-vous que la création d’un projet déclenche automatiquement une build possible pour toutes les dépendances de projet. Le comportement normal de MSBuild consiste à générer tous les projets dépendants obsolètes. Ces builds de projet dépendantes sont lancées avec les mêmes paramètres de propriété globaux à 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 builds de ligne de commande de votre projet. Pour plus d’informations, consultez les fichiers de réponse MSBuild.

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

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

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

• .props les fichiers sont importés tôt dans l’ordre d’importation.

• .targets les fichiers sont importés tard dans l’ordre de génération.

Cette convention est appliquée par <Project Sdk="SdkName"> les importations (c’est-à-dire l’importation de Sdk.props vient en premier, avant tout le contenu du fichier, puis Sdk.targets vient en dernier, après tout le contenu du fichier).

Lorsque vous décidez où placer les propriétés, utilisez les instructions générales suivantes :

• Pour de nombreuses propriétés, il n’importe pas où elles sont définies, car elles ne sont pas remplacées et sont lues uniquement au moment de l’exécution.

• Pour le comportement qui peut être personnalisé dans un projet individuel, définissez les valeurs par défaut dans .props les fichiers.

• Évitez de paramétrer des propriétés dépendantes dans les fichiers de type .props en lisant la valeur d'une propriété potentiellement personnalisée, car la personnalisation ne s'effectue qu'une fois que MSBuild a lu le projet de l'utilisateur.

• Définissez les propriétés dépendantes dans .targets les fichiers, car elles récupèrent des personnalisations à partir de projets individuels.

• Si vous devez remplacer les propriétés, effectuez-le dans un .targets fichier, une fois que toutes les personnalisations de projet utilisateur ont eu la possibilité de prendre effet. Soyez prudent lors de l’utilisation de propriétés dérivées ; Les propriétés dérivées peuvent également avoir besoin d’être remplacées.

• Inclure des éléments dans les fichiers .props (basés sur une propriété). Toutes les propriétés sont prises en compte avant tout élément, de sorte que les personnalisations des propriétés de projet utilisateur soient prises en compte, et que les fichiers .props donnent au projet de l’utilisateur la possibilité de Remove ou Update tout élément introduit par l’importation.

• Définissez des cibles dans des .targets fichiers. Toutefois, si le .targets fichier est importé par un SDK, n’oubliez pas que ce scénario rend la substitution de la cible plus difficile, car le projet de l’utilisateur n’a pas de place pour le remplacer par défaut.

• Si possible, préférez personnaliser les propriétés au moment de l’évaluation par rapport à la modification des propriétés à l’intérieur d’une cible. Cette directive facilite le chargement d’un projet et la compréhension de ce qu’elle fait.

Contenu connexe

• Vue d’ensemble du processus de construction
• Propriétés courantes du projet MSBuild
• Fichiers de réponse MSBuild
• Informations de référence sur MSBuild