.vcxproj en .props bestandsstructuur

MSBuild is het standaardprojectsysteem in Visual Studio; wanneer u Bestand>nieuw project kiest, maakt u in de meeste gevallen een MSBuild-project waarvan de instellingen zijn opgeslagen in een XML-projectbestand met de extensie .vcxproj. Het projectbestand kan ook bestanden en .props bestanden importeren .targets waarin instellingen kunnen worden opgeslagen.

Als u de projecteigenschappen in de IDE wilt behouden, raden we u aan alleen uw .vcxproj projecten in de IDE te maken en te wijzigen en handmatige bewerkingen in de bestanden te voorkomen. In de meeste gevallen hoeft u het projectbestand nooit handmatig te bewerken. Handmatige bewerkingen kunnen de projectverbindingen verbreken die nodig zijn om projectinstellingen te wijzigen op de eigenschappenpagina's van Visual Studio en kunnen buildfouten veroorzaken die moeilijk kunnen worden opgespoord en hersteld. Zie C++-compiler en buildeigenschappen instellen in Visual Studio voor meer informatie over het gebruik van de eigenschappenpagina's.

Op schaal wordt het beheren van veel afzonderlijke projecten in de IDE tijdrovend en foutgevoelig. Het is moeilijk om consistentie te behouden of standaardisatie af te dwingen voor tientallen of honderden projecten. In dergelijke gevallen is het de moeite waard om uw projectbestanden te bewerken om aangepaste .props bestanden te .targets gebruiken voor algemene eigenschappen in veel projecten. U kunt deze bestanden ook gebruiken wanneer u aanpassingen nodig hebt die niet mogelijk zijn in de IDE. Handige plaatsen om aanpassingen in te voegen zijn de Directory.Build.props en Directory.Build.targets bestanden, die automatisch worden geïmporteerd in alle OP MSBuild gebaseerde projecten.

In sommige gevallen zijn aangepaste .props bestanden of .targets bestanden mogelijk niet voldoende voor uw projectmanagementbehoeften. Mogelijk moet u projectbestanden of eigenschappenvensters handmatig wijzigen .vcxproj . Handmatig bewerken vereist een goed begrip van MSBuild en moet de richtlijnen in dit artikel volgen. Om de IDE automatisch te laden en bij te werken .vcxproj , hebben deze bestanden verschillende beperkingen die niet van toepassing zijn op andere MSBuild-projectbestanden. Fouten kunnen ertoe leiden dat de IDE vastloopt of zich op onverwachte manieren gedraagt.

Voor handmatige bewerkingsscenario's bevat dit artikel basisinformatie over de structuur van .vcxproj en gerelateerde bestanden.

Belangrijke overwegingen

Als u ervoor kiest om een .vcxproj bestand handmatig te bewerken, moet u rekening houden met deze feiten:

• De structuur van het bestand moet een voorgeschreven vorm volgen, die in dit artikel wordt beschreven.

• Het Visual Studio C++-projectsysteem biedt momenteel geen ondersteuning voor jokertekens of lijsten rechtstreeks in projectitems. Deze formulieren worden bijvoorbeeld niet ondersteund:

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

  Zie bestanden en jokertekens voor meer informatie over ondersteuning met jokertekens.vcxproj in projecten en mogelijke tijdelijke oplossingen.

• Het Visual Studio C++-projectsysteem biedt momenteel geen ondersteuning voor macro's in projectitempaden. Dit formulier wordt bijvoorbeeld niet ondersteund:

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

  'Niet ondersteund' betekent dat macro's niet gegarandeerd werken voor alle bewerkingen in de IDE. Macro's die de waarde in verschillende configuraties niet wijzigen, moeten werken, maar blijven mogelijk niet behouden als een item naar een ander filter of project wordt verplaatst. Macro's die hun waarde voor verschillende configuraties wijzigen, veroorzaken problemen. De IDE verwacht niet dat projectitempaden verschillen voor verschillende projectconfiguraties.

• Als u projecteigenschappen correct wilt toevoegen, verwijderen of wijzigen wanneer u ze bewerkt in het dialoogvenster Projecteigenschappen , moet het bestand afzonderlijke groepen bevatten voor elke projectconfiguratie. De voorwaarden moeten in deze vorm zijn:

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

• Elke eigenschap moet worden opgegeven in de groep met het juiste label, zoals opgegeven in het eigenschappenregelbestand. Zie xml-regelbestanden voor eigenschappenpagina's voor meer informatie.

.vcxproj bestandselementen

U kunt de inhoud van een .vcxproj bestand inspecteren met behulp van een tekst- of XML-editor. U kunt het weergeven in Visual Studio door met de rechtermuisknop op het project in Solution Explorer te klikken, project uit te laden en vervolgens Bewerken Foo.vcxproj te kiezen.

Het eerste wat u moet zien, is dat de elementen op het hoogste niveau in een bepaalde volgorde worden weergegeven. Voorbeeld:

• De meeste eigenschapsgroepen en itemdefinitiegroepen vinden plaats na het importeren voor Microsoft.Cpp.Default.props.

• Alle doelen worden aan het einde van het bestand geïmporteerd.

• Er zijn meerdere eigenschapsgroepen, elk met een uniek label en ze vinden plaats in een bepaalde volgorde.

De volgorde van elementen in het projectbestand is essentieel, omdat MSBuild is gebaseerd op een sequentiële evaluatiemodel. Als uw projectbestand, inclusief alle geïmporteerde .props bestanden .targets , bestaat uit meerdere definities van een eigenschap, overschrijft de laatste definitie de voorgaande definities. In het volgende voorbeeld wordt de waarde 'xyz' ingesteld tijdens de compilatie omdat de MSBUild-engine deze het laatst tegenkomt tijdens de evaluatie.

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

In het volgende fragment ziet u een minimaal .vcxproj bestand. Elk .vcxproj bestand dat door Visual Studio wordt gegenereerd, bevat deze MSBuild-elementen op het hoogste niveau. En ze worden in deze volgorde weergegeven, hoewel ze mogelijk meerdere exemplaren van elk dergelijk element op het hoogste niveau bevatten. Kenmerken Label zijn willekeurige tags die alleen door Visual Studio worden gebruikt als ondertekens voor bewerking; ze hebben geen andere functie.

<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>

In de volgende secties wordt het doel van elk van deze elementen beschreven en waarom ze op deze manier worden gerangschikt:

Projectelement

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

Project is het hoofdknooppunt. Hiermee geeft u de MSBuild-versie op die moet worden gebruikt en ook het standaarddoel dat moet worden uitgevoerd wanneer dit bestand wordt doorgegeven aan MSBuild.exe.

ProjectConfigurations ItemGroup-element

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations bevat de beschrijving van de projectconfiguratie. Voorbeelden zijn Foutopsporing |Win32, Release |Win32, Foutopsporing |ARM, enzovoort. Veel projectinstellingen zijn specifiek voor een bepaalde configuratie. U wilt bijvoorbeeld waarschijnlijk optimalisatie-eigenschappen instellen voor een release-build, maar niet voor een foutopsporingsbuild.

De ProjectConfigurations itemgroep wordt niet gebruikt tijdens de build. De Visual Studio IDE vereist dat het project wordt geladen. Deze itemgroep kan worden verplaatst naar een .props bestand en in het .vcxproj bestand worden geïmporteerd. Als u echter configuraties wilt toevoegen of verwijderen, moet u het .props bestand handmatig bewerken. U kunt de IDE niet gebruiken.

ProjectConfiguration-elementen

In het volgende codefragment ziet u een projectconfiguratie. In dit voorbeeld is 'Debug|x64' de configuratienaam. De naam van de projectconfiguratie moet de indeling $(Configuration)|$(Platform)hebben. Een ProjectConfiguration knooppunt kan twee eigenschappen hebben: Configuration en Platform. Deze eigenschappen worden automatisch ingesteld met de waarden die hier worden opgegeven wanneer de configuratie actief is.

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

De IDE verwacht een projectconfiguratie te vinden voor elke combinatie van Configuration waarden en Platform waarden die in alle ProjectConfiguration items worden gebruikt. Vaak betekent dit dat een project betekenisloze projectconfiguraties kan hebben om aan deze vereiste te voldoen. Als een project bijvoorbeeld deze configuraties heeft:

• Fouten opsporen|Win32
• Detailhandel|x64
• Fouten opsporen|x64
• Detailhandel |Win32

Als u vervolgens een nieuwe configuratie aan het project toevoegt, zegt u 'Speciale 32-bits optimalisatie|Win32" moet u ook de configuratie "Speciale 32-bits optimalisatie|x64" toevoegen, ook al is 'Speciale 32-bits optimalisatie' betekenisloos voor x64.

U kunt de build- en implementatieopdrachten uitschakelen voor elke configuratie in Solution Configuration Manager.

Globals PropertyGroup-element

<PropertyGroup Label="Globals" />

Globals bevat instellingen op projectniveau, zoals ProjectGuid, RootNamespaceen ApplicationType of ApplicationTypeRevision. De laatste twee definiëren vaak het doel-besturingssysteem. Een project kan slechts op één besturingssysteem zijn gericht, omdat verwijzingen en projectitems momenteel geen voorwaarden kunnen hebben. Deze eigenschappen worden doorgaans niet elders in het projectbestand overschreven. Deze groep is niet configuratieafhankelijk en bestaat doorgaans slechts één Globals groep in het projectbestand.

Microsoft.Cpp.default.props Import-element

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

Het eigenschappenvenster Microsoft.Cpp.default.props wordt geleverd met Visual Studio en kan niet worden gewijzigd. Het bevat de standaardinstellingen voor het project. De standaardinstellingen kunnen variëren, afhankelijk van het ApplicationType.

Configuration PropertyGroup-elementen

<PropertyGroup Label="Configuration" />

Een Configuration eigenschapsgroep heeft een gekoppelde configuratievoorwaarde (zoals Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") en wordt geleverd in meerdere exemplaren, één per configuratie. Deze eigenschappengroep fungeert als host voor de eigenschappen die zijn ingesteld voor een specifieke configuratie. Configuratie-eigenschappen omvatten PlatformToolset en bepalen ook de opname van systeemeigenschapsbladen in Microsoft.Cpp.props. Als u bijvoorbeeld de eigenschap <CharacterSet>Unicode</CharacterSet>definieert, wordt het eigenschappenvenster van het systeem microsoft gedefinieerd. Cpp.unicodesupport.props wordt opgenomen. Als u Microsoft.Cpp.props inspecteert, ziet u de regel: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Microsoft.Cpp.props Import-element

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

Het eigenschappenvenster Microsoft.Cpp.props (rechtstreeks of via import) definieert de standaardwaarden voor veel hulpprogrammaspecifieke eigenschappen. Voorbeelden hiervan zijn de eigenschappen Optimalisatie en Waarschuwingsniveau van de compiler, de eigenschap TypeLibraryName van het MIDL-hulpprogramma, enzovoort. Het importeert ook verschillende systeemeigenschapsbladen op basis waarvan configuratie-eigenschappen worden gedefinieerd in de eigenschappengroep direct voordat deze worden gedefinieerd.

Het element ExtensionSettings ImportGroup

<ImportGroup Label="ExtensionSettings" />

De ExtensionSettings groep bevat importbewerkingen voor de eigenschappenvensters die deel uitmaken van Build-aanpassingen. Een buildaanpassing wordt gedefinieerd door maximaal drie bestanden: een .targets bestand, een .props bestand en een .xml bestand. Deze importgroep bevat de importbewerkingen voor het .props bestand.

PropertySheets ImportGroup-elementen

<ImportGroup Label="PropertySheets" />

De PropertySheets groep bevat de importbewerkingen voor eigenschappenvensters van gebruikers. Deze importbewerkingen zijn de eigenschappenvensters die u toevoegt via de weergave Property Manager in Visual Studio. De volgorde waarin deze importen worden vermeld, is belangrijk en wordt weerspiegeld in Property Manager. Het projectbestand bevat normaal gesproken meerdere exemplaren van dit type importgroep, één voor elke projectconfiguratie.

UserMacros PropertyGroup-element

<PropertyGroup Label="UserMacros" />

UserMacros bevat eigenschappen die u maakt als variabelen die worden gebruikt om uw buildproces aan te passen. U kunt bijvoorbeeld een gebruikersmacro definiëren om uw aangepaste uitvoerpad te definiëren als $(CustomOutputPath) en deze gebruiken om andere variabelen te definiëren. Deze eigenschapsgroep bevat dergelijke eigenschappen. In Visual Studio wordt deze groep niet ingevuld in het projectbestand, omdat Microsoft C++ geen ondersteuning biedt voor gebruikersmacro's voor configuraties. Gebruikersmacro's worden ondersteund in eigenschappenvensters.

Eigenschappengroepelementen per configuratie

<PropertyGroup />

Er zijn meerdere exemplaren van deze eigenschapsgroep, één per configuratie voor alle projectconfiguraties. Aan elke eigenschapsgroep moet één configuratievoorwaarde zijn gekoppeld. Als er configuraties ontbreken, werkt het dialoogvenster Projecteigenschappen niet correct. In tegenstelling tot de eigenschappengroepen die eerder worden vermeld, heeft deze geen label. Deze groep bevat instellingen op projectconfiguratieniveau. Deze instellingen zijn van toepassing op alle bestanden die deel uitmaken van de opgegeven itemgroep. De metagegevens van de definitie van het aanpassingsitem worden hier geïnitialiseerd.

Deze PropertyGroup moet erna <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> komen en er mag geen andere PropertyGroup zonder label zijn voordat deze wordt bewerkt (anders werkt het bewerken van projecteigenschappen niet correct).

ItemDefinitionGroup-elementen per configuratie

<ItemDefinitionGroup />

Bevat itemdefinities. Deze definities moeten voldoen aan dezelfde voorwaardenregels als de labelloze elementen per configuratie PropertyGroup .

ItemGroup-elementen

<ItemGroup />

ItemGroup elementen bevatten de items (bronbestanden, enzovoort) in het project. Voorwaarden worden niet ondersteund voor Project-items (dat wil gezegd itemtypen die worden behandeld als projectitems volgens regelsdefinities).

De metagegevens moeten configuratievoorwaarden hebben voor elke configuratie, zelfs als ze allemaal hetzelfde zijn. Voorbeeld:

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

Het Visual Studio C++-projectsysteem biedt momenteel geen ondersteuning voor jokertekens in projectitems.

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

Het Visual Studio C++-projectsysteem biedt momenteel geen ondersteuning voor macro's in projectitems.

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

Verwijzingen worden opgegeven in een ItemGroup en hebben deze beperkingen:

• Verwijzingen bieden geen ondersteuning voor voorwaarden.

• Verwijzingen naar metagegevens bieden geen ondersteuning voor voorwaarden.

Microsoft.Cpp.targets Import-element

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

Definieert (rechtstreeks of via import) C++-doelen, zoals bouwen, opschonen, enzovoort.

Het element ExtensionTargets ImportGroup

<ImportGroup Label="ExtensionTargets" />

Deze groep bevat importbewerkingen voor de doelbestanden voor buildaanpassing.

Gevolgen van onjuiste volgorde

De Visual Studio IDE is afhankelijk van het projectbestand met de volgorde die eerder is beschreven. Wanneer u bijvoorbeeld een eigenschapswaarde op de eigenschappenpagina's definieert, plaatst de IDE de eigenschapsdefinitie meestal in de eigenschapsgroep met het lege label. Deze volgorde zorgt ervoor dat standaardwaarden die in de systeemeigenschapsbladen worden gebracht, worden overschreven door door de gebruiker gedefinieerde waarden. Op dezelfde manier worden de doelbestanden aan het einde geïmporteerd omdat ze de eerder gedefinieerde eigenschappen gebruiken en omdat ze doorgaans geen eigenschappen zelf definiëren. Gebruikerseigenschapsvensters worden ook geïmporteerd na de systeemeigenschapsvensters (opgenomen door Microsoft.Cpp.props). Deze volgorde zorgt ervoor dat de gebruiker standaardinstellingen kan overschrijven die door de systeemeigenschapsbladen worden meegenomen.

Als een .vcxproj bestand deze indeling niet volgt, zijn de buildresultaten mogelijk niet wat u verwacht. Als u bijvoorbeeld per ongeluk een systeemeigenschapsvenster importeert na de eigenschappenvensters die door de gebruiker zijn gedefinieerd, worden de gebruikersinstellingen overschreven door de eigenschappenvensters van het systeem.

Zelfs de IDE-ontwerptijd is afhankelijk van een bepaalde mate van de juiste volgorde van elementen. Als uw .vcxproj bestand bijvoorbeeld niet over de PropertySheets importgroep beschikt, kan de IDE mogelijk niet bepalen waar een nieuw eigenschappenvenster moet worden weergegeven dat de gebruiker heeft gemaakt in Property Manager. Dit kan ertoe leiden dat een gebruikersblad wordt overschreven door een systeemblad. Hoewel de heuristiek die door IDE wordt gebruikt kleine inconsistenties in de .vcxproj bestandsindeling kan verdragen, raden we u ten zeerste aan niet af te wijken van de structuur die eerder in dit artikel is weergegeven.

Hoe de IDE elementlabels gebruikt

Wanneer u in de IDE de eigenschap UseOfAtl instelt op de pagina met algemene eigenschappen, wordt deze geschreven naar de groep Configuratie-eigenschappen in het projectbestand. De eigenschap TargetName op dezelfde eigenschappenpagina wordt geschreven naar de eigenschapsgroep labelloos per configuratie. Visual Studio bekijkt het XML-bestand van de eigenschappenpagina voor de informatie over waar elke eigenschap moet worden geschreven. Voor de pagina Algemeen , ervan uitgaande dat u een Engelse versie van Visual Studio 2019 Enterprise Edition hebt, is %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xmldat bestand. Het XML-regelbestand van de eigenschappenpagina definieert de statische informatie over een regel en alle eigenschappen. Een dergelijke informatie is de voorkeurspositie van een regeleigenschap in het doelbestand (het bestand waarin de waarde wordt geschreven). De voorkeurspositie wordt opgegeven door het labelkenmerk op de projectbestandselementen.

Indeling eigenschappenvenster

Het volgende XML-fragment is een minimale indeling van een eigenschappenvensterbestand (.props). Het is vergelijkbaar met een .vcxproj bestand en de functionaliteit van de .props elementen kan worden afgeleid uit de eerdere discussie.

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

Als u uw eigen eigenschappenvenster wilt maken, kopieert u een van de .props bestanden in de VCTargets map en wijzigt u dit voor uw doeleinden. Voor Visual Studio 2019 Enterprise Edition is VCTargetshet standaardpad%ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Zie ook

C++ compiler en build-eigenschappen instellen in Visual Studio
XML-bestanden van eigenschappenpagina
.vcxproj bestanden en jokertekens