MSBuild projeleri nasıl oluşturur?

MSBuild, Microsoft'un çoğu Visual Studio projesi oluşturmak için kullanılan derleme altyapısıdır. MSBuild, kodunuzu derlemek için derleyicileri ve diğer araçları çağırır, ancak esnek yapılandırma ve özelleştirme seçenekleri ile yalnızca derlenmiş ikili dosyalar oluşturmak için altyapıyı değil, aynı zamanda çok çeşitli diğer çıkış yapıtlarını da içerir. MSBuild çok yapılandırılabilir ve özelleştirilebilir, ancak bu özelleştirilebilirlikten en iyi şekilde yararlanmak için MSBuild'in nasıl çalıştığını anlamak önemlidir. Bu makalede, Visual Studio'dan veya komut satırından veya betikten çağrılsa da MSBuild'in proje dosyalarınızı nasıl işlediğini öğreneceksiniz. MSBuild'in nasıl çalıştığını bilmek sorunları daha iyi tanılamanıza ve derleme işleminizi daha iyi özelleştirmenize yardımcı olabilir. Bu makalede derleme işlemi açıklanır ve büyük ölçüde tüm proje türleri için geçerlidir.

Yapı oluşturma süreci tamamen şunlardan oluşur:

• ilk başlatma - komut satırı seçeneklerinin işlenmesi.
• evaluation - MSBuild proje dosyasının metninin yorumlanması ve işlenmesi.
• execution - projeyi oluşturan hedefleri ve görevleri çalıştırır.

Dış içeri aktarmalar, kaynak dosyalara ve diğer giriş yapıtlarına ek olarak, hem Microsoft.Common.targets gibi standart içeri aktarmalar hem de çözüm veya proje düzeyinde kullanıcı tarafından yapılandırılabilir içeri aktarmalar dahil olmak üzere derleme işleminin ayrıntılarını tanımlar.

Başlangıç

MSBuild, Microsoft.Build.dll'daki MSBuild nesne modeli aracılığıyla veya yürütülebilir dosyayı (MSBuild.exe veya dotnet build) doğrudan komut satırında veya CI sistemlerinde olduğu gibi bir betikte çağırarak Visual Studio'dan çağrılabilir. Her iki durumda da, derleme işlemini etkileyen girişler proje dosyasını (veya Visual Studio'da iç proje nesnesini), muhtemelen bir çözüm dosyasını, ortam değişkenlerini ve komut satırı anahtarlarını veya bunların nesne modeli eşdeğerlerini içerir. Başlatma aşamasında, günlükçüleri yapılandırma gibi MSBuild ayarlarını yapılandırmak için komut satırı seçenekleri veya nesne modeli eşdeğerleri kullanılır. veya -property anahtarını kullanarak -p komut satırında ayarlanan özellikler, proje dosyaları daha sonra okunsa bile proje dosyalarında ayarlanacak tüm değerleri geçersiz kılan genel özellikler olarak ayarlanır.

Sonraki bölümler, çözüm dosyaları veya proje dosyaları gibi giriş dosyaları hakkındadır.

Çözümler ve projeler

MSBuild örnekleri bir projeden veya bir çözümün parçası olarak birçok projeden oluşabilir. Ya da .slnx biçimindeki .sln çözüm dosyaları desteklenir (MSBuild 17.12 ve sonraki sürümlerde). Çözüm dosyası (.sln) bir MSBuild XML dosyası değildir, ancak MSBuild, bu dosyayı belirli yapılandırma ve platform ayarları için yapılandırılması gereken tüm projeleri bilecek şekilde yorumlar. MSBuild bu girişi işlediğinde çözüm derlemesi olarak adlandırılır. Her çözüm derlemesinde bir şeyler çalıştırmanıza olanak sağlayan bazı genişletilebilir noktaları vardır, ancak bu derleme tek tek proje derlemelerinden ayrı bir çalıştırma olduğundan, çözüm derlemesinden hiçbir özellik veya hedef tanım ayarı her proje derlemesi için uygun değildir.

Çözüm derlemesini genişletmeyi çözüm derlemesini özelleştirme konusunda bulabilirsiniz.

Visual Studio derlemeleri ile MSBuild.exe derlemeleri karşılaştırması

Projelerin Visual Studio'da derlemesi ile MSBuild'i doğrudan MSBuild yürütülebilir dosyası aracılığıyla çağırmanız veya bir derleme başlatmak için MSBuild nesne modelini kullanmanız arasında bazı önemli farklar vardır. Visual Studio, Visual Studio derlemeleri için proje derleme sırasını yönetir; yalnızca tek tek proje düzeyinde MSBuild'i çağırır ve çağırdığında, MSBuild'in ne yaptığını önemli ölçüde etkileyen birkaç Boole özelliği (BuildingInsideVisualStudio, BuildProjectReferences) ayarlanır. Her projenin içinde yürütme, MSBuild aracılığıyla çağrıldığında olduğu gibi gerçekleşir, ancak başvurulan projelerde fark ortaya çıkar. MSBuild'de referans verilen projeler gerektiğinde bir derleme gerçekleşir; yani görevleri ve araçları çalıştırır ve çıkış dosyasını oluşturur. Visual Studio derlemesi başvurulan bir proje bulduğunda, MSBuild yalnızca başvurulan projeden beklenen çıkışları döndürür; Visual Studio'nun bu diğer projelerin derlemesini denetlemesine olanak tanır. Visual Studio, derleme sırasını belirler ve MSBuild'e ayrı ayrı çağrı yapar (gerektiğinde), tamamen Visual Studio'nun denetimi altındadır.

MSBuild bir çözüm dosyasıyla çağrıldığında, MSBuild çözüm dosyasını ayrıştırdığında, standart bir XML giriş dosyası oluşturduğunda, değerlendirdiğinde ve proje olarak yürüttüğünde başka bir fark ortaya çıkar. Çözüm derlemesi herhangi bir projeden önce yürütülür. Visual Studio'dan derleme yaparken bunların hiçbiri gerçekleşmez; MSBuild hiçbir zaman çözüm dosyasını görmez. Sonuç olarak, çözüm derleme özelleştirmesi ( before.SolutionName.sln.targets ve after.SolutionName.sln.targets) yalnızca MSBuild.exe, dotnet build veya nesne modeli temelli derlemeler için geçerlidir, Visual Studio derlemeleri için geçerli değildir.

Proje SDK'ları

MSBuild proje dosyaları için SDK özelliği nispeten yenidir. Bu değişiklik öncesinde, proje dosyaları belirli bir proje türü için derleme işlemini tanımlayan .targets ve .props dosyalarını açıkça içeri aktarmıştı.

.NET Core projeleri, .NET SDK'sının kendilerine uygun sürümünü içeri aktarır. Genel bakışa, .NET Core proje SDK'ları'na ve özellikler referansına bakın.

Değerlendirme aşaması

Bu bölümde, ne oluşturulacağını belirleyen bellek içi nesneler üretmek için bu giriş dosyalarının nasıl işlendiği ve ayrıştırıldığı açıklanır.

Değerlendirme aşamasının amacı, giriş XML dosyalarına ve yerel ortama göre bellekte nesne yapıları oluşturmaktır. Değerlendirme aşaması, proje XML dosyaları veya içeri aktarılan XML dosyaları gibi giriş dosyalarını işleyen altı geçişten ve genellikle .props veya .targets dosyaları olarak adlandırılan içeri aktarılan XML dosyalarından oluşur. Bunlar öncelikle özellikleri ayarlayıp ayarlamadıklarına veya derleme hedeflerini tanımlamalarına bağlıdır. Her geçiş, daha sonra projeleri derlemek için yürütme aşamasında kullanılan bellek içi nesnelerin bir bölümünü oluşturur, ancak değerlendirme aşamasında gerçek derleme eylemi gerçekleşmez. Her geçişte, öğeler göründükleri sırayla işlenir.

Değerlendirme aşamasındaki geçişler aşağıdaki gibidir:

• Ortam değişkenlerini değerlendirme
• İthalatları ve özellikleri değerlendirin
• Öğe tanımlarını değerlendirme
• Öğeleri değerlendirme
• UsingTask öğelerini değerlendirme
• Hedefleri değerlendirme

İçeri aktarmalar ve özellikler, içeri aktarmalar yerinde genişletilmiş gibi aynı görünüm sırasında değerlendirilir. Bu nedenle, daha önce içeri aktarılan dosyalardaki özellik ayarları daha sonra içeri aktarılan dosyalar içinde kullanılabilir.

Bu geçişlerin sırasının önemli etkileri vardır ve proje dosyasını özelleştirirken bilinmesi önemlidir. Bkz. Özellik ve öğe değerlendirme sırası.

Ortam değişkenlerini değerlendirme

Bu aşamada ortam değişkenleri eşdeğer özellikleri ayarlamak için kullanılır. Örneğin, PATH ortam değişkeni özelliği $(PATH)olarak kullanılabilir hale getirilir. Komut satırından veya betikten çalıştırıldığında, komut ortamı normal olarak kullanılır ve Visual Studio'dan çalıştırıldığında, Visual Studio başlatıldığında ortam etkin olur.

İçeri aktarmaları ve özellikleri değerlendir

Bu aşamada, proje dosyaları ve ithalat zincirinin tamamı dahil olmak üzere giriş XML'sinin tamamı okunur. MSBuild, projenin XML'sini ve içeri aktarılan tüm dosyaları temsil eden bir bellek içi XML yapısı oluşturur. Şu anda hedeflerde olmayan özellikler değerlendirilir ve ayarlanır.

MSBuild'in tüm XML giriş dosyalarını işleminin başında okumasının bir sonucu olarak, derleme işlemi sırasında bu girişlerde yapılan değişiklikler geçerli derlemeyi etkilemez.

Herhangi bir hedefin dışındaki özellikler, hedeflerdeki özelliklerden farklı şekilde işlenir. Bu aşamada, yalnızca herhangi bir hedefin dışında tanımlanan özellikler değerlendirilir.

Özellikler, özellikler geçişi sırasında işlendiği için, girişin herhangi bir noktasındaki bir özellik girişte daha önce görünen özellik değerlerine erişebilir, ancak daha sonra görünen özelliklere erişemez.

Öğeler değerlendirilmeden önce özellikler işlendiği için, özelliklerin herhangi bir bölümü geçirildiğinde herhangi bir öğenin değerine erişemezsiniz.

Öğe tanımlarını değerlendirme

Bu aşamada , öğe tanımları yorumlanır ve bu tanımların bellek içi gösterimi oluşturulur.

Öğeleri değerlendirme

Hedefin içinde tanımlanan öğeler, herhangi bir hedefin dışındaki öğelerden farklı şekilde işlenir. Bu aşamada, herhangi bir hedefin dışındaki öğeler ve ilişkili meta verileri işlenir. Öğe tanımlarına göre ayarlanan meta veriler, öğelerde ayarlanan meta veriler tarafından geçersiz kılınabilir. Öğeler göründükleri sırayla işlendiği için, daha önce tanımlanmış olan öğelere başvurabilirsiniz, ancak daha sonra görünen öğelere başvuramazsınız. Öğe geçişi, özellikler geçtikten sonra olduğundan, özellik tanımının daha sonra görünüp görünmediğine bakılmaksızın, öğeler herhangi bir hedefin dışında tanımlanırsa herhangi bir özelliğe erişebilir.

Öğeleri değerlendirin UsingTask

Bu aşamada UsingTask öğeleri okunur ve görevler yürütme aşamasında daha sonra kullanılmak üzere bildirilir.

Hedefleri değerlendirme

Bu aşamada, tüm hedef nesne yapıları yürütme hazırlığında bellekte oluşturulur. Gerçek icra gerçekleşmez.

Yürütme aşaması

Yürütme aşamasında hedefler sıralanır ve çalıştırılır ve tüm görevler yürütülür. Ancak ilk olarak, hedefler içinde tanımlanan özellikler ve öğeler, göründükleri sırayla tek bir aşamada birlikte değerlendirilir. İşleme sırası, hedefte olmayan özelliklerin ve öğelerin işlenmesinden önemli ölçüde farklıdır: önce tüm özellikler, sonra da tüm öğeler ayrı geçişlerde. Bir hedef içindeki özelliklerde ve öğelerde yapılan değişiklikler, değiştirildikleri hedef sonrasında gözlemlenebilir.

Hedef build sırası

Tek bir projede hedefler seri olarak yürütülür. Temel sorun, bağımlılıkların hedefleri doğru sırada oluşturmak için kullanılması için her şeyin hangi sırada derleneceğinin nasıl belirleneceğidir.

Hedef derleme sırası, her hedefte BeforeTargets, DependsOnTargetsve AfterTargets özniteliklerinin kullanımıyla belirlenir. Önceki hedef bu özniteliklerde başvuruda bulunan bir özelliği değiştirirse, önceki hedefin yürütülmesi sırasında sonraki hedeflerin sırası etkilenebilir.

Sıralama kuralları , Hedef derleme sırasını belirleme bölümünde açıklanmıştır. İşlem, derlenecek hedefleri içeren bir yığın yapısı tarafından belirlenir. Bu yığının en üstündeki hedef yürütmeye başlar ve başka bir şeye bağlıysa, bu hedefler yığının en üstüne gönderilir ve yürütülmeye başlar. Herhangi bir bağımlılığı olmayan bir hedef olduğunda tamamlanmak üzere yürütülür ve üst hedef devam eder.

Proje Başvuruları

MSBuild'in alabildiği iki kod yolu vardır: burada açıklanan normal yol ve sonraki bölümde açıklanan grafik seçeneği.

Tek tek projeler, öğeler aracılığıyla ProjectReference diğer projelere bağımlılıklarını belirtir. Yığın üstündeki bir proje derlenmeye başladığında, ortak hedef dosyalarında tanımlanan standart bir hedef olan hedef çalıştırıldığı ResolveProjectReferences noktaya ulaşır.

ResolveProjectReferences öğelerin girişlerini kullanarak ProjectReference MSBuild görevini çağırarak çıkışları alır. ProjectReference öğeler, Reference gibi yerel öğelere dönüştürülür. Geçerli projenin MSBuild yürütme aşaması, başvurulan projeyi işlemeye başlama aşamasında duraklatılır (gerekirse değerlendirme aşaması önce tamamlanır). Bağımlı projeyi oluşturmaya başladıktan sonra referans alınan proje oluşturulur ve bu durum, birbirine bağlı projelerin oluşturulduğu bir yapı oluşmasına neden olur.

Visual Studio, çözüm (.sln) dosyalarında proje bağımlılıkları oluşturmaya olanak tanır. Bağımlılıklar çözüm dosyasında belirtilir ve yalnızca bir çözüm oluşturulurken veya Visual Studio içinde oluşturulurken dikkate edilir. Tek bir proje oluşturursanız, bu bağımlılık türü yoksayılır. Çözüm başvuruları MSBuild tarafından öğelere ProjectReference dönüştürülür ve bundan sonra aynı şekilde ele alınır.

Graf seçeneği

Grafik derleme anahtarını (-graphBuild veya -graph) ProjectReference belirtirseniz, MSBuild tarafından kullanılan birinci sınıf bir kavram haline gelir. MSBuild tüm projeleri ayrıştırarak projelerin gerçek bir bağımlılık grafiği olan ve derleme sırasını belirlemek için geçilen derleme sırası grafiğini oluşturur. Tek tek projelerdeki hedeflerde olduğu gibi MSBuild de başvuruda bulunan projelerin bağımlı oldukları projelerden sonra derlenmesini sağlar.

Paralel yürütme

Çok işlemcili destek seçeneği (-maxCpuCount veya -m) kullanıyorsanız, MSBuild, mevcut CPU çekirdeklerini kullanan MSBuild süreçleri olan düğümler oluşturur. Her proje kullanılabilir bir düğüme gönderilir. Düğüm içinde bireysel proje derlemeleri ardışık olarak yürütülür.

Görevler, MSBuild'deki özelliğin değerine BuildInParallel göre ayarlanmış bir boole değişkeni $(BuildInParallel)ayarlanarak paralel yürütme için etkinleştirilebilir. Paralel yürütme için etkinleştirilmiş görevler için, bir iş zamanlayıcı düğümleri yönetir ve işi düğümlere atar.

Bkz . MSBuild ile paralel olarak birden çok proje oluşturma

Standart ithalatlar

Microsoft.Common.props ve Microsoft.Common.targets'ın her ikisi de .NET proje dosyaları tarafından içeri aktarılır (SDK stilindeki projelerde açıkça veya örtük olarak) ve Visual Studio yüklemesindeki MSBuild\Current\bin klasöründe bulunur. C++ projelerinin kendi import hiyerarşisi vardır; bkz C++ projeleri için MSBuild İç Yapısı.

Microsoft.Common.props dosyası, geçersiz kılabileceğiniz varsayılan ayarları ayarlar. Proje dosyasının başında (açıkça veya örtük olarak) içeri aktarılır. Bu şekilde, projenizin ayarları varsayılan değerlerden sonra görünür, böylece bunları geçersiz kılar.

Microsoft.Common.targets dosyası ve içeri aktardığınız hedef dosyalar .NET projeleri için standart derleme işlemini tanımlar. Ayrıca derlemeyi özelleştirmek için kullanabileceğiniz uzantı noktaları sağlar.

Uygulamada Microsoft.Common.targets , Microsoft.Common.CurrentVersion.targets dosyasını içeri aktaran ince bir sarmalayıcıdır. Bu dosya standart özelliklerin ayarlarını içerir ve derleme işlemini tanımlayan gerçek hedefleri tanımlar. Hedef Build burada tanımlanır, ancak aslında kendisi boş olur. Ancak Build hedefi, gerçek derleme adımlarını oluşturan BeforeBuild, CoreBuild, ve AfterBuild olan tek tek hedefleri belirleyen DependsOnTargets özniteliğini içerir. Hedef Build aşağıdaki gibi tanımlanır:

  <PropertyGroup>
    <BuildDependsOn>
      BeforeBuild;
      CoreBuild;
      AfterBuild
    </BuildDependsOn>
  </PropertyGroup>

  <Target
      Name="Build"
      Condition=" '$(_InvalidConfigurationWarning)' != 'true' "
      DependsOnTargets="$(BuildDependsOn)"
      Returns="@(TargetPathWithTargetPlatformMoniker)" />

BeforeBuild ve AfterBuild uzantı noktalarıdır. Microsoft.Common.CurrentVersion.targets dosyasında boşlardır, ancak projeler ana derleme işleminden önce veya sonra gerçekleştirilmesi gereken görevlerle kendi BeforeBuild ve AfterBuild hedeflerini sağlayabilir. AfterBuild, no-op hedefinden önce çalıştırılır çünkü AfterBuild, Build hedefindeki DependsOnTargets özniteliğinde görünür, ancak CoreBuild sonrasında gerçekleşir.

Hedef CoreBuild, aşağıdaki gibi derleme araçlarına yapılan çağrıları içerir:

  <PropertyGroup>
    <CoreBuildDependsOn>
      BuildOnlySettings;
      PrepareForBuild;
      PreBuildEvent;
      ResolveReferences;
      PrepareResources;
      ResolveKeySource;
      Compile;
      ExportWindowsMDFile;
      UnmanagedUnregistration;
      GenerateSerializationAssemblies;
      CreateSatelliteAssemblies;
      GenerateManifests;
      GetTargetPath;
      PrepareForRun;
      UnmanagedRegistration;
      IncrementalClean;
      PostBuildEvent
    </CoreBuildDependsOn>
  </PropertyGroup>
  <Target
      Name="CoreBuild"
      DependsOnTargets="$(CoreBuildDependsOn)">

    <OnError ExecuteTargets="_TimeStampAfterCompile;PostBuildEvent" Condition="'$(RunPostBuildEvent)'=='Always' or '$(RunPostBuildEvent)'=='OnOutputUpdated'"/>
    <OnError ExecuteTargets="_CleanRecordFileWrites"/>

  </Target>

Aşağıdaki tabloda bu hedefler açıklanmaktadır; bazı hedefler yalnızca belirli proje türleri için geçerlidir.

Target	Description
BuildOnlySettings	Yalnızca gerçek derlemeler için ayarlar, Visual Studio'nun proje yükleme sırasında MSBuild'i çağırdığı durumlar için geçerli değildir.
PrepareForBuild	Derleme önkoşullarını hazırla
PreBuildEvent	Projelerin inşa öncesi yürütülecek görevleri tanımlaması için bir uzantı noktasıdır.
ResolveProjectReferences	Proje bağımlılıklarını analiz et ve referans verilen projeleri oluştur
ResolveAssemblyReferences (Montaj Referanslarını Çöz)	Başvurulan derlemeleri bul.
ResolveReferences	ResolveProjectReferences ve ResolveAssemblyReferences'den oluşur ve tüm bağımlılıkları bulur.
Kaynakları Hazırla	Kaynak dosyalarını işleme
ResolveKeySource	Derlemeyi imzalamak için kullanılan tanımlayıcı ad anahtarını ve ClickOnce bildirimlerini imzalamak için kullanılan sertifikayı çözün.
Derlemek	Derleyiciyi çağırır
WindowsMDDosyasınıDışaAktar	Derleyici tarafından oluşturulan WinMDModule dosyalarından bir WinMD dosyası oluşturun.
UnmanagedUnregistration	Önceki bir derlemeden COM Interop kayıt defteri girdilerini temizleyin veya kaldırın.
Serileştirme Bileşenlerini Üret	sgen.exekullanarak bir XML serileştirme derlemesi oluşturun.
Uydu Bileşenleri Oluştur	Kaynaklardaki her benzersiz kültür için bir uydu derlemesi oluşturun.
Bildirim Oluştur	ClickOnce uygulama ve dağıtım bildirimleri veya yerel bildirim oluşturur.
GetTargetPath	Bu proje için derlenmiş ürünü (yürütülebilir dosya veya bütünleştirilmiş paket) meta veriyle birlikte içeren bir öğeyi döndür.
PrepareForRun	Derleme çıkışlarını değiştirdiyseniz son dizine kopyalayın.
Yönetilmeyen Kayıt	COM Birlikte Çalışma için kayıt defteri girdilerini ayarla
IncrementalClean	Önceki bir derlemede üretilen ancak geçerli derlemede üretilmeyen dosyaları kaldırın. Artımlı derlemelerde Clean'in çalışmasını sağlamak için bu gereklidir.
PostBuildEvent	Derlemeden sonra çalıştırılacak görevleri tanımlamak için projelerin uzantı noktası

Önceki tablodaki hedeflerin çoğu dile özgü içeri aktarmalarda bulunur, örneğin Microsoft.CSharp.targets. Bu dosya, C# .NET projelerine özgü standart derleme işlemi adımlarını tanımlar. Örneğin, C# derleyicisini çağıran Compile hedefini gerçekten içerir.

Kullanıcı tarafından ayar yapılabilir aktarımlar

Standart içeri aktarmalara ek olarak, derleme işlemini özelleştirmek için ekleyebileceğiniz birkaç içeri aktarma vardır.

• Directory.Build.props
• Directory.Build.targets

Bu dosyalar, altındaki herhangi bir alt klasörde bulunan projeler için standart ithalat süreci tarafından içeri alınır. Bu genellikle tüm projeleri denetlemek için çözümün yapı düzeyinde ayarlardadır, ancak dosya sisteminde sürücünün ana dizinine kadar daha üstte yer alabilir.

Directory.Build.props dosyası Microsoft.Common.props tarafından içeri aktarılır, bu nedenle burada tanımlanan özellikler proje dosyasında kullanılabilir. Değerleri proje başına temelinde özelleştirmek için proje dosyasında yeniden tanımlanabilirler. Directory.Build.targets dosyası proje dosyasından sonra okunur. Genellikle hedefler içerir, ancak burada tek tek projelerin yeniden tanımlamasını istemediğiniz özellikleri de tanımlayabilirsiniz.

Proje dosyasındaki özelleştirmeler

Çözüm Gezgini'nde, Özellikler penceresinde veya Proje Özellikleri'nde değişiklik yaparken Visual Studio proje dosyalarınızı güncelleştirir, ancak proje dosyasını doğrudan düzenleyerek de kendi değişikliklerinizi yapabilirsiniz.

Birçok derleme davranışı, proje ve çözüm klasörlerinin tamamı için özellikleri genel olarak ayarlamak üzere bir Directory.Build.props dosyası oluşturarak, msbuild özelliklerini bir projeye yerel ayarlar için proje dosyasında veya önceki bölümde belirtildiği gibi ayarlayarak yapılandırılabilir. Komut satırındaki geçici derlemeler veya betikler için, MSBuild'in belirli bir çalıştırmasında özellikleri ayarlamak için /p seçeneğini komut satırında da kullanabilirsiniz. Ayarlayabileceğiniz özellikler hakkında bilgi için bkz. Ortak MSBuild proje özellikleri .

İlgili içerik

• Derlemenizi özelleştirin
• Visual Studio derleme işlemini genişletme.
• MSBuild