Personnaliser votre buildCustomize your build

Dans les versions de MSBuild antérieures à la version 15, si vous souhaitiez fournir une nouvelle propriété personnalisée aux projets de votre solution, vous deviez ajouter manuellement une référence à cette propriété pour chaque fichier projet de la solution.In versions of MSBuild prior to version 15, if you wanted to provide a new, custom property to projects in your solution, you had to manually add a reference to that property to every project file in the solution. Ou vous deviez définir la propriété dans un fichier .props, puis importer explicitement le fichier .props dans chaque projet de la solution, entre autres.Or, you had to define the property in a .props file and then explicitly import the .props file in every project in the solution, among other things.

Maintenant, vous pouvez ajouter une nouvelle propriété à chaque projet en une seule étape en la définissant dans un seul fichier appelé Directory.Build.props qui se trouve à la racine de votre référentiel.However, now you can add a new property to every project in one step by defining it in a single file called Directory.Build.props at the root of your repo. Quand MSBuild s’exécute, Microsoft.Common.props recherche le fichier Directory.Build.props dans votre structure de répertoire (et Microsoft.Common.targets recherche Directory.Build.targets).When MSBuild runs, Microsoft.Common.props searches your directory structure for the Directory.Build.props file (and Microsoft.Common.targets looks for Directory.Build.targets). S’il en trouve un, il importe la propriété.If it finds one, it imports the property. Directory.Build.props est un fichier défini par l’utilisateur qui fournit des personnalisations aux projets situés dans un répertoire.Directory.Build.props is a user-defined file that provides customizations to projects under a directory.

Exemple avec Directory.Build.propsDirectory.Build.props example

Par exemple, si vous souhaitez permettre à l’ensemble de vos projets d’accéder à la nouvelle fonctionnalité Roslyn /deterministic (qui est exposée dans la cible CoreCompile de Roslyn par la propriété $(Deterministic)), vous pouvez procéder comme suit.For example, if you wanted to enable all of your projects to access the new Roslyn /deterministic feature (which is exposed in the Roslyn CoreCompile target by the property $(Deterministic)), you could do the following.

  1. Créez un nouveau fichier à la racine de votre référentiel appelé Directory.Build.props.Create a new file in the root of your repo called Directory.Build.props.
  2. Ajoutez le code XML suivant au fichier.Add the following XML to the file.

    <Project>
     <PropertyGroup>
       <Deterministic>true</Deterministic>
     </PropertyGroup>
    </Project>
    
  3. Exécutez MSBuild.Run MSBuild. Les importations existantes de votre projet de Microsoft.Common.props et Microsoft.Common.targets trouvent le fichier et l’importent.Your project’s existing imports of Microsoft.Common.props and Microsoft.Common.targets find the file and import it.

Étendue de la rechercheSearch scope

Lorsque vous recherchez un fichier Directory.Build.props, MSBuild remonte dans la structure de répertoire par rapport à l’emplacement de votre projet ($(MSBuildProjectFullPath)) et s’arrête après avoir localisé un fichier Directory.Build.props.When searching for a Directory.Build.props file, MSBuild walks the directory structure upwards from your project location ($(MSBuildProjectFullPath)), stopping after it locates a Directory.Build.props file. Par exemple, si votre $(MSBuildProjectFullPath) était c:\users\username\code\test\case1, MSBuild commencerait à rechercher ici, puis remonterait dans la structure de répertoire jusqu’à ce qu’il trouve un fichier Directory.Build.props, comme dans la structure de répertoire suivante.For example, if your $(MSBuildProjectFullPath) was c:\users\username\code\test\case1, MSBuild would start searching there and then search the directory structure upward until it located a Directory.Build.props file, as in the following directory structure.

c:\users\username\code\test\case1
c:\users\username\code\test
c:\users\username\code
c:\users\username
c:\users
c:\

L’emplacement du fichier solution est sans importance pour Directory.Build.props.The location of the solution file is irrelevant to Directory.Build.props.

Ordre d’importationImport order

Directory.Build.props est importé très tôt dans Microsoft.Common.props, donc les propriétés définies ultérieurement ne sont pas disponibles pour ce dernier.Directory.Build.props is imported very early in Microsoft.Common.props, so properties defined later are unavailable to it. Par conséquent, évitez de faire référence aux propriétés qui ne sont pas encore définies (et qui seront évaluées comme vides).So, avoid referring to properties that are not yet defined (and will thus evaluate to empty).

Directory.Build.targets est importé à partir de Microsoft.Common.targets après l’importation des fichiers .targets à partir des packages NuGet.Directory.Build.targets is imported from Microsoft.Common.targets after importing .targets files from NuGet packages. Il peut donc être utilisé pour remplacer les propriétés et les cibles définies dans la quasi-totalité de la logique de build. Dans certains cas toutefois, il peut être nécessaire d’effectuer des personnalisations dans le fichier projet après l’importation finale.So, it can be used to override properties and targets defined in most of the build logic, but at times it may be necessary to do customizations within the project file after the final import.

Cas d’utilisation : Fusion à plusieurs niveauxUse case: multi-level merging

Supposons que vous ayez la structure de solution standard suivante :Suppose you have this standard solution structure:

\
  MySolution.sln
  Directory.Build.props     (1)
  \src
    Directory.Build.props   (2-src)
    \Project1
    \Project2
  \test
    Directory.Build.props   (2-test)
    \Project1Tests
    \Project2Tests

Il peut être souhaitable d’avoir des propriétés communes pour tous les projets (1), des propriétés communes pour les projets src (2-src) et des propriétés communes pour les projets test (2-test).It might be desirable to have common properties for all projects (1), common properties for src projects (2-src), and common properties for test projects (2-test).

Pour que MSBuild fusionne correctement les fichiers « internes » (2-src et 2-test) avec le fichier « externe » (1), vous devez prendre en compte le fait qu’une fois que MSBuild a trouvé un fichier Directory.Build.props, il arrête sa recherche.For MSBuild to correctly merge the "inner" files (2-src and 2-test) with the "outer" file (1), you must take into account that once MSBuild finds a Directory.Build.props file, it stops further scanning. Pour poursuivre la recherche et fusionner les fichiers internes avec le fichier externe, placez ce qui suit dans les deux fichiers internes :To continue scanning, and merge into the outer file, place this into both inner files:

<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

Voici un résumé de l’approche générale MSBuild :A summary of MSBuild's general approach is as follows:

  • Pour un projet donné, MSBuild recherche le premier Directory.Build.props vers le haut de la structure de la solution, le fusionne avec les valeurs par défaut et arrête la rechercheFor any given project, MSBuild finds the first Directory.Build.props upward in the solution structure, merges it with defaults, and stops scanning for more
  • Si vous souhaitez rechercher et fusionner plusieurs niveaux, importez (<Import...>, ci-dessus) le fichier « externe » à partir du fichier « interne ».If you want multiple levels to be found and merged, then <Import...> (shown above) the "outer" file from the "inner" file
  • Si le fichier « externe » n’importe pas également un élément situé au-dessus, la recherche s’arrête.If the "outer" file does not itself also import something above it, then scanning stops there
  • Pour contrôler le processus de recherche et de fusion, utilisez $(DirectoryBuildPropsPath) et $(ImportDirectoryBuildProps).To control the scanning/merging process, use $(DirectoryBuildPropsPath) and $(ImportDirectoryBuildProps)

Ou plus simplement : MSBuild s’arrête au premier Directory.Build.props qui n’importe aucun élément.Or more simply: the first Directory.Build.props which doesn't import anything, is where MSBuild stops.

Voir aussiSee Also

Concepts MSBuild MSBuild Concepts
Informations de référence sur MSBuildMSBuild Reference