MSBuild nasıl proje oluşturur

MSBuild gerçekte nasıl çalışır? 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.

Derleme işleminin tamamı, projeyi oluşturan hedeflerin ve görevlerin ilk başlatma, değerlendirme ve yürütme işlemlerinden oluşur. Bu girişlere ek olarak, dış içeri aktarmalar 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, Visual Studio'dan Microsoft.Build.dll'daki MSBuild nesne modeli aracılığıyla veya yürütülebilir dosya (MSBuild.exe veya dotnet build) doğrudan komut satırında veya CI sistemlerinde olduğu gibi bir betikte çağrılarak ç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 -p anahtarını kullanarak -property 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. Çözüm dosyası bir MSBuild XML dosyası değildir, ancak MSBuild, bu dosyayı belirli yapılandırma ve platform ayarları için derlenmesini gereken tüm projeleri bilecek şekilde yorumlar. MSBuild bu XML girişini 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 başvuruda bulunan projeler gerektiğinde bir derleme gerçekleşir; başka bir ifadeyle görevleri ve araçları çalıştırır ve çıkışı 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 (daha önce kullanarak ). SolutionName.sln.targets ve sonrası. SolutionName.sln.targets) yalnızca MSBuild.exe, dotnet buildveya nesne modeli temelli derlemeler için geçerlidir; Visual Studio derlemeleri için geçerli değildir.

Proje SDK’leri

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ış, .NET Core proje SDK'ları ve özellikler başvurusuna 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
• İçeri aktarmaları ve özellikleri değerlendirme
• Öğ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ğerlendirme

Bu aşamada, proje dosyaları ve içeri aktarma zincirinin tamamı dahil olmak üzere giriş XML'sinin tamamı içinde 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ğerlendirme 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 yürütme 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 derleme 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 görevin 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ın en üstündeki bir proje derlenmeye başladığında, ortak hedef dosyalarda tanımlanan standart bir hedef olan hedefin yürütüldüğü ResolveProjectReferences noktaya ulaşır.

ResolveProjectReferences çıkışlarını almak için öğelerin girişleriyle ProjectReference MSBuild görevini çağırır. Öğeler ProjectReference gibi Referenceyerel öğelere dönüştürülür. Geçerli projenin MSBuild yürütme aşaması, yürütme aşaması başvuruda bulunan projeyi işlemeye başlarken duraklatılır (değerlendirme aşaması gerektiğinde önce yapılır). Başvurulan proje yalnızca bağımlı projeyi oluşturmaya başladıktan sonra oluşturulur ve böylece bir proje ağacı oluşturulur.

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ıracak ve derleme sırasını belirlemek için çapraz geçiş yapılan projelerin gerçek bir bağımlılık grafiği olan 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 (-maxCpuCount veya -m anahtar) kullanıyorsanız, MSBuild kullanılabilir CPU çekirdeklerini kullanan MSBuild işlemleri olan düğümler oluşturur. Her proje kullanılabilir bir düğüme gönderilir. Düğüm içinde tek tek proje derlemeleri seri olarak yürütülür.

Görevler, MSBuild'deki özelliğin değerine $(BuildInParallel) göre ayarlanmış bir boole değişkeni BuildInParallelayarlanarak 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 içeri aktarmalar

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 içeri aktarma hiyerarşisi vardır; Bkz . C++ projeleri için MSBuild İçleri.

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 hedef, Build , ve AfterBuildolan gerçek derleme adımlarını BeforeBuildCoreBuildoluşturan tek tek hedefleri belirten özniteliğini içerirDependsOnTargets. 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, hedefteki özniteliğinde Build DependsOnTargets göründüğündenAfterBuild, ancak sonrasında CoreBuildgerçekleştiğinden, operasyon Buildyapılmadan önce çalıştırılır.

Hedef, CoreBuild derleme araçlarına yapılan çağrıları aşağıdaki gibi 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.

Ö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 Compile gerçekten çağıran hedefi içerir.

Kullanıcı tarafından yapılandırılabilir içeri aktarmalar

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ördeki projeler için standart içeri aktarmalar tarafından okunur. Bu genellikle çözümdeki tüm projeleri denetlemek için ayarların çözüm düzeyindedir, ancak dosya sisteminde sürücünün köküne kadar daha yüksek olabilir.

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 içinde 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, Ö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 kendi değişikliklerinizi de 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 çağrısının özelliklerini ayarlamak için komut satırındaki seçeneğini de kullanabilirsiniz /p . Ayarlayabileceğiniz özellikler hakkında bilgi için bkz . Ortak MSBuild proje özellikleri .

İlgili içerik

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