.vcxproj ve .props dosya yapısı

MSBuild, Visual Studio'daki varsayılan proje sistemidir; Visual C++ içinde Dosya>Yeni Proje'yi seçtiğinizde, ayarları uzantısına .vcxprojsahip bir XML proje dosyasında depolanan bir MSBuild projesi oluşturursunuz. Proje dosyası, ayarların depolanabileceği dosyaları ve .targets dosyaları da içeri aktarabilir.props.

Proje özelliklerinizi IDE'de tutmak istiyorsanız, yalnızca IDE'de projelerinizi oluşturup değiştirmenizi ve dosyalarda el ile yapılan düzenlemelerden kaçınmanızı .vcxproj öneririz. Çoğu durumda, proje dosyasını el ile düzenlemeniz gerekmez. El ile yapılan düzenlemeler, Visual Studio özellik sayfalarında proje ayarlarını değiştirmek için gereken proje bağlantılarını kesebilir ve hata ayıklaması ve onarımı zor derleme hatalarına neden olabilir. Özellik sayfalarını kullanma hakkında daha fazla bilgi için bkz . Visual Studio'da C++ derleyicisi ve derleme özelliklerini ayarlama.

Büyük ölçekte, IDE'de birçok ayrı projenin yönetilmesi zahmetli ve hataya eğilimli hale gelir. Onlarca veya yüzlerce projede tutarlılığı korumak veya standartlaştırmayı zorunlu tutmak zordur. Bu gibi durumlarda, birçok projede ortak özellikler için özelleştirilmiş .props veya .targets dosyaları kullanmak üzere proje dosyalarınızı düzenlemeniz faydalı olabilir. IDE'de mümkün olmayan özelleştirmeler gerektiğinde de bu dosyaları kullanabilirsiniz. Özelleştirme eklemek için kullanışlı yerler, tüm MSBuild tabanlı projelerde otomatik olarak içeri aktarılan ve Directory.Build.targets dosyalarıdırDirectory.Build.props.

Bazı durumlarda, özelleştirilmiş .props veya .targets yalnızca dosyalar proje yönetimi gereksinimleriniz için yeterli olmayabilir. Yine de proje dosyalarını veya özellik sayfalarını el ile değiştirmeniz .vcxproj gerekebilir. El ile düzenleme, MSBuild'in iyi anlaşılmasını gerektirir ve bu makaledeki yönergeleri izlemelidir. IDE'nin dosyaları otomatik olarak yükleyebilmesi ve güncelleştirebilmesi .vcxproj için, bu dosyaların diğer MSBuild proje dosyaları için geçerli olmayan çeşitli kısıtlamaları vardır. Hatalar IDE'nin kilitlenmesine veya beklenmeyen şekillerde davranmasına neden olabilir.

El ile düzenleme senaryoları için, bu makale ve ilgili dosyaların yapısı .vcxproj hakkında temel bilgiler içerir.

Dikkat edilmesi gereken önemli hususlar

Bir .vcxproj dosyayı el ile düzenlemeyi seçerseniz şu olgulara dikkat edin:

• Dosyanın yapısı, bu makalede açıklanan, belirlenmiş bir formu izlemelidir.

• Visual Studio C++ proje sistemi şu anda joker karakterleri veya listeleri doğrudan proje öğelerinde desteklememektedir. Örneğin, bu formlar desteklenmez:

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

  Projelerdeki joker karakter desteği ve olası geçici çözümler hakkında daha fazla bilgi için bkz .vcxproj . dosyalar ve joker karakterler.

• Visual Studio C++ proje sistemi şu anda proje öğesi yollarındaki makroları desteklememektedir. Örneğin, bu form desteklenmez:

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

  "Desteklenmiyor" ifadesi, makroların IDE'deki tüm işlemler için çalışmasının garanti edilmediği anlamına gelir. Farklı yapılandırmalarda değerlerini değiştirmeyen makrolar çalışmalıdır, ancak bir öğe farklı bir filtreye veya projeye taşındığında korunmayabilir. Farklı yapılandırmalar için değerlerini değiştiren makrolar sorunlara neden olur. IDE, farklı proje yapılandırmaları için proje öğesi yollarının farklı olmasını beklemez.

• Proje Özellikleri iletişim kutusunda düzenlerken proje özelliklerini doğru şekilde eklemek, kaldırmak veya değiştirmek için, dosya her proje yapılandırması için ayrı gruplar içermelidir. Koşullar şu biçimde olmalıdır:

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

• Her özellik, özellik kuralı dosyasında belirtildiği gibi doğru etiketiyle grupta belirtilmelidir. Daha fazla bilgi için bkz . Özellik sayfası xml kuralı dosyaları.

.vcxproj dosya öğeleri

Herhangi bir metin veya XML düzenleyicisi kullanarak dosyanın .vcxproj içeriğini inceleyebilirsiniz. Çözüm Gezgini'da projeye sağ tıklayıp Projeyi kaldır'ı ve ardından Foo.vcxproj'yu Düzenle'yi seçerek Visual Studio'da görüntüleyebilirsiniz.

Dikkat edilmesi gereken ilk şey, en üst düzey öğelerin belirli bir sırada göründüğüdür. Örnek:

• Özellik gruplarının ve öğe tanım gruplarının çoğu, Microsoft.Cpp.Default.props için içeri aktarma işleminden sonra gerçekleşir.

• Tüm hedefler dosyanın sonunda içeri aktarılır.

• Her birinin benzersiz etiketi olan birden çok özellik grubu vardır ve bunlar belirli bir sırada gerçekleşir.

MSBuild sıralı değerlendirme modeline dayalı olduğundan, proje dosyasındaki öğelerin sırası çok önemlidir. Tüm içeri aktarılanlar .props ve .targets dosyalar da dahil olmak üzere proje dosyanız bir özelliğin birden çok tanımından oluşuyorsa, son tanım öncekileri geçersiz kılar. Aşağıdaki örnekte, MSBUild altyapısı değerlendirme sırasında en son karşılaştığından derleme sırasında "xyz" değeri ayarlanır.

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

Aşağıdaki kod parçacığında en az .vcxproj dosya gösterilmektedir. Visual Studio tarafından oluşturulan tüm .vcxproj dosyalar bu üst düzey MSBuild öğelerini içerir. Ve bu sırada görünürler, ancak bu tür üst düzey öğelerin birden çok kopyasını içerebilirler. Tüm Label öznitelikler, yalnızca Visual Studio tarafından düzenleme için işaretpostları olarak kullanılan rastgele etiketlerdir; başka bir işlevi yoktur.

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

Aşağıdaki bölümlerde bu öğelerin her birinin amacı ve neden bu şekilde sıralandığı açıklanmaktadır:

Project öğesi

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

Project kök düğümdür. Kullanılacak MSBuild sürümünü ve ayrıca bu dosya MSBuild.exe dosyasına geçirildiğinde yürütülecek varsayılan hedefi belirtir.

ProjectConfigurations ItemGroup öğesi

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations proje yapılandırma açıklamasını içerir. Örnekler Hata Ayıklama|Win32, Sürüm|Win32, Hata Ayıklama|ARM ve benzeri. Birçok proje ayarı belirli bir yapılandırmaya özeldir. Örneğin, büyük olasılıkla bir yayın derlemesi için iyileştirme özellikleri ayarlamak isteyeceksiniz ancak hata ayıklama derlemesi ayarlamak istemeyeceksiniz.

Öğe ProjectConfigurations grubu derleme zamanında kullanılmaz. Visual Studio IDE' nin projeyi yüklemesi gerekir. Bu öğe grubu bir .props dosyaya taşınabilir ve dosyaya .vcxproj aktarılabilir. Ancak bu durumda yapılandırmaları eklemeniz veya kaldırmanız gerekiyorsa dosyayı el ile düzenlemeniz .props gerekir; IDE'yi kullanamazsınız.

ProjectConfiguration öğeleri

Aşağıdaki kod parçacığında bir proje yapılandırması gösterilmektedir. Bu örnekte yapılandırma adı 'Debug|x64'dür. Proje yapılandırma adı biçiminde $(Configuration)|$(Platform)olmalıdır. Bir ProjectConfiguration düğümün iki özelliği olabilir: Configuration ve Platform. Bu özellikler, yapılandırma etkin olduğunda burada belirtilen değerlerle otomatik olarak ayarlanır.

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

IDE, tüm ProjectConfiguration öğelerde kullanılan ve Platform değerlerinin Configuration herhangi bir bileşimi için bir proje yapılandırmasını bulmayı bekler. Bu durum genellikle bir projenin bu gereksinimi karşılamaya yönelik anlamsız proje yapılandırmalarına sahip olabileceği anlamına gelir. Örneğin, bir proje şu yapılandırmalara sahipse:

• Hata Ayıklama|Win32

• Perakende|Win32

• Özel 32 bit İyileştirme|Win32

x64 için "Özel 32 bit İyileştirme" anlamsız olsa da bu yapılandırmalara sahip olması gerekir:

• Hata Ayıklama|x64

• Perakende|x64

• Özel 32 bit İyileştirme|x64

Çözüm Yapılandırma Yöneticisi'nde herhangi bir yapılandırma için derleme ve dağıtma komutlarını devre dışı bırakabilirsiniz.

Globals PropertyGroup öğesi

<PropertyGroup Label="Globals" />

Globals, RootNamespaceve ApplicationType veya ApplicationTypeRevisiongibi ProjectGuidproje düzeyi ayarlarını içerir. Son ikisi genellikle hedef işletim sistemini tanımlar. Şu anda başvurular ve proje öğelerinin koşulları olmadığından, bir proje yalnızca tek bir işletim sistemini hedefleyebilir. Bu özellikler genellikle proje dosyasının başka bir yerinde geçersiz kılınmazlar. Bu grup yapılandırmaya bağımlı değildir ve genellikle proje dosyasında yalnızca bir Globals grup vardır.

Microsoft.Cpp.default.props İçeri Aktarma öğesi

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

Microsoft.Cpp.default.props özellik sayfası Visual Studio ile birlikte gelir ve değiştirilemez. Projenin varsayılan ayarlarını içerir. Varsayılan değerler ApplicationType'a bağlı olarak değişebilir.

Configuration PropertyGroup öğeleri

<PropertyGroup Label="Configuration" />

Özellik Configuration grubu ekli bir yapılandırma koşuluna (örneğin Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") sahiptir ve yapılandırma başına bir tane olmak üzere birden çok kopya halinde gelir. Bu özellik grubu, belirli bir yapılandırma için ayarlanan özellikleri barındırıyor. Yapılandırma özellikleri PlatformToolset'i içerir ve sistem özellik sayfalarının Microsoft.Cpp.props'a eklenmesini de denetler. Örneğin, özelliğini <CharacterSet>Unicode</CharacterSet>tanımlarsanız, sistem özellik sayfası microsoft. Cpp.unicodesupport.props eklenecektir. Microsoft.Cpp.props dosyasını incelerseniz şu satırı görürsünüz: <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Microsoft.Cpp.props İçeri Aktarma öğesi

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

Microsoft.Cpp.props özellik sayfası (doğrudan veya içeri aktarmalar aracılığıyla) birçok ara öğeye özgü özellik için varsayılan değerleri tanımlar. Örnek olarak derleyicinin İyileştirme ve Uyarı Düzeyi özellikleri, MIDL aracının TypeLibraryName özelliği vb. verilebilir. Ayrıca, özellik grubunda tanımlandığı yapılandırma özelliklerine göre çeşitli sistem özellik sayfalarını da hemen içeri aktarır.

Extension Ayarlar ImportGroup öğesi

<ImportGroup Label="ExtensionSettings" />

Grup, ExtensionSettings Derleme Özelleştirmeleri'nin parçası olan özellik sayfalarının içeri aktarmalarını içerir. Derleme Özelleştirmesi en fazla üç dosyayla tanımlanır: bir .targets dosya, bir .props dosya ve bir .xml dosya. Bu içeri aktarma grubu, dosyanın içeri aktarmalarını .props içerir.

PropertySheets ImportGroup öğeleri

<ImportGroup Label="PropertySheets" />

Grup, PropertySheets kullanıcı özellik sayfaları için içeri aktarmaları içerir. Bu içeri aktarmalar, Visual Studio'daki Özellik Yöneticisi görünümü aracılığıyla eklediğiniz özellik sayfalarıdır. Bu içeri aktarmaların listelenme sırası önemlidir ve Özellik Yöneticisi'ne yansıtılır. Proje dosyası normalde her proje yapılandırması için bir tane olan bu tür içeri aktarma grubunun birden çok örneğini içerir.

UserMacros PropertyGroup öğesi

<PropertyGroup Label="UserMacros" />

UserMacros , derleme işleminizi özelleştirmek için kullanılan değişkenler olarak oluşturduğunuz özellikleri içerir. Örneğin, özel çıkış yolunuzu $(CustomOutputPath) olarak tanımlamak için bir kullanıcı makro tanımlayabilir ve bunu diğer değişkenleri tanımlamak için kullanabilirsiniz. Bu özellik grubu bu tür özellikleri barındırmaktadır. Visual C++ yapılandırmalar için kullanıcı makrolarını desteklemediğinden Visual Studio'da bu grup proje dosyasında doldurulmuyor. Kullanıcı makroları özellik sayfalarında desteklenir.

Yapılandırma başına PropertyGroup öğeleri

<PropertyGroup />

Bu özellik grubunun, tüm proje yapılandırmaları için yapılandırma başına bir tane olan birden çok örneği vardır. Her özellik grubunun bir yapılandırma koşulu eklenmelidir. Herhangi bir yapılandırma eksikse, Proje Özellikleri iletişim kutusu düzgün çalışmaz. Daha önce listelenen özellik gruplarının aksine, bunun etiketi yoktur. Bu grup, proje yapılandırma düzeyi ayarlarını içerir. Bu ayarlar, belirtilen öğe grubunun parçası olan tüm dosyalar için geçerlidir. Derleme özelleştirme öğesi tanımı meta verileri burada başlatılır.

Bu PropertyGroup'un daha sonra <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> gelmesi ve bundan önce Etiketi olmayan başka bir PropertyGroup olmaması gerekir (aksi takdirde Proje Özellikleri düzenleme düzgün çalışmaz).

Yapılandırma başına ItemDefinitionGroup öğeleri

<ItemDefinitionGroup />

Öğe tanımlarını içerir. Bu tanımların, yapılandırma PropertyGroup başına etiketsiz öğelerle aynı koşul kurallarına uyması gerekir.

ItemGroup öğeleri

<ItemGroup />

ItemGroup öğeleri projedeki öğeleri (kaynak dosyaları vb.) içerir. Koşullar Project öğeleri (yani, kural tanımlarına göre proje öğeleri olarak ele alınan öğe türleri) için desteklenmez.

Meta verilerin tümü aynı olsa bile her yapılandırma için yapılandırma koşulları olmalıdır. Örnek:

<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++ proje sistemi şu anda proje öğelerinde joker karakterleri desteklememektedir.

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

Visual Studio C++ proje sistemi şu anda proje öğelerindeki makroları desteklememektedir.

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

Başvurular bir ItemGroup içinde belirtilir ve şu sınırlamalara sahiptir:

• Başvurular koşulları desteklemez.

• Başvuru meta verileri koşulları desteklemez.

Microsoft.Cpp.targets import öğesi

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

Derleme, temizleme vb. gibi C++ hedeflerini (doğrudan veya içeri aktarmalar aracılığıyla) tanımlar.

ExtensionTargets ImportGroup öğesi

<ImportGroup Label="ExtensionTargets" />

Bu grup, Derleme Özelleştirmesi hedef dosyaları için içeri aktarmalar içerir.

Yanlış sıralamanın sonuçları

Visual Studio IDE, proje dosyasının daha önce açıklanan sıralamaya sahip olmasına bağlıdır. Örneğin, özellik sayfalarında bir özellik değeri tanımladığınızda, IDE genellikle özellik tanımını boş etiketli özellik grubuna yerleştirir. Bu sıralama, sistem özellik sayfalarına getirilen varsayılan değerlerin kullanıcı tanımlı değerler tarafından geçersiz kılınmasını sağlar. Benzer şekilde, hedef dosyalar daha önce tanımlanan özellikleri kullandıklarından ve genellikle özellikleri kendileri tanımlamadığından sonunda içeri aktarılır. Benzer şekilde, kullanıcı özellik sayfaları sistem özellik sayfalarından sonra içeri aktarılır (tarafından Microsoft.Cpp.propsdahil edilir). Bu sıra, kullanıcının sistem özellik sayfaları tarafından getirilen tüm varsayılanları geçersiz kılabilmesini sağlar.

Bir .vcxproj dosya bu düzeni izlemiyorsa, derleme sonuçları beklediğiniz gibi olmayabilir. Örneğin, kullanıcı tarafından tanımlanan özellik sayfalarından sonra yanlışlıkla bir sistem özellik sayfasını içeri aktarırsanız, kullanıcı ayarları sistem özellik sayfaları tarafından geçersiz kılınabilir.

IDE tasarım süresi deneyimi bile öğelerin doğru sıralanmasında bir ölçüde bağlıdır. Örneğin, dosyanızda .vcxprojPropertySheets içeri aktarma grubu yoksa, IDE kullanıcının Özellik Yöneticisi'nde oluşturduğu yeni özellik sayfasının nereye yerleştirileceğini belirleyemeyebilir. Bir kullanıcı sayfasının sistem sayfası tarafından geçersiz kılınmasıyla sonuçlanabilir. IDE tarafından kullanılan buluşsal yöntem, dosya düzenindeki küçük tutarsızlıkları tolere etse de .vcxproj , bu makalenin önceki bölümlerinde gösterilen yapıdan sapmamanızı kesinlikle öneririz.

IDE öğe etiketlerini nasıl kullanır?

IDE'de, genel özellik sayfasında UseOfAtl özelliğini ayarladığınızda, proje dosyasındaki Configuration özellik grubuna yazılır. Aynı özellik sayfasındaki TargetName özelliği, yapılandırma başına etiketsiz özellik grubuna yazılır. Visual Studio, her özelliğin nereye yazıldığına ilişkin bilgiler için özellik sayfasının xml dosyasına bakar. Visual Studio 2019 Enterprise Sürümü İngilizce sürümüne sahip olduğunuzu varsayarsak, Genel özellik sayfası için bu dosya olur%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. Özellik sayfası XML kural dosyası, bir Kural ve tüm özellikleri hakkındaki statik bilgileri tanımlar. Bu tür bilgilerden biri, hedef dosyada rule özelliğinin tercih edilen konumudur (değerinin yazılacağı dosya). Tercih edilen konum, proje dosyası öğelerindeki Label özniteliği tarafından belirtilir.

Özellik Sayfası düzeni

Aşağıdaki XML kod parçacığı, özellik sayfası (.props) dosyasının en küçük düzenidir. Bir dosyaya .vcxproj benzer ve öğelerin işlevselliği .props önceki tartışmadan çıkarılabilir.

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

Kendi özellik sayfanızı oluşturmak için klasördeki .propsVCTargets dosyalardan birini kopyalayın ve kendi amaçlarınıza göre değiştirin. Visual Studio 2019 Enterprise sürümü için varsayılan VCTargets yol şeklindedir %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Ayrıca bkz.

Visual Studio’da C++ derleyicisi ve derleme özelliklerini ayarlama
Özellik Sayfası XML Dosyaları
.vcxproj dosyalar ve joker karakterler