`.vcxproj` och `.props` filstruktur

2025-10-09

MSBuild är standardprojektsystemet i Visual Studio. när du väljer Nytt>filprojekt i Visual C++ skapar du ett MSBuild-projekt vars inställningar lagras i en XML-projektfil som har tillägget .vcxproj. Projektfilen kan också importera .props filer och .targets filer där inställningarna kan lagras.

Om du tänker underhålla projektegenskaperna i IDE rekommenderar vi att du bara skapar och ändrar dina .vcxproj projekt i IDE:t och undviker manuella redigeringar av filerna. I de flesta fall behöver du aldrig redigera projektfilen manuellt. Manuella ändringar kan bryta de projektanslutningar som krävs för att ändra projektinställningarna på Visual Studio-egenskapssidorna och kan orsaka byggfel som är svåra att felsöka och reparera. Mer information om hur du använder egenskapssidorna finns i Ange C++-kompilator- och byggegenskaper i Visual Studio.

I stor skala blir det tråkigt och felbenäget att hantera många enskilda projekt i IDE. Det är svårt att upprätthålla konsekvens eller framtvinga standardisering i tiotals eller hundratals projekt. I dessa fall är det värt att redigera dina projektfiler för att använda anpassade .props filer eller .targets filer för vanliga egenskaper i många projekt. Du kan också använda dessa filer när du behöver anpassningar som inte är möjliga i IDE. Praktiska platser för att infoga anpassningar är Directory.Build.props filerna och Directory.Build.targets som automatiskt importeras i alla MSBuild-baserade projekt.

I vissa fall kanske anpassade .props filer eller .targets enbart filer inte räcker för dina projekthanteringsbehov. Du kan fortfarande behöva ändra .vcxproj projektfiler eller egenskapsblad manuellt. Manuell redigering kräver en god förståelse för MSBuild och måste följa riktlinjerna i den här artikeln. För att IDE ska kunna läsa in och uppdatera .vcxproj filer automatiskt har dessa filer flera begränsningar som inte gäller för andra MSBuild-projektfiler. Misstag kan orsaka att IDE kraschar eller beter sig på oväntade sätt.

För manuella redigeringsscenarier innehåller den här artikeln grundläggande information om strukturen .vcxproj för och relaterade filer.

Viktiga överväganden

Om du väljer att redigera en .vcxproj fil manuellt bör du vara medveten om följande fakta:

Filens struktur måste följa ett föreskrivet formulär som beskrivs i den här artikeln.
Visual Studio C++-projektsystemet stöder för närvarande inte jokertecken eller listor direkt i projektobjekt. Dessa formulär stöds till exempel inte:
```
<ItemGroup>
   <None Include="*.txt"/>
   <ClCompile Include="a.cpp;b.cpp"/>
</ItemGroup>
```
Mer information om stöd för jokertecken i projekt och möjliga lösningar finns i .vcxproj filer och jokertecken.
Visual Studio C++-projektsystemet stöder för närvarande inte makron i projektobjektsökvägar. Det här formuläret stöds till exempel inte:
```
<ItemGroup>
   <ClCompile Include="$(IntDir)\generated.cpp"/>
</ItemGroup>
```
"Stöds inte" innebär att makron inte garanteras fungera för alla åtgärder i IDE. Makron som inte ändrar sitt värde i olika konfigurationer bör fungera, men som kanske inte bevaras om ett objekt flyttas till ett annat filter eller projekt. Makron som ändrar sitt värde för olika konfigurationer orsakar problem. IDE:t förväntar sig inte att projektobjektsökvägarna ska vara olika för olika projektkonfigurationer.
Om du vill lägga till, ta bort eller ändra projektegenskaperna korrekt när du redigerar dem i dialogrutan Projektegenskaper måste filen innehålla separata grupper för varje projektkonfiguration. Villkoren måste vara i följande form:
```
Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"
```
Varje egenskap måste anges i gruppen med rätt etikett, enligt vad som anges i egenskapsregelfilen. Mer information finns i Xml-regelfiler för egenskapssida.

`.vcxproj` filelement

Du kan granska innehållet i en .vcxproj fil med hjälp av valfri text- eller XML-redigerare. Du kan visa det i Visual Studio genom att högerklicka på projektet i Solution Explorer, välja Ta bort projekt och sedan välja Redigera Foo.vcxproj.

Det första du bör notera är att elementen på den översta nivån visas i en viss ordning. Till exempel:

De flesta egenskapsgrupper och objektdefinitionsgrupper sker efter importen för Microsoft.Cpp.Default.props.
Alla mål importeras i slutet av filen.
Det finns flera egenskapsgrupper, var och en med en unik etikett, och de förekommer i en viss ordning.

Ordningen på element i projektfilen är mycket viktig eftersom MSBuild baseras på en sekventiell utvärderingsmodell. Om projektfilen, inklusive alla importerade .props filer och .targets filer, består av flera definitioner av en egenskap åsidosätter den senaste definitionen de föregående. I följande exempel anges värdet "xyz" under kompilering eftersom MSBUild-motorn stöter på det senast under utvärderingen.

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

Följande kodfragment visar en minimal .vcxproj fil. Alla .vcxproj filer som genereras av Visual Studio innehåller dessa MSBuild-element på den översta nivån. Och de visas i den här ordningen, även om de kan innehålla flera kopior av varje sådant element på den översta nivån. Alla Label attribut är godtyckliga taggar som endast används av Visual Studio som skyltar för redigering. De har ingen annan funktion.

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

I följande avsnitt beskrivs syftet med vart och ett av dessa element och varför de ordnas på det här sättet:

Projektelement

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

Project är rotnoden. Den anger vilken MSBuild-version som ska användas och även standardmålet som ska köras när filen skickas till MSBuild.exe.

Elementet ProjectConfigurations ItemGroup

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations innehåller beskrivningen av projektkonfigurationen. Exempel är Felsökning|Win32, Release|Win32, Debug|ARM och så vidare. Många projektinställningar är specifika för en viss konfiguration. Du vill till exempel förmodligen ange optimeringsegenskaper för en versionsversion, men inte en felsökningsversion.

Objektgruppen ProjectConfigurations används inte vid bygget. Visual Studio IDE kräver att projektet läses in. Den här objektgruppen kan flyttas till en .props fil och importeras .vcxproj till filen. Men om du behöver lägga till eller ta bort konfigurationer måste du dock redigera .props filen manuellt. Du kan inte använda IDE:t.

ProjectConfiguration-element

Följande kodfragment visar en projektkonfiguration. I det här exemplet är "Felsökning|x64" konfigurationsnamnet. Projektkonfigurationsnamnet måste vara i formatet $(Configuration)|$(Platform). En ProjectConfiguration nod kan ha två egenskaper: Configuration och Platform. Dessa egenskaper anges automatiskt med de värden som anges här när konfigurationen är aktiv.

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

IDE förväntar sig att hitta en projektkonfiguration för alla kombinationer av Configuration och Platform värden som används i alla ProjectConfiguration objekt. Ofta innebär det att ett projekt kan ha meningslösa projektkonfigurationer för att uppfylla detta krav. Om ett projekt till exempel har följande konfigurationer:

Felsöka|Win32
Detaljhandel|x64
Felsöka|x64
Detaljhandel|Win32

Om du sedan lägger till en ny konfiguration i projektet säger du "Särskild 32-bitarsoptimering|Win32" måste du också lägga till konfigurationen "Special 32-bitarsoptimering|x64", även om "Special 32-bitarsoptimering" är meningslös för x64.

Du kan inaktivera kommandot build och deploy för valfri konfiguration i Solution Configuration Manager.

Elementet Globals PropertyGroup

<PropertyGroup Label="Globals" />

Globals innehåller inställningar på projektnivå, till exempel ProjectGuid, RootNamespaceoch ApplicationType eller ApplicationTypeRevision. De två sista definierar ofta måloperativsystemet. Ett projekt kan bara rikta in sig på ett enskilt operativsystem eftersom referenser och projektobjekt för närvarande inte kan ha villkor. Dessa egenskaper åsidosättas vanligtvis inte någon annanstans i projektfilen. Den här gruppen är inte konfigurationsberoende och finns vanligtvis bara en Globals grupp i projektfilen.

Importelementet Microsoft.Cpp.default.props

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

Egenskapsbladet Microsoft.Cpp.default.props levereras med Visual Studio och kan inte ändras. Den innehåller standardinställningarna för projektet. Standardvärdena kan variera beroende på ApplicationType.

Configuration PropertyGroup-element

<PropertyGroup Label="Configuration" />

En Configuration egenskapsgrupp har ett kopplat konfigurationsvillkor (till exempel Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") och finns i flera kopior, en per konfiguration. Den här egenskapsgruppen är värd för de egenskaper som har angetts för en specifik konfiguration. Konfigurationsegenskaper inkluderar PlatformToolset och styr även inkluderingen av systemegenskapsblad i Microsoft.Cpp.props. Om du till exempel definierar egenskapen <CharacterSet>Unicode</CharacterSet>, kommer systemegenskapsbladet microsoft. Cpp.unicodesupport.props inkluderas . Om du inspekterar Microsoft.Cpp.props visas raden: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Importelement för Microsoft.Cpp.props

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

Egenskapsbladet Microsoft.Cpp.props (direkt eller via importer) definierar standardvärdena för många verktygsspecifika egenskaper. Exempel är kompilatorns egenskaper för optimering och varningsnivå, midl-verktygets typelibraryname-egenskap och så vidare. Den importerar också olika systemegenskapsblad baserat på vilka konfigurationsegenskaper som definieras i egenskapsgruppen omedelbart före den.

ExtensionSettings ImportGroup-element

<ImportGroup Label="ExtensionSettings" />

Gruppen ExtensionSettings innehåller importer för egenskapsbladen som ingår i Bygganpassningar. En build-anpassning definieras av upp till tre filer: en .targets fil, en .props fil och en .xml fil. Den här importgruppen innehåller importen för .props filen.

PropertySheets ImportGroup-element

<ImportGroup Label="PropertySheets" />

Gruppen PropertySheets innehåller importerna för användaregenskapsblad. Dessa importer är de egenskapsblad som du lägger till via Property Manager-vyn i Visual Studio. Den ordning i vilken dessa importer visas är viktig och återspeglas i Egenskapshanteraren. Projektfilen innehåller normalt flera instanser av den här typen av importgrupp, en för varje projektkonfiguration.

UserMacros PropertyGroup-element

<PropertyGroup Label="UserMacros" />

UserMacros innehåller egenskaper som du skapar som variabler som används för att anpassa byggprocessen. Du kan till exempel definiera ett användarmakro för att definiera din anpassade utdatasökväg som $(CustomOutputPath) och använda den för att definiera andra variabler. Den här egenskapsgruppen har sådana egenskaper. I Visual Studio fylls inte den här gruppen i projektfilen eftersom Visual C++ inte stöder användarmakro för konfigurationer. Användarmakron stöds i egenskapsblad.

Egenskapsgruppselement per konfiguration

<PropertyGroup />

Det finns flera instanser av den här egenskapsgruppen, en per konfiguration för alla projektkonfigurationer. Varje egenskapsgrupp måste ha ett konfigurationsvillkor kopplat. Om några konfigurationer saknas fungerar inte dialogrutan Projektegenskaper korrekt. Till skillnad från de egenskapsgrupper som anges tidigare har den här inte någon etikett. Den här gruppen innehåller inställningar på projektkonfigurationsnivå. De här inställningarna gäller för alla filer som ingår i den angivna objektgruppen. Metadata för versionsanpassningsobjektdefinition initieras här.

Den här PropertyGroup måste komma efter <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> och det får inte finnas någon annan PropertyGroup utan etikett innan den (annars fungerar inte redigeringen av projektegenskaper korrekt).

ObjektDefinitionGroup-element per konfiguration

<ItemDefinitionGroup />

Innehåller objektdefinitioner. Dessa definitioner måste följa samma villkorsregler som de etikettlösa elementen per konfiguration PropertyGroup .

ItemGroup-element

<ItemGroup />

ItemGroup element innehåller objekten (källfiler och så vidare) i projektet. Villkor stöds inte för Projektobjekt (dvs. objekttyper som behandlas som projektobjekt efter regeldefinitioner).

Metadata bör ha konfigurationsvillkor för varje konfiguration, även om de är likadana. Till exempel:

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

Visual Studio C++-projektsystemet stöder för närvarande inte jokertecken i projektobjekt.

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

Visual Studio C++-projektsystemet stöder för närvarande inte makron i projektobjekt.

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

Referenser anges i en ItemGroup och de har följande begränsningar:

Referenser stöder inte villkor.
Referensmetadata stöder inte villkor.

Importelementet Microsoft.Cpp.targets

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

Definierar (direkt eller via importer) C++-mål som build, clean och så vidare.

ExtensionTargets ImportGroup-element

<ImportGroup Label="ExtensionTargets" />

Den här gruppen innehåller importer för målfilerna för build-anpassning.

Konsekvenser av felaktig beställning

Visual Studio IDE beror på att projektfilen har den ordning som beskrevs tidigare. När du till exempel definierar ett egenskapsvärde på egenskapssidorna placerar IDE vanligtvis egenskapsdefinitionen i egenskapsgruppen med den tomma etiketten. Den här ordningen säkerställer att standardvärdena i systemegenskapsbladen åsidosätts av användardefinierade värden. På samma sätt importeras målfilerna i slutet eftersom de använder de egenskaper som definierats tidigare och eftersom de vanligtvis inte definierar själva egenskaperna. På samma sätt importeras användaregenskapsbladen efter systemegenskapsbladen (ingår i Microsoft.Cpp.props). Den här ordningen säkerställer att användaren kan åsidosätta alla standardvärden som tas in av systemegenskapsbladen.

Om en .vcxproj fil inte följer den här layouten kanske inte byggresultatet är det du förväntar dig. Om du till exempel av misstag importerar ett systemegenskapsblad efter de egenskapsblad som definierats av användaren, blir användarinställningarna åsidosatta av systemegenskapsbladen.

Även IDE-designens tidsupplevelse beror till viss del på rätt ordning på elementen. Om .vcxproj filen till exempel inte har PropertySheets importgruppen kanske IDE:n inte kan avgöra var ett nytt egenskapsblad som användaren har skapat i Property Manager ska placeras. Det kan leda till att ett användarblad åsidosättas av ett systemblad. Även om heuristiken som används av IDE kan tolerera mindre inkonsekvenser i fillayouten .vcxproj rekommenderar vi starkt att du inte avviker från strukturen som visades tidigare i den här artikeln.

Hur IDE använder elementetiketter

När du anger egenskapen UseOfAtl på sidan allmän egenskap i IDE skrivs den till egenskapsgruppen Konfiguration i projektfilen. Egenskapen TargetName på samma egenskapssida skrivs till egenskapsgruppen etikettlös per konfiguration. Visual Studio tittar på egenskapssidans XML-fil för information om var varje egenskap ska skrivas. För egenskapssidan Allmänt , förutsatt att du har en engelsk version av Visual Studio 2019 Enterprise Edition, är %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xmlfilen . XML-regelfilen för egenskapssidan definierar statisk information om en regel och alla dess egenskaper. En sådan information är den föredragna positionen för en regelegenskap i målfilen (filen där dess värde skrivs). Önskad position anges av attributet Etikett för projektfilelementen.

Layout för egenskapsblad

Följande XML-kodfragment är en minimal layout för en egenskapsbladsfil (.props). Det liknar en .vcxproj fil och funktionerna i elementen .props kan härledas från den tidigare diskussionen.

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

Om du vill skapa ett eget egenskapsblad kopierar du en av .props filerna i VCTargets mappen och ändrar den för dina syften. För Visual Studio 2019 Enterprise-utgåvan är %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargetsstandardsökvägen VCTargets .

Se även

Ange C++-kompilator- och byggegenskaper i Visual Studio
XML-filer för egenskapssida
.vcxproj filer och jokertecken

Feedback

Var den här sidan till hjälp?