Udostępnij za pośrednictwem

.vcxproj i .props struktura plików

  • Artykuł

Program MSBuild jest domyślnym systemem projektu w programie Visual Studio. Po wybraniu pozycji Plik>nowy projekt w programie Visual C++ tworzysz projekt MSBuild, którego ustawienia są przechowywane w pliku projektu XML z rozszerzeniem ..vcxproj Plik projektu może również importować .props pliki i .targets pliki, w których można przechowywać ustawienia.

Jeśli zamierzasz zachować właściwości projektu w środowisku IDE, zalecamy tylko tworzenie i modyfikowanie .vcxproj projektów w środowisku IDE i unikanie ręcznych edycji plików. W większości przypadków nigdy nie trzeba ręcznie edytować pliku projektu. Ręczne edycje mogą spowodować przerwanie połączeń projektu wymaganych do zmodyfikowania ustawień projektu na stronach właściwości programu Visual Studio i mogą powodować błędy kompilacji, które są trudne do debugowania i naprawy. Aby uzyskać więcej informacji na temat używania stron właściwości, zobacz Set C++ compiler and build properties in Visual Studio (Ustawianie właściwości kompilatora języka C++ i kompilowania w programie Visual Studio).

Na dużą skalę zarządzanie wieloma poszczególnymi projektami w środowisku IDE staje się żmudne i podatne na błędy. Trudno jest zachować spójność lub wymusić standaryzację w dziesiątkach lub setkach projektów. W takich przypadkach warto edytować pliki projektu, aby używać dostosowanych .props lub .targets plików dla typowych właściwości w wielu projektach. Te pliki mogą być również używane, gdy wymagane są dostosowania, które nie są możliwe w środowisku IDE. Przydatne miejsca do wstawiania dostosowań to Directory.Build.props pliki i Directory.Build.targets , które są automatycznie importowane we wszystkich projektach opartych na programie MSBuild.

W niektórych przypadkach samodzielnie dostosowane .props lub .targets pliki mogą nie być wystarczające dla potrzeb zarządzania projektami. Nadal może być konieczne ręczne modyfikowanie .vcxproj plików projektu lub arkuszy właściwości. Ręczne edytowanie wymaga dobrego zrozumienia programu MSBuild i musi postępować zgodnie z wytycznymi w tym artykule. Aby środowisko IDE ładowało i aktualizowało .vcxproj pliki automatycznie, te pliki mają kilka ograniczeń, które nie mają zastosowania do innych plików projektu MSBuild. Błędy mogą spowodować awarię środowiska IDE lub zachowanie się w nieoczekiwany sposób.

W przypadku scenariuszy ręcznego edytowania ten artykuł zawiera podstawowe informacje o strukturze i powiązanych .vcxproj plikach.

Ważne uwagi

Jeśli zdecydujesz się ręcznie edytować .vcxproj plik, należy pamiętać o następujących faktach:

  • Struktura pliku musi być zgodna z określonym formularzem, który został opisany w tym artykule.

  • System projektu Visual Studio C++ obecnie nie obsługuje symboli wieloznacznych ani list bezpośrednio w elementach projektu. Na przykład te formularze nie są obsługiwane:

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

    Aby uzyskać więcej informacji na temat obsługi symboli wieloznacznych w projektach i możliwych obejść, zobacz .vcxproj pliki i symbole wieloznaczne.

  • System projektu Visual Studio C++ obecnie nie obsługuje makr w ścieżkach elementów projektu. Na przykład ten formularz nie jest obsługiwany:

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

    "Nieobsługiwane" oznacza, że makra nie mają gwarancji, że działają dla wszystkich operacji w środowisku IDE. Makra, które nie zmieniają ich wartości w różnych konfiguracjach, powinny działać, ale mogą nie być zachowywane, jeśli element zostanie przeniesiony do innego filtru lub projektu. Makra, które zmieniają ich wartość dla różnych konfiguracji, spowodują problemy. Środowisko IDE nie oczekuje, że ścieżki elementów projektu będą inne dla różnych konfiguracji projektu.

  • Aby poprawnie dodawać, usuwać lub modyfikować właściwości projektu podczas edytowania ich w oknie dialogowym Właściwości projektu, plik musi zawierać oddzielne grupy dla każdej konfiguracji projektu. Warunki muszą mieć następującą postać:

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

  • Każda właściwość musi być określona w grupie z poprawną etykietą, jak określono w pliku reguły właściwości. Aby uzyskać więcej informacji, zobacz Pliki reguł xml strony właściwości.

.vcxproj elementy pliku

Zawartość pliku można sprawdzić .vcxproj przy użyciu dowolnego tekstu lub edytora XML. Możesz go wyświetlić w programie Visual Studio, klikając prawym przyciskiem myszy projekt w Eksplorator rozwiązań, wybierając pozycję Zwolnij projekt, a następnie wybierając polecenie Edytuj Foo.vcxproj.

Pierwszą rzeczą, którą należy zauważyć, jest to, że elementy najwyższego poziomu są wyświetlane w określonej kolejności. Na przykład:

  • Większość grup właściwości i grup definicji elementów występuje po zaimportowaniu elementu Microsoft.Cpp.Default.props.

  • Wszystkie obiekty docelowe są importowane na końcu pliku.

  • Istnieje wiele grup właściwości, z których każda ma unikatową etykietę, i występuje w określonej kolejności.

Kolejność elementów w pliku projektu jest niezwykle ważna, ponieważ program MSBuild jest oparty na modelu oceny sekwencyjnej. Jeśli plik projektu, w tym wszystkie zaimportowane .props pliki i .targets zawiera wiele definicji właściwości, ostatnia definicja zastępuje powyższe. W poniższym przykładzie wartość "xyz" zostanie ustawiona podczas kompilacji, ponieważ aparat MSBUild napotka ją ostatnio podczas oceny.

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

Poniższy fragment kodu przedstawia minimalny .vcxproj plik. Każdy .vcxproj plik wygenerowany przez program Visual Studio będzie zawierać te elementy programu MSBuild najwyższego poziomu. Będą one wyświetlane w tej kolejności, chociaż mogą zawierać wiele kopii każdego z takich elementów najwyższego poziomu. Wszystkie Label atrybuty są dowolnymi tagami, które są używane tylko przez program Visual Studio jako znaki do edycji; nie mają żadnej innej funkcji.

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

W poniższych sekcjach opisano przeznaczenie każdego z tych elementów i dlaczego są one uporządkowane w ten sposób:

Project, element

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

Project jest węzłem głównym. Określa wersję programu MSBuild do użycia, a także domyślny element docelowy do wykonania, gdy ten plik zostanie przekazany do MSBuild.exe.

ProjectConfigurations, element ItemGroup

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations zawiera opis konfiguracji projektu. Przykłady to Debugowanie|Win32, Release|Win32, Debug|ARM i tak dalej. Wiele ustawień projektu jest specyficznych dla danej konfiguracji. Na przykład prawdopodobnie chcesz ustawić właściwości optymalizacji dla kompilacji wydania, ale nie kompilacji debugowania.

Grupa ProjectConfigurations elementów nie jest używana w czasie kompilacji. Środowisko IDE programu Visual Studio wymaga załadowania projektu. Tę grupę .props elementów można przenieść do pliku i zaimportować do .vcxproj pliku. Jednak w takim przypadku, jeśli musisz dodać lub usunąć konfiguracje, musisz ręcznie edytować .props plik; nie można użyć środowiska IDE.

Elementy konfiguracji projektu

Poniższy fragment kodu przedstawia konfigurację projektu. W tym przykładzie "Debuguj|x64" jest nazwą konfiguracji. Nazwa konfiguracji projektu musi mieć format $(Configuration)|$(Platform). Węzeł ProjectConfiguration może mieć dwie właściwości: Configuration i Platform. Te właściwości są ustawiane automatycznie z wartościami określonymi tutaj, gdy konfiguracja jest aktywna.

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

Środowisko IDE oczekuje znalezienia konfiguracji projektu dla dowolnej kombinacji Configuration wartości i Platform używanych we wszystkich ProjectConfiguration elementach. Często oznacza to, że projekt może mieć bez znaczenia konfiguracje projektu, aby spełnić to wymaganie. Jeśli na przykład projekt ma następujące konfiguracje:

  • Debugowanie|Win32

  • Sprzedaż detaliczna|Win32

  • Specjalna optymalizacja 32-bitowa|Win32

następnie musi mieć te konfiguracje, mimo że "Specjalna optymalizacja 32-bitowa" jest bez znaczenia dla x64:

  • Debugowanie|x64

  • Sprzedaż detaliczna|x64

  • Specjalna optymalizacja 32-bitowa|x64

Polecenia kompilacji i wdrażania można wyłączyć dla dowolnej konfiguracji w programie Solution Configuration Manager.

Globals PropertyGroup, element

<PropertyGroup Label="Globals" />

Globals zawiera ustawienia na poziomie projektu, takie jak ProjectGuid, RootNamespacei lub ApplicationType ApplicationTypeRevision. Dwa ostatnie często definiują docelowy system operacyjny. Projekt może dotyczyć tylko jednego systemu operacyjnego, ponieważ obecnie odwołania i elementy projektu nie mogą mieć warunków. Te właściwości zazwyczaj nie są zastępowane w innym miejscu w pliku projektu. Ta grupa nie jest zależna od konfiguracji i zazwyczaj w pliku projektu istnieje tylko jedna Globals grupa.

Microsoft.Cpp.default.props, element Import

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

Arkusz właściwości Microsoft.Cpp.default.props jest dostarczany z programem Visual Studio i nie można go modyfikować. Zawiera on ustawienia domyślne projektu. Wartości domyślne mogą się różnić w zależności od typu aplikacji.

Elementy Configuration PropertyGroup

<PropertyGroup Label="Configuration" />

Grupa Configuration właściwości ma dołączony warunek konfiguracji (taki jak Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") i znajduje się w wielu kopiach, po jednym na konfigurację. Ta grupa właściwości hostuje właściwości ustawione dla określonej konfiguracji. Właściwości konfiguracji obejmują platformToolset, a także kontrolowanie dołączania arkuszy właściwości systemowych w pliku Microsoft.Cpp.props. Jeśli na przykład zdefiniujesz właściwość <CharacterSet>Unicode</CharacterSet>, wówczas systemowy arkusz właściwości microsoft. Plik Cpp.unicodesupport.props zostanie uwzględniony. Jeśli sprawdzisz plik Microsoft.Cpp.props, zobaczysz wiersz: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Microsoft.Cpp.props, element Import

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

Arkusz właściwości Microsoft.Cpp.props (bezpośrednio lub za pośrednictwem importu) definiuje wartości domyślne dla wielu właściwości specyficznych dla narzędzi. Przykłady obejmują właściwości optymalizacji i poziomu ostrzeżenia kompilatora, właściwość TypeLibraryName narzędzia MIDL itd. Importuje również różne arkusze właściwości systemowych na podstawie właściwości konfiguracji zdefiniowanych w grupie właściwości bezpośrednio przed nim.

ExtensionSettings ImportGroup, element

<ImportGroup Label="ExtensionSettings" />

Grupa ExtensionSettings zawiera importy arkuszy właściwości, które są częścią dostosowań kompilacji. Dostosowywanie kompilacji jest definiowane przez maksymalnie trzy pliki: .targets plik, .props plik i .xml plik. Ta grupa importu zawiera importy dla .props pliku.

Elementy PropertySheets ImportGroup

<ImportGroup Label="PropertySheets" />

Grupa PropertySheets zawiera importy dla arkuszy właściwości użytkownika. Te importy to arkusze właściwości dodawane za pośrednictwem widoku Menedżera właściwości w programie Visual Studio. Kolejność, w której wymieniono te importy, jest ważna i odzwierciedlana w Menedżerze właściwości. Plik projektu zwykle zawiera wiele wystąpień tego rodzaju grupy importu, po jednym dla każdej konfiguracji projektu.

UserMacros PropertyGroup, element

<PropertyGroup Label="UserMacros" />

UserMacros zawiera właściwości tworzone jako zmienne, które są używane do dostosowywania procesu kompilacji. Można na przykład zdefiniować makro użytkownika, aby zdefiniować niestandardową ścieżkę wyjściową jako $(CustomOutputPath) i użyć go do zdefiniowania innych zmiennych. Ta grupa nieruchomości mieści takie właściwości. W programie Visual Studio ta grupa nie jest wypełniana w pliku projektu, ponieważ program Visual C++ nie obsługuje makr użytkownika dla konfiguracji. Makra użytkownika są obsługiwane w arkuszach właściwości.

Elementy PropertyGroup dla konfiguracji

<PropertyGroup />

Istnieje wiele wystąpień tej grupy właściwości, po jednym na konfigurację dla wszystkich konfiguracji projektu. Każda grupa właściwości musi mieć dołączony jeden warunek konfiguracji. Jeśli brakuje żadnych konfiguracji, okno dialogowe Właściwości projektu nie będzie działać poprawnie. W przeciwieństwie do grup właściwości wymienionych wcześniej, ta grupa nie ma etykiety. Ta grupa zawiera ustawienia na poziomie konfiguracji projektu. Te ustawienia dotyczą wszystkich plików, które są częścią określonej grupy elementów. Tutaj zainicjowano metadane definicji elementu dostosowywania.

Ta grupa właściwości musi pojawić się później <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> i nie może istnieć żadna inna grupa właściwości bez etykiety przed nią (w przeciwnym razie edytowanie właściwości projektu nie będzie działać poprawnie).

Elementy ItemDefinitionGroup dla konfiguracji

<ItemDefinitionGroup />

Zawiera definicje elementów. Te definicje muszą być zgodne z tymi samymi regułami warunków co elementy konfiguracji PropertyGroup bez etykiet.

Elementy itemGroup

<ItemGroup />

ItemGroup elementy zawierają elementy (pliki źródłowe itd.) w projekcie. Warunki nie są obsługiwane w przypadku elementów projektu (czyli typów elementów, które są traktowane jako elementy projektu według definicji reguł).

Metadane powinny mieć warunki konfiguracji dla każdej konfiguracji, nawet jeśli są takie same. Na przykład:

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

System projektu Visual Studio C++ obecnie nie obsługuje symboli wieloznacznych w elementach projektu.

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

System projektu Visual Studio C++ obecnie nie obsługuje makr w elementach projektu.

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

Odwołania są określone w grupie elementów i mają następujące ograniczenia:

  • Odwołania nie obsługują warunków.

  • Metadane odwołań nie obsługują warunków.

Microsoft.Cpp.targets, element Import

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

Definiuje (bezpośrednio lub za pośrednictwem importu) obiekty docelowe języka C++, takie jak kompilacja, czyszczenie itd.

ExtensionTargets, element ImportGroup

<ImportGroup Label="ExtensionTargets" />

Ta grupa zawiera importy plików docelowych dostosowywania kompilacji.

Konsekwencje nieprawidłowego porządkowania

Środowisko IDE programu Visual Studio zależy od pliku projektu z wcześniej opisanym zamówieniem. Na przykład podczas definiowania wartości właściwości na stronach właściwości środowisko IDE zwykle umieszcza definicję właściwości w grupie właściwości z pustą etykietą. Ta kolejność gwarantuje, że wartości domyślne wprowadzone w arkuszach właściwości systemowych są zastępowane przez wartości zdefiniowane przez użytkownika. Podobnie pliki docelowe są importowane na końcu, ponieważ używają właściwości zdefiniowanych wcześniej, a ponieważ zazwyczaj nie definiują właściwości. Podobnie arkusze właściwości użytkownika są importowane po arkuszach właściwości systemowych (dołączonych przez Microsoft.Cpp.propsprogram ). Ta kolejność gwarantuje, że użytkownik może zastąpić wszystkie ustawienia domyślne wprowadzone przez arkusze właściwości systemowych.

Jeśli plik nie jest zgodna z tym układem .vcxproj , wyniki kompilacji mogą nie być zgodne z oczekiwaniami. Jeśli na przykład pomylisz się z importem arkusza właściwości systemowych po arkuszach właściwości zdefiniowanych przez użytkownika, ustawienia użytkownika są zastępowane przez arkusze właściwości systemowych.

Nawet środowisko czasu projektowania środowiska IDE zależy od pewnego zakresu od poprawnej kolejności elementów. Jeśli na przykład .vcxproj plik nie ma PropertySheets grupy importu, środowisko IDE może nie być w stanie określić, gdzie umieścić nowy arkusz właściwości utworzony przez użytkownika w Menedżerze właściwości. Może to spowodować zastąpienie arkusza użytkownika przez arkusz systemowy. Mimo że heurystyka używana przez środowisko IDE może tolerować drobne niespójności w .vcxproj układzie plików, zdecydowanie zalecamy, aby nie odbiegać od struktury przedstawionej wcześniej w tym artykule.

Jak środowisko IDE używa etykiet elementów

W środowisku IDE po ustawieniu właściwości UseOfAtl na stronie właściwości ogólnej jest zapisywana w grupie właściwości Konfiguracja w pliku projektu. Właściwość TargetName na tej samej stronie właściwości jest zapisywana w grupie właściwości bez etykiety na konfigurację. Program Visual Studio analizuje plik XML strony właściwości, aby uzyskać informacje na temat miejsca zapisu każdej właściwości. Na stronie właściwości Ogólne, zakładając, że masz angielską wersję programu Visual Studio 2019 Enterprise Edition, ten plik to %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. Plik reguły XML strony właściwości definiuje statyczne informacje o regule i wszystkich jej właściwościach. Jedną z takich informacji jest preferowana pozycja właściwości Rule w pliku docelowym (plik, w którym zostanie zapisana jego wartość). Preferowana pozycja jest określana przez atrybut Label w elementach pliku projektu.

Układ arkusza właściwości

Poniższy fragment kodu XML jest minimalnym układem pliku arkusza właściwości (props). Jest on podobny do .vcxproj pliku, a funkcjonalność .props elementów można wywnioskować z wcześniejszej dyskusji.

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

Aby tworzyć własny arkusz właściwości, skopiuj jeden z .props plików w folderze i zmodyfikuj VCTargets go do swoich celów. W przypadku wersji Visual Studio 2019 Enterprise domyślna VCTargets ścieżka to %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Zobacz też

Ustawianie właściwości kompilacji i kompilatora języka C++ w programie Visual Studio
Pliki XML strony właściwości
.vcxproj pliki i symbole wieloznaczne