.vcxproj und .props Dateistruktur

MSBuild ist das Standardprojektsystem in Visual Studio. Wenn Sie "Neues Projekt in Visual C++ datei>" auswählen, erstellen Sie ein MSBuild-Projekt, dessen Einstellungen in einer XML-Projektdatei mit der Erweiterung .vcxprojgespeichert sind. Die Projektdatei kann auch Dateien und .targets Dateien importieren.props, in denen Einstellungen gespeichert werden können.

Wenn Sie beabsichtigen, Ihre Projekteigenschaften in der IDE zu Standard, empfehlen wir, nur Ihre .vcxproj Projekte in der IDE zu erstellen und zu ändern und manuelle Änderungen an den Dateien zu vermeiden. In den meisten Fällen müssen Sie die Projektdatei nie manuell bearbeiten. Manuelle Bearbeitungen können die Projektverbindungen unterbrechen, die zum Ändern von Projekteinstellungen auf den Eigenschaftenseiten von Visual Studio erforderlich sind, und kann zu Buildfehlern führen, die schwierig zu debuggen und zu reparieren sind. Weitere Informationen zur Verwendung der Eigenschaftenseiten finden Sie unter Festlegen von C++-Compiler- und Buildeigenschaften in Visual Studio.

Die Verwaltung vieler einzelner Projekte in der IDE wird mühsam und fehleranfällig. Es ist schwierig, Konsistenz zu Standard oder Standardisierung über mehrere zehn oder Hunderte von Projekten hinweg durchzusetzen. In diesen Fällen lohnt es sich, Ihre Projektdateien zu bearbeiten, um angepasste .props oder .targets Dateien für gemeinsame Eigenschaften in vielen Projekten zu verwenden. Sie können diese Dateien auch verwenden, wenn Sie Anpassungen benötigen, die in der IDE nicht möglich sind. Praktische Orte zum Einfügen von Anpassungen sind die Directory.Build.props und Directory.Build.targets Dateien, die automatisch in alle MSBuild-basierten Projekte importiert werden.

In einigen Fällen reichen angepasste .props oder .targets Dateien allein möglicherweise nicht für Ihre Projektmanagementanforderungen aus. Möglicherweise müssen Sie Projektdateien oder Eigenschaftenblätter manuell ändern .vcxproj . Die manuelle Bearbeitung erfordert ein gutes Verständnis von MSBuild und muss die Richtlinien in diesem Artikel befolgen. Damit die IDE Dateien automatisch laden und aktualisieren .vcxproj kann, gelten für diese Dateien mehrere Einschränkungen, die nicht für andere MSBuild-Projektdateien gelten. Fehler können dazu führen, dass die IDE abstürzt oder sich unerwartet verhält.

Für manuelle Bearbeitungsszenarien enthält dieser Artikel grundlegende Informationen zur Struktur und .vcxproj verwandten Dateien.

Wichtige Überlegungen

Wenn Sie sich dafür entscheiden, eine .vcxproj Datei manuell zu bearbeiten, beachten Sie die folgenden Fakten:

• Die Struktur der Datei muss einer vorgeschriebenen Form folgen, die in diesem Artikel beschrieben wird.

• Das Visual Studio C++-Projektsystem unterstützt derzeit keine Wild Karte oder Listen direkt in Projektelementen. Diese Formulare werden beispielsweise nicht unterstützt:

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

  Weitere Informationen zu wilden Karte Unterstützung in Projekten und möglichen Problemumgehungen finden Sie unter .vcxproj Dateien und Wild Karte s.

• Das Visual Studio C++-Projektsystem unterstützt derzeit keine Makros in Projektelementpfaden. Dieses Formular wird z. B. nicht unterstützt:

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

  "Nicht unterstützt" bedeutet, dass Makros nicht garantiert für alle Vorgänge in der IDE funktionieren. Makros, die ihren Wert in unterschiedlichen Konfigurationen nicht ändern, sollten funktionieren, werden jedoch möglicherweise nicht beibehalten, wenn ein Element in einen anderen Filter oder ein anderes Projekt verschoben wird. Makros, die ihren Wert für unterschiedliche Konfigurationen ändern, verursachen Probleme. Die IDE erwartet nicht, dass Projektelementpfade für verschiedene Projektkonfigurationen unterschiedlich sind.

• Damit Projekteigenschaften beim Bearbeiten im Dialogfeld "Projekteigenschaften " ordnungsgemäß hinzugefügt, entfernt oder geändert werden können, muss die Datei separate Gruppen für jede Projektkonfiguration enthalten. Die Bedingungen müssen in dieser Form sein:

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

• Jede Eigenschaft muss in der Gruppe mit der richtigen Bezeichnung angegeben werden, wie in der Eigenschaftsregeldatei angegeben. Weitere Informationen finden Sie unter Property page xml rule files (XML-Regeldateien für Eigenschaftenseiten).

.vcxproj Dateielemente

Sie können den Inhalt einer .vcxproj Datei mit einem beliebigen Text- oder XML-Editor prüfen. Sie können sie in Visual Studio anzeigen, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt klicken und anschließend Projekt entladen > Foo.vcxproj bearbeiten auswählen.

Zunächst werden Sie feststellen, dass die Elemente auf oberster Ebene in einer bestimmten Reihenfolge angezeigt werden. Beispiel:

• Die meisten Eigenschaftengruppen und Elementdefinitionsgruppen werden nach dem Import für „Microsoft.Cpp.Default.props“ angezeigt.

• Alle Ziele werden am Ende der Datei importiert.

• Es gibt mehrere Eigenschaftengruppen, die jeweils eine eindeutige Bezeichnung besitzen und in einer bestimmten Reihenfolge auftreten.

Die Reihenfolge der Elemente in der Projektdatei ist von entscheidender Bedeutung, da MSBuild auf einem sequenziellen Auswertungsmodell basiert. Wenn Ihre Projektdatei, einschließlich aller importierten .props und .targets Dateien, aus mehreren Definitionen einer Eigenschaft besteht, überschreibt die letzte Definition die vorherigen. Im folgenden Beispiel wird der Wert "xyz" während der Kompilierung festgelegt, da das MSBUild-Modul während der Auswertung auf sie zuletzt stößt.

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

Der folgende Codeausschnitt zeigt eine minimale .vcxproj Datei. Jede .vcxproj von Visual Studio generierte Datei enthält diese MSBuild-Elemente der obersten Ebene. Außerdem werden sie in dieser Reihenfolge angezeigt, obwohl sie möglicherweise mehrere Kopien jedes solchen Elements auf oberster Ebene enthalten können. Alle Label Attribute sind beliebige Tags, die nur von Visual Studio als Signposts zum Bearbeiten verwendet werden; sie haben keine andere 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>

In den folgenden Abschnitten wird der Zweck der einzelnen Elemente und deren Reihenfolge beschrieben:

Project-Element

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

Project ist der Stammknoten. Es gibt die zu verwendende MSBuild-Version und auch das Standardziel an, das ausgeführt werden soll, wenn diese Datei an MSBuild.exe übergeben wird.

ItemGroup-Element „ProjectConfigurations“

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations enthält die Beschreibung der Projektkonfiguration. Beispiele dafür sind „Debug|Win32“, „Release|Win32“ und „Debug|ARM“. Viele Projekteigenschaften sind für eine bestimmte Konfiguration spezifisch. Beispielsweise möchten Sie wahrscheinlich Optimierungseigenschaften für einen Releasebuild festlegen, aber keinen Debugbuild.

Die ProjectConfigurations Elementgruppe wird zur Erstellungszeit nicht verwendet. Für die Visual Studio-IDE muss das Projekt geladen werden. Diese Elementgruppe kann in eine .props Datei verschoben und in die .vcxproj Datei importiert werden. Wenn Sie jedoch Konfigurationen hinzufügen oder entfernen müssen, müssen Sie die .props Datei manuell bearbeiten. Sie können die IDE nicht verwenden.

ProjectConfiguration-Elemente

In folgendem Codeausschnitt wird eine Projektkonfiguration dargestellt. In diesem Beispiel ist "Debug|x64" der Konfigurationsname. Der Projektkonfigurationsname muss im Format vorliegen $(Configuration)|$(Platform). Ein ProjectConfiguration Knoten kann zwei Eigenschaften aufweisen: Configuration und Platform. Diese Eigenschaften werden automatisch mit den hier angegebenen Werten festgelegt, wenn die Konfiguration aktiv ist.

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

Die IDE erwartet, dass eine Projektkonfiguration für eine beliebige Kombination von und Platform Werten gefunden wird, die Configuration in allen ProjectConfiguration Elementen verwendet werden. Oft bedeutet dies, dass ein Projekt möglicherweise sinnlose Projektkonfigurationen hat, um diese Anforderung zu erfüllen. Gehen Sie von einem Projekt mit folgenden Konfigurationen aus:

• Debug|Win32

• Retail|Win32

• Special 32-bit Optimization|Win32

Das Projekt muss dann ebenfalls diese Konfigurationen enthalten, obwohl „Special 32-bit Optimization“ für x64 nicht von Bedeutung ist:

• Debuggen|x64

• Retail|x64

• Special 32-bit Optimization|x64

Sie können die Build- und Bereitstellungsbefehle für alle Konfigurationen im Konfigurations-Manager für Projektmappen deaktivieren.

PropertyGroup-Element „Globals“

<PropertyGroup Label="Globals" />

Globals enthält Einstellungen auf Projektebene, z ProjectGuid. B. , RootNamespaceund ApplicationType oder ApplicationTypeRevision. Die letzten beiden definieren häufig das Zielbetriebssystem. Ein Projekt kann nur auf ein einzelnes Betriebssystem abzielen, da derzeit Verweise und Projektelemente keine Bedingungen haben können. Diese Eigenschaften werden üblicherweise nicht an anderer Stelle in der Projektdatei überschrieben. Diese Gruppe ist nicht konfigurationsabhängig, und in der Regel ist nur eine Globals Gruppe in der Projektdatei vorhanden.

Import-Element „Microsoft.Cpp.default.props“

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

Das Eigenschaftenblatt "Microsoft.Cpp.default.props" ist im Lieferumfang von Visual Studio enthalten und kann nicht geändert werden. Es enthält die Standardeinstellungen für das Projekt. Die Standardwerte hängen von „ApplicationType“ ab.

PropertyGroup-Element „Configuration“

<PropertyGroup Label="Configuration" />

Eine Configuration-Eigenschaftengruppe besitzt eine angefügte Konfigurationsbedingung (z.B. Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") und liegt in mehreren Kopien (eine pro Konfiguration) vor. Diese Eigenschaftengruppe hostet die Eigenschaften, die für eine bestimmte Konfiguration festgelegt sind. Zu den Konfigurationseigenschaften zählt „PlatformToolset“. Außerdem steuern diese das Einschließen von Systemeigenschaftenblättern in Microsoft.Cpp.props. Wenn Sie beispielsweise die Eigenschaft <CharacterSet>Unicode</CharacterSet> definieren, wird das Systemeigenschaftenblatt microsoft.Cpp.unicodesupport.props eingeschlossen. Wenn Sie Microsoft.Cpp.props prüfen, wird die Zeile angezeigt: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Import-Element „Microsoft.Cpp.props“

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

Das Eigenschaftenblatt "Microsoft.Cpp.props " (direkt oder über Importe) definiert die Standardwerte für viele toolspezifische Eigenschaften. Beispiele sind die Eigenschaften Optimierung und Warnungsebene des Compilers, die TypeLibraryName-Eigenschaft des MIDL-Tools usw. Außerdem werden verschiedene Systemeigenschaftenblätter importiert, die darauf basieren, welche Konfigurationseigenschaften in der Eigenschaftengruppe unmittelbar davor definiert sind.

ImportGroup-Element „ExtensionSettings“

<ImportGroup Label="ExtensionSettings" />

Die ExtensionSettings-Gruppe enthält Importe für die Eigenschaftenblätter, die Teil der Buildanpassungen sind. Eine Buildanpassung wird durch bis zu drei Dateien definiert: eine .targets Datei, eine .props Datei und eine .xml Datei. Diese Importgruppe enthält die Importe für die .props Datei.

ImportGroup-Element „PropertySheets“

<ImportGroup Label="PropertySheets" />

Die PropertySheets-Gruppe enthält die Importe für Benutzereigenschaftenblätter. Bei diesen Importen handelt es sich um die Eigenschaftenblätter, die Sie über die Eigenschaften-Manager-Ansicht in Visual Studio hinzufügen. Die Reihenfolge, in der diese Importe aufgeführt werden, ist wichtig und wird im Eigenschaften-Manager dargestellt. Die Projektdatei enthält normalerweise mehrere Instanzen von dieser Art von Importgruppe (eine pro Projektkonfigurationen).

PropertyGroup-Element „UserMacros“

<PropertyGroup Label="UserMacros" />

UserMacros enthält Eigenschaften, die Sie als Variablen erstellen, die zum Anpassen des Buildprozesses verwendet werden. Sie können beispielsweise ein Benutzermakro definieren, um den benutzerdefinierten Ausgabepfad als „$(CustomOutputPath)“ zu definieren und diesen dafür verwenden, andere Variablen zu definieren. Diese Eigenschaftengruppe enthält diese Eigenschaften. In Visual Studio wird diese Gruppe nicht in der Projektdatei aufgefüllt, da Visual C++ Benutzermakros für Konfigurationen nicht unterstützt. Benutzermakros werden in Eigenschaftenblättern unterstützt.

PropertyGroup-Elemente pro Konfiguration

<PropertyGroup />

Es gibt mehrere Instanzen dieser Eigenschaftengruppe: eine pro Konfiguration für alle Projektkonfigurationen. Jeder Eigenschaftengruppe muss eine Konfigurationsbedingung angefügt sein. Wenn eine Konfiguration fehlt, funktioniert das Dialogfeld Projekteigenschaften nicht ordnungsgemäß. Im Gegensatz zu den zuvor aufgeführten Eigenschaftengruppen verfügt dies nicht über eine Bezeichnung. Diese Gruppe enthält Einstellungen auf Projektkonfigurationsebene. Diese Eigenschaften gelten für alle Dateien, die Teil der angegebenen Elementgruppe sind. Elementdefinitionsmetadaten für die Buildanpassung werden hier initialisiert.

Diese PropertyGroup muss folgen <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> , und es darf keine andere PropertyGroup ohne Bezeichnung vorhanden sein , bevor sie angezeigt wird (andernfalls funktioniert die Bearbeitung von Project-Eigenschaften nicht ordnungsgemäß).

ItemDefinitionGroup-Elemente pro Konfiguration

<ItemDefinitionGroup />

Enthält Elementdefinitionen. Diese Definitionen müssen den gleichen Bedingungen entsprechen wie die Bezeichnungs-weniger pro Konfigurationselemente PropertyGroup .

ItemGroup-Elemente

<ItemGroup />

ItemGroup elemente enthalten die Elemente (Quelldateien usw.) im Projekt. Bedingungen werden für Project-Elemente nicht unterstützt (d. h. Elementtypen, die als Projektelemente anhand von Regeldefinitionen behandelt werden).

Die Metadaten sollten über Konfigurationsbedingungen für jede Konfiguration verfügen, auch wenn sie alle gleich sind. Beispiel:

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

Das Visual Studio C++-Projektsystem unterstützt derzeit keine Wild Karte in Projektelementen.

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

Das Visual Studio C++-Projektsystem unterstützt derzeit keine Makros in Projektelementen.

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

Verweise werden in einem ItemGroup-Element angegeben und haben folgende Einschränkungen:

• Verweise unterstützen keine Bedingungen.

• Verweise auf Metadaten unterstützen keine Bedingungen.

Import-Element „Microsoft.Cpp.targets“

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

Definiert (direkt oder über Importe) C++-Ziele wie Build, sauber usw.

ImportGroup-Element „ExtensionTargets“

<ImportGroup Label="ExtensionTargets" />

Diese Gruppe enthält Importe für die Zieldateien der Buildanpassung.

Folgen einer falschen Sortierung

Die Visual Studio-IDE hängt von der Zuvor beschriebenen Sortierung der Projektdatei ab. Wenn Sie beispielsweise einen Eigenschaftswert auf den Eigenschaftenseiten definieren, platziert die IDE die Eigenschaftsdefinition generell in der Eigenschaftengruppe mit der leeren Bezeichnung. Durch diese Sortierung wird sichergestellt, dass die in den Systemeigenschaftenblättern enthaltenen Standardwerte durch benutzerdefinierte Werte überschrieben werden. Ebenso werden die Zieldateien am Ende importiert, da sie die zuvor definierten Eigenschaften nutzen und da sie im Allgemeinen keine Eigenschaften selbst definieren. Ebenso werden Benutzereigenschaftenblätter nach den Systemeigenschaftenblättern importiert (eingeschlossen von Microsoft.Cpp.props). Diese Reihenfolge stellt sicher, dass der Benutzer alle Standardwerte außer Kraft setzen kann, die von den Systemeigenschaftenblättern bereitgestellt werden.

Wenn eine .vcxproj Datei diesem Layout nicht folgt, sind die Buildergebnisse möglicherweise nicht das, was Sie erwarten. Wenn Sie z. B. versehentlich ein Systemeigenschaftenblatt nach den vom Benutzer definierten Eigenschaftenblättern importieren, werden die Benutzereinstellungen von den Systemeigenschaftenblättern außer Kraft gesetzt.

Selbst die IDE-Entwurfszeit hängt teilweise von der korrekten Anordnung von Elementen ab. Wenn ihre .vcxproj Datei beispielsweise nicht über die PropertySheets Importgruppe verfügt, kann die IDE möglicherweise nicht ermitteln, wo ein neues Eigenschaftenblatt platziert werden soll, das der Benutzer im Eigenschaften-Manager erstellt hat. Dies kann dazu führen, dass ein Benutzerblatt von einem Systemblatt überschrieben wird. Obwohl die von IDE verwendete Heuristik kleinere Inkonsistenzen im .vcxproj Dateilayout tolerieren kann, empfehlen wir dringend, dass Sie nicht von der struktur abweichen, die weiter oben in diesem Artikel gezeigt wird.

Verwendung von Elementbezeichnungen durch die IDE

Wenn Sie in der IDE die UseOfAtl-Eigenschaft auf der allgemeinen Eigenschaftenseite festlegen, wird sie in die Konfigurationseigenschaftengruppe in der Projektdatei geschrieben. Die TargetName-Eigenschaft auf derselben Eigenschaftenseite wird in die Eigenschaftsgruppe ohne Bezeichnung pro Konfiguration geschrieben. Visual Studio sucht in der XML-Datei der Eigenschaftenseite nach Informationen dazu, wohin jede Eigenschaft geschrieben werden soll. Für die Allgemeine Eigenschaftsseite, vorausgesetzt, Sie verfügen über eine englische Version von Visual Studio 2019 Enterprise Edition, ist %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xmldiese Datei . Die XML-Regeldatei der Eigenschaftenseite definiert die statischen Informationen einer Regel und deren Eigenschaften. Eine dieser Informationen ist die bevorzugte Position einer Regeleigenschaft in der Zieldatei (die Datei, in die deren Wert geschrieben wird). Die bevorzugte Position wird vom Label-Attribut in den Elementen der Projektdatei angegeben.

Layout von Eigenschaftenblättern

Der folgende XML-Codeausschnitt stellt das minimale Layout einer Eigenschaftenblattdatei (.props) dar. Es ähnelt einer .vcxproj Datei, und die Funktionalität der .props Elemente kann aus der vorherigen Diskussion abgeleitet werden.

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

Um ein eigenes Eigenschaftenblatt zu erstellen, kopieren Sie eine der .props Dateien im VCTargets Ordner, und ändern Sie es für Ihre Zwecke. Für Visual Studio 2019 Enterprise Edition ist %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargetsder Standardpfad VCTargets .

Siehe auch

Festlegen der Compiler- und Buildeigenschaften (C++) in Visual Studio
Eigenschaftenseite: XML-Dateien
.vcxproj-Dateien und -Platzhalter