.vcxproj et .props structure de fichiers

MSBuild est le système de projet par défaut dans Visual Studio. Lorsque vous choisissez Nouveau>projet dans Visual C++ que vous créez un projet MSBuild dont les paramètres sont stockés dans un fichier projet XML qui a l’extension..vcxproj Le fichier projet peut également importer .props des fichiers et .targets des fichiers où les paramètres peuvent être stockés.

Si vous envisagez de conserver vos propriétés de projet dans l’IDE, nous vous recommandons de créer et de modifier uniquement vos .vcxproj projets dans l’IDE, et d’éviter les modifications manuelles des fichiers. Dans la plupart des cas, vous n’avez jamais besoin de modifier manuellement le fichier projet. Les modifications manuelles peuvent interrompre les connexions de projet requises pour modifier les paramètres du projet dans les pages de propriétés Visual Studio et peuvent entraîner des erreurs de génération difficiles à déboguer et à réparer. Pour plus d’informations sur l’utilisation des pages de propriétés, consultez Définir le compilateur C++ et les propriétés de build dans Visual Studio.

À grande échelle, la gestion de nombreux projets individuels dans l’IDE devient fastidieuse et sujette aux erreurs. Il est difficile de maintenir la cohérence ou d’appliquer la normalisation sur des dizaines ou des centaines de projets. Dans ces cas, il est utile de modifier vos fichiers projet afin d’utiliser des fichiers personnalisés .props ou .targets des fichiers pour des propriétés communes dans de nombreux projets. Vous pouvez également utiliser ces fichiers lorsque vous avez besoin de personnalisations qui ne sont pas possibles dans l’IDE. Les emplacements pratiques pour insérer des personnalisations sont les Directory.Build.props fichiers et Directory.Build.targets les fichiers qui sont automatiquement importés dans tous les projets MSBuild.

Dans certains cas, les fichiers personnalisés .props ou .targets les fichiers seuls peuvent ne pas être suffisants pour vos besoins de gestion de projet. Vous devrez peut-être toujours modifier .vcxproj manuellement des fichiers projet ou des feuilles de propriétés. La modification manuelle nécessite une bonne compréhension de MSBuild et doit suivre les instructions de cet article. Pour que l’IDE charge et met à jour .vcxproj automatiquement des fichiers, ces fichiers ont plusieurs restrictions qui ne s’appliquent pas à d’autres fichiers projet MSBuild. Les erreurs peuvent entraîner le blocage ou le comportement de l’IDE de manière inattendue.

Pour les scénarios d’édition manuelle, cet article contient des informations de base sur la structure des .vcxproj fichiers et les fichiers associés.

Remarques importantes

Si vous choisissez de modifier manuellement un .vcxproj fichier, tenez compte des faits suivants :

• La structure du fichier doit suivre un formulaire prescrit qui est décrit dans cet article.

• Le système de projet Visual Studio C++ ne prend actuellement pas en charge les caractères génériques carte ou les listes directement dans les éléments du projet. Par exemple, ces formulaires ne sont pas pris en charge :

  <ItemGroup>
     <None Include="*.txt"/>
     <ClCompile Include="a.cpp;b.cpp"/>
  </ItemGroup>
  

  Pour plus d’informations sur le caractère générique carte la prise en charge des projets et des solutions de contournement possibles, consultez .vcxproj les fichiers et les fichiers génériques carte s.

• Le système de projet Visual Studio C++ ne prend actuellement pas en charge les macros dans les chemins d’accès aux éléments de projet. Par exemple, ce formulaire n’est pas pris en charge :

  <ItemGroup>
     <ClCompile Include="$(IntDir)\generated.cpp"/>
  </ItemGroup>
  

  « Non pris en charge » signifie que les macros ne sont pas garanties de fonctionner pour toutes les opérations de l’IDE. Les macros qui ne modifient pas leur valeur dans différentes configurations doivent fonctionner, mais peuvent ne pas être conservées si un élément est déplacé vers un autre filtre ou projet. Les macros qui modifient leur valeur pour différentes configurations entraîneront des problèmes. L’IDE ne s’attend pas à ce que les chemins d’accès des éléments de projet soient différents pour différentes configurations de projet.

• Pour ajouter, supprimer ou modifier correctement les propriétés du projet lorsque vous les modifiez dans la boîte de dialogue Propriétés du projet, le fichier doit contenir des groupes distincts pour chaque configuration de projet. Les conditions doivent être sous cette forme :

  Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"
  

• Chaque propriété doit être spécifiée dans le groupe avec son étiquette correcte, comme spécifié dans le fichier de règle de propriété. Pour plus d’informations, consultez Fichiers de règles XML des pages de propriétés.

.vcxproj éléments de fichier

Vous pouvez inspecter le contenu d’un .vcxproj fichier à l’aide d’un texte ou d’un éditeur XML. Pour l’afficher dans Visual Studio, cliquez avec le bouton sur le projet dans l’Explorateur de solutions, choisissez Décharger le projet, puis Modifier Foo.vcxproj.

Vous pouvez tout de suite remarquer que les éléments de niveau supérieur s’affichent dans un ordre particulier. Par exemple :

• La plupart des groupes de propriétés et des groupes de définitions d’éléments se trouvent après l’importation de Microsoft.Cpp.Default.props.

• Toutes les cibles sont importées à la fin du fichier.

• Plusieurs groupes de propriétés, chacun d’eux ayant une étiquette unique, suivent un ordre particulier.

L’ordre des éléments dans le fichier projet est essentiel, car MSBuild est basé sur un modèle d’évaluation séquentiel. Si votre fichier projet, y compris tous les fichiers importés et .targets les .props fichiers, se compose de plusieurs définitions d’une propriété, la dernière définition remplace les fichiers précédents. Dans l’exemple suivant, la valeur « xyz » est définie pendant la compilation, car le moteur MSBUild le rencontre pendant son évaluation.

  <MyProperty>abc</MyProperty>
  <MyProperty>xyz</MyProperty>

L’extrait de code suivant montre un fichier minimal .vcxproj . Tous les .vcxproj fichiers générés par Visual Studio contiennent ces éléments MSBuild de niveau supérieur. Ils apparaissent dans cet ordre, même s’ils peuvent contenir plusieurs copies de chaque élément de niveau supérieur. Tous Label les attributs sont des balises arbitraires qui sont utilisées uniquement par Visual Studio en tant que signpostages pour la modification ; ils n’ont aucune autre fonction.

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003'>
  <ItemGroup Label="ProjectConfigurations" />
  <PropertyGroup Label="Globals" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup Label="Configuration" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ImportGroup Label="ExtensionSettings" />
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
  <ImportGroup Label="ExtensionTargets" />
</Project>

Les sections suivantes décrivent l’objectif de chacun de ces éléments et pourquoi ils sont classés de cette façon :

Élément Project

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003' >

Project est le nœud racine. Il spécifie la version MSBuild à utiliser et la cible par défaut à exécuter lorsque ce fichier est transmis à MSBuild.exe.

Élément ItemGroup ProjectConfigurations

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations contient la description de la configuration du projet. Voici quelques exemples : Debug|Win32, Release|Win32, Debug|ARM, etc. De nombreux paramètres de projet sont spécifiques à une configuration donnée. Par exemple, vous souhaiterez probablement définir des propriétés d’optimisation pour une build de mise en production, mais pas une build de débogage.

Le ProjectConfigurations groupe d’éléments n’est pas utilisé au moment de la génération. L’IDE Visual Studio nécessite qu’il charge le projet. Ce groupe d’éléments peut être déplacé vers un .props fichier et importé dans le .vcxproj fichier. Toutefois, dans ce cas, si vous devez ajouter ou supprimer des configurations, vous devez modifier manuellement le .props fichier ; vous ne pouvez pas utiliser l’IDE.

Éléments ProjectConfiguration

L’extrait suivant montre une configuration de projet. Dans cet exemple, « Debug|x64 » est le nom de configuration. Le nom de configuration du projet doit être au format $(Configuration)|$(Platform). Un ProjectConfiguration nœud peut avoir deux propriétés : Configuration et Platform. Ces propriétés sont définies automatiquement avec les valeurs spécifiées ici lorsque la configuration est active.

<ProjectConfiguration Include="Debug|x64">
  <Configuration>Debug</Configuration>
  <Platform>x64</Platform>
</ProjectConfiguration>

L’IDE s’attend à trouver une configuration de projet pour n’importe quelle combinaison de Configuration valeurs Platform utilisée dans tous les ProjectConfiguration éléments. Souvent, cela signifie qu’un projet peut avoir des configurations de projet sans signification pour répondre à cette exigence. Par exemple, si un projet a les configurations suivantes :

• Debug|Win32

• Retail|Win32

• Special 32-bit Optimization|Win32

Il doit également avoir ces configurations, bien que « Special 32-bit Optimization » n’ait aucune signification pour x64 :

• Debug|x64

• Retail|x64

• Special 32-bit Optimization|x64

Vous pouvez désactiver les commandes de génération et de déploiement pour n’importe quelle configuration dans le gestionnaire de configuration de solutions.

Élément PropertyGroup Globals

<PropertyGroup Label="Globals" />

Globals contient des paramètres au niveau du projet tels que ProjectGuid, RootNamespaceet ApplicationType ou ApplicationTypeRevision. Les deux derniers définissent souvent le système d’exploitation cible. Un projet ne peut cibler qu’un seul système d’exploitation, car actuellement, les références et les éléments de projet ne peuvent pas avoir de conditions. Ces propriétés ne sont généralement pas remplacées autre part dans le fichier projet. Ce groupe n’est pas dépendant de la configuration, et il n’existe généralement qu’un Globals seul groupe dans le fichier projet.

Élément Import Microsoft.Cpp.default.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />

La feuille de propriétés Microsoft.Cpp.default.props est fournie avec Visual Studio et ne peut pas être modifiée. Elle contient les paramètres par défaut du projet. Les valeurs par défaut peuvent varier en fonction du type d’application.

Éléments PropertyGroup Configuration

<PropertyGroup Label="Configuration" />

Un groupe de propriétés Configuration est attaché à une condition de configuration (comme Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"). Plusieurs copies sont disponibles, une par configuration. Ce groupe de propriétés héberge les propriétés définies pour une configuration spécifique. Les propriétés de configuration, dont PlatformToolset, contrôlent également l’inclusion de feuilles de propriétés système dans Microsoft.Cpp.props. Par exemple, si vous définissez la propriété <CharacterSet>Unicode</CharacterSet>, la feuille de propriétés système microsoft.Cpp.unicodesupport.props est incluse. Si vous inspectez Microsoft.Cpp.props, vous verrez la ligne : <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Élément Import Microsoft.Cpp.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />

La feuille de propriétés Microsoft.Cpp.props (directement ou via les importations) définit les valeurs par défaut pour de nombreuses propriétés spécifiques à l’outil. Par exemple, les propriétés Optimisation et Niveau d’avertissement du compilateur, la propriété TypeLibraryName de l’outil MIDL, et ainsi de suite. Il importe également différentes feuilles de propriétés système en fonction des propriétés de configuration définies dans le groupe de propriétés immédiatement avant elle.

Élément ImportGroup ExtensionSettings

<ImportGroup Label="ExtensionSettings" />

Le groupe ExtensionSettings contient les importations des feuilles de propriétés qui font partie des personnalisations de build. Une personnalisation de build est définie par jusqu’à trois fichiers : un .targets fichier, un .props fichier et un .xml fichier. Ce groupe d’importation contient les importations pour le .props fichier.

Éléments ImportGroup PropertySheets

<ImportGroup Label="PropertySheets" />

Le groupe PropertySheets contient les importations des feuilles de propriétés d’utilisateur. Ces importations sont les feuilles de propriétés que vous ajoutez via la vue Gestionnaire de propriétés dans Visual Studio. L’ordre dans lequel ces importations sont répertoriées est important et est reflété dans le Gestionnaire de propriétés. Le fichier projet contient normalement plusieurs instances de ce genre de groupe d’importations, une pour chaque configuration de projet.

Élément PropertyGroup UserMacros

<PropertyGroup Label="UserMacros" />

UserMacros contient des propriétés que vous créez comme variables pour personnaliser votre processus de génération. Vous pouvez par exemple définir une macro utilisateur pour définir votre chemin de sortie personnalisé, $(CustomOutputPath), et l’utiliser pour définir d’autres variables. Ce groupe de propriétés héberge de telles propriétés. Dans Visual Studio, ce groupe n’est pas renseigné dans le fichier projet, car Visual C++ ne prend pas en charge les macros utilisateur pour les configurations. Les macros utilisateur sont prises en charge dans les feuilles de propriétés.

Éléments PropertyGroup par configuration

<PropertyGroup />

Il existe plusieurs instances de ce groupe de propriétés, une par configuration de projet. Chaque groupe de propriétés doit être attaché à une condition de configuration. Si une configuration est manquante, la boîte de dialogue Propriétés du projet ne fonctionne pas correctement. Contrairement aux groupes de propriétés répertoriés précédemment, celui-ci n’a pas d’étiquette. Ce groupe contient des paramètres au niveau de la configuration du projet. Ces paramètres s’appliquent à tous les fichiers qui font partie du groupe d’éléments spécifié. Les métadonnées de définition des éléments de personnalisation de la build sont initialisées ici.

Ce PropertyGroup doit venir après <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> et il ne doit pas y avoir d’autre PropertyGroup sans étiquette avant celle-ci (sinon la modification des propriétés du projet ne fonctionnera pas correctement).

Éléments ItemDefinitionGroup par configuration

<ItemDefinitionGroup />

Contient les définitions d’éléments. Ces définitions doivent respecter les mêmes règles de conditions que les éléments sans étiquette par configuration PropertyGroup .

Éléments ItemGroup

<ItemGroup />

ItemGroup les éléments contiennent les éléments (fichiers sources, et ainsi de suite) dans le projet. Les conditions ne sont pas prises en charge pour les éléments project (autrement dit, les types d’éléments traités comme des éléments de projet par définitions de règles).

Les métadonnées doivent avoir des conditions de configuration pour chaque configuration, même si elles sont toutes les mêmes. Par exemple :

<ItemGroup>
  <ClCompile Include="stdafx.cpp">
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</TreatWarningAsError>
  </ClCompile>
</ItemGroup>

Le système de projet Visual Studio C++ ne prend actuellement pas en charge les éléments génériques carte dans les éléments du projet.

<ItemGroup>
  <ClCompile Include="*.cpp"> <!--Error-->
</ItemGroup>

Le système de projet Visual Studio C++ ne prend actuellement pas en charge les macros dans les éléments du projet.

<ItemGroup>
  <ClCompile Include="$(IntDir)\generated.cpp"> <!--not guaranteed to work in all scenarios-->
</ItemGroup>

Les références, spécifiées dans un ItemGroup, présentent ces limitations :

• Les références ne prennent pas en charge les conditions.

• Les métadonnées de référence ne prennent pas en charge les conditions.

Élément Import Microsoft.Cpp.targets

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

Définit (directement ou via des importations) des cibles C++ telles que la génération, propre, etc.

Élément ImportGroup ExtensionTargets

<ImportGroup Label="ExtensionTargets" />

Ce groupe contient des importations pour les fichiers cibles de personnalisation de la build.

Conséquences de l’ordre incorrect

L’IDE Visual Studio dépend du fichier projet ayant l’ordre décrit précédemment. Par exemple, quand vous définissez une valeur de propriété dans les pages de propriétés, l’IDE place généralement la définition de la propriété dans le groupe de propriétés avec l’étiquette vide. Cet ordre garantit que les valeurs par défaut introduites dans les feuilles de propriétés système sont remplacées par des valeurs définies par l’utilisateur. De même, les fichiers cibles sont importés à la fin, car ils consomment les propriétés définies précédemment et, étant donné qu’ils ne définissent généralement pas eux-mêmes les propriétés. De même, les feuilles de propriétés utilisateur sont importées après les feuilles de propriétés système (incluses par Microsoft.Cpp.props). Cet ordre garantit que l’utilisateur peut remplacer les valeurs par défaut introduites par les feuilles de propriétés système.

Si un .vcxproj fichier ne suit pas cette disposition, les résultats de build peuvent ne pas être ce que vous attendez. Par exemple, si vous importez par erreur une feuille de propriétés système après les feuilles de propriétés définies par l’utilisateur, les paramètres utilisateur sont remplacés par les feuilles de propriétés système.

Même l’expérience du temps de conception de l’IDE dépend d’une certaine mesure du classement correct des éléments. Par exemple, si votre .vcxproj fichier n’a pas le PropertySheets groupe d’importation, l’IDE peut ne pas pouvoir déterminer où placer une nouvelle feuille de propriétés que l’utilisateur a créée dans Le Gestionnaire de propriétés. Cela peut entraîner la substitution d’une feuille utilisateur par une feuille système. Bien que l’heuristique utilisée par l’IDE puisse tolérer des incohérences mineures dans la disposition du .vcxproj fichier, nous vous recommandons vivement de ne pas dévier de la structure présentée précédemment dans cet article.

Comment l’IDE utilise les étiquettes d’élément

Dans l’IDE, lorsque vous définissez la propriété UseOfAtl dans la page de propriétés générale, elle est écrite dans le groupe de propriétés Configuration dans le fichier projet. La propriété TargetName dans la même page de propriétés est écrite dans le groupe de propriétés sans étiquette par configuration. Visual Studio examine le fichier XML de la page de propriétés pour obtenir des informations sur les emplacements où il doit écrire chaque propriété. Pour la page de propriétés Général, en supposant que vous disposez d’une version anglaise de Visual Studio 2019 Êdition Entreprise, ce fichier est %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. Le fichier de règle XML de la page de propriétés définit les informations statiques sur une règle et toutes ses propriétés. Ces informations comprennent notamment la position préférée d’une propriété Rule dans le fichier de destination (le fichier où sa valeur sera écrite). La position préférée est spécifiée par l’attribut Label sur les éléments du fichier projet.

Disposition de la feuille de propriétés

L’extrait XML suivant est une disposition minimale d’un fichier de feuille de propriétés (.props). Il est similaire à un .vcxproj fichier et les fonctionnalités des .props éléments peuvent être déduites de la discussion précédente.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
</Project>

Pour créer votre propre feuille de propriétés, copiez l’un des .props fichiers du VCTargets dossier et modifiez-le à vos fins. Pour Visual Studio 2019 Enterprise Edition, le chemin d’accès par défaut VCTargets est %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Voir aussi

Définir le compilateur C++ et les propriétés de build dans Visual Studio
Fichiers XML de la page de propriétés
.vcxprojfichiers et fichiers génériques carte