MSBuild

  • Makale

Microsoft Build Engine, uygulama oluşturmaya yönelik bir platformdur. MSBuild olarak da bilinen bu altyapı, derleme platformunun yazılımları nasıl işleyeceğini ve derleyeceğini kontrol eden proje dosyası için bir XML şeması sağlar. Visual Studio MSBuild’i kullanır ama MSBuild Visual Studio’ya bağımlı değildir. Proje veya çözüm dosyanızda msbuild.exe veya dotnet derlemesini çağırarak, Visual Studio'nun yüklü olmadığı ortamlarda ürünleri düzenleyebilir ve oluşturabilirsiniz.

Visual Studio yönetilen projeleri yüklemek ve derlemek için MSBuild kullanır. Visual Studio'daki proje dosyaları (.csproj, .vbproj, .vcxproj ve diğerleri), IDE kullanarak bir proje oluşturduğunuzda yürütülen MSBuild XML kodunu içerir. Visual Studio projeleri, tipik geliştirme çalışmalarını yapmak için gerekli tüm ayarları ve derleme işlemlerini içeri aktarır, ancak bunları Visual Studio içinden veya XML düzenleyicisi kullanarak genişletebilir veya değiştirebilirsiniz.

MSBuild'i Visual Studio içermeyen bir Windows sistemine yüklemek için indirmeler sayfasında Visual Studio için Derleme Araçları'na gidin. MSBuild'i bu yöntemle yüklemek size MSBuild.exe sağlar.

.NET Core ve .NET 5 veya üzeri için, MSBuild eşdeğerini almanın başka bir yolu da .NET SDK'sını yüklemektir. .NET derleme komutu dotnet build macOS, Windows veya Linux üzerinde .NET SDK ile kullanılabilir. .NET derleme komutudotnet build, MSBuild.exe .NET Core sürümü üzerinde ince bir sarmalayıcıdır. .NET Core ve .NET 5 ve üzerini hedefleyen projeler oluşturmak için MSBuild kullanan .NET Core komut satırı arabirimini (CLI) kullanabilirsiniz.

Visual Studio 2022'den başlayarak, Visual Studio'da derleme yaptığınızda MSBuild'in 64 bit sürümü kullanılır.

C++ için MSBuild hakkında bilgi için bkz . MSBuild (C++).

Aşağıdaki örneklerde, Visual Studio IDE yerine komut satırından MSBuild çağırarak derlemeleri ne zaman çalıştırabileceğiniz gösterilmektedir.

  • Visual Studio yüklü değil.

  • MSBuild'in 64 bit sürümünü kullanmak istiyorsunuz ve Visual Studio 2019 veya önceki bir sürümünü kullanıyorsunuz. MSBuild'in bu sürümü genellikle gereksizdir, ancak MSBuild'in daha fazla belleğe erişmesine izin verir.

  • Bir derlemeyi birden çok işlemde çalıştırmak istiyorsunuz. Ancak, C++ ve C# projelerinde aynı sonucu elde etmek için IDE'yi kullanabilirsiniz.

  • Derleme sistemini değiştirmek istiyorsunuz. Örneğin, aşağıdaki eylemleri etkinleştirmek isteyebilirsiniz:

    • Dosyaları derleyiciye ulaşmadan önce önişle.

    • Derleme çıkışlarını farklı bir yere kopyalayın.

    • Derleme çıkışlarından sıkıştırılmış dosyalar oluşturun.

    • İşlem sonrası adımlarını uygulayın. Örneğin, bir derlemeyi farklı bir sürümle damgalamak isteyebilirsiniz.

Visual Studio IDE'de kod yazabilirsiniz ancak MSBuild kullanarak derlemeleri çalıştırabilirsiniz. Başka bir alternatif olarak, bir geliştirme bilgisayarında IDE'de kod oluşturabilir, ancak birden çok geliştiricinin işbirliğiyle bir kaynak depodan tümleştirilmiş kod oluşturmak için komut satırından MSBuild'i çalıştırabilirsiniz.

Not

Uygulamanızı otomatik olarak derlemek, test etmek ve dağıtmak için Azure Pipelines'ı kullanabilirsiniz. Derleme sisteminiz, geliştiriciler kodu iade ettiğinde (örneğin, Sürekli Tümleştirme stratejisinin bir parçası olarak) veya bir zamanlamaya (örneğin, gecelik Bir Derleme Doğrulama Testi derlemesi) göre derlemeleri otomatik olarak çalıştırabilir. Azure Pipelines, MSBuild kullanarak kodunuzu derler. Daha fazla bilgi için bkz . Azure Pipelines.

Windows üzerinde MSBuild ile ilgili giriş niteliğindeki bir öğretici için bkz . İzlenecek Yol: MSBuild Kullanma.

Komut isteminde MSBuild kullanma

MSBuild'i komut isteminde çalıştırmak için , uygun komut satırı seçenekleriyle birlikte proje dosyasını MSBuild.exe geçirin. Komut satırı seçenekleri özellikleri ayarlamanıza, belirli hedefleri yürütmenize ve derleme işlemini denetleyan diğer seçenekleri ayarlamanıza olanak tanır. Örneğin, özelliği olarak ayarlanmış DebugMyProj.proj dosyasını oluşturmak için aşağıdaki komut satırı söz dizimini Configuration kullanırsınız.

MSBuild.exe MyProj.proj -property:Configuration=Debug

MSBuild, dosya uzantısına göre davranışını değiştirmez, ancak kural, "proje dosyası" olarak adlandırılan ana MSBuild giriş dosyası için , .vcxprojveya .vbprojgibi .csprojile biten proj uzantıları kullanmaktır.

MSBuild komut satırı seçenekleri hakkında daha fazla bilgi için bkz . Komut satırı başvurusu.

Önemli

Projeyi indirmeden önce kodun güvenilirliğini belirleyin.

.NET Core ve .NET 5 veya üzeri için genellikle MSBuild'i çağırmak için kullanırsınız dotnet build . Bkz. dotnet derlemesi. Visual Studio veya Visual Studio Derleme Araçları değil yalnızca .NET SDK'sını yüklerseniz, msbuild yalnızca aracılığıyla dotnet buildolur.

Komut satırıdotnet build --help, MSBuild.exe seçeneklerinin tümünü değil, öğesine özgü dotnet buildkomut satırı seçeneklerini listeler, ancak MSBuild komut satırı başvurusunda listelenen tüm komut satırı seçeneklerini kullanmaya devam edebilirsiniz. tarafından dotnet build işlenmemiş seçenekler MSBuild'e geçirilir.

Proje dosyası

MSBuild, basit ve genişletilebilir XML tabanlı bir proje dosyası biçimi kullanır. MSBuild proje dosya biçimi, geliştiricilerin oluşturulacak öğeleri ve ayrıca farklı işletim sistemleri ve yapılandırmalar için nasıl oluşturulacaklarını açıklamalarına olanak tanır. Buna ek olarak, proje dosyası biçimi geliştiricilerin ayrı dosyalara hesaba katılabilen yeniden kullanılabilir derleme kuralları yazmasına olanak tanır, böylece derlemeler üründeki farklı projeler arasında tutarlı bir şekilde gerçekleştirilebilir.

Visual Studio derleme sistemi projeye özgü mantığı proje dosyasının içinde depolar ve içeri aktarılan MSBuild XML dosyalarını ve gibi .props.targets uzantılarla kullanarak standart derleme mantığını tanımlar. Dosyalar .props MSBuild özelliklerini, dosyalar ise .targets MSBuild hedeflerini tanımlar. Bu içeri aktarmalar bazen Visual Studio proje dosyasında görünür, ancak .NET Core, .NET 5 ve .NET 6 projeleri gibi daha yeni projelerde, içeri aktarmaları proje dosyasında görmezsiniz; bunun yerine aşağıdakine benzer bir SDK başvurusu görürsünüz:

<Project Sdk="Microsoft.Net.Sdk">

Bunlar SDK stili projeler olarak adlandırılır. .NET SDK gibi bir SDK'ya başvurdığınızda, ve .target dosyalarının .props içeri aktarma işlemleri SDK tarafından örtük olarak belirtilir.

Aşağıdaki bölümlerde MSBuild proje dosya biçiminin bazı temel öğeleri açıklanmaktadır. Temel proje dosyası oluşturma hakkında bir öğretici için bkz . İzlenecek yol: Sıfırdan MSBuild proje dosyası oluşturma.

Properties

Özellikler, derlemeleri yapılandırmak için kullanılabilecek anahtar/değer çiftlerini temsil eder. PropertyGroup öğesinin alt öğesi olarak özelliğin adına sahip bir öğe oluşturularak özellikler bildirilir. Örneğin, aşağıdaki kod değeri Buildolan adlı BuildDir bir özellik oluşturur.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

öğesine bir öznitelik yerleştirerek bir Condition özelliği koşullu olarak tanımlayabilirsiniz. Koşul olarak değerlendirilmediği truesürece koşullu öğelerin içeriği yoksayılır. Aşağıdaki örnekte özelliği Configuration henüz tanımlanmamışsa tanımlanır.

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

Özelliklere proje dosyasının her yanında $(<PropertyName>) söz dizimi kullanılarak başvurulabilir. Örneğin, ve $(Configuration)kullanarak $(BuildDir) önceki örneklerdeki özelliklere başvurabilirsiniz.

Özellikler hakkında daha fazla bilgi için bkz . MSBuild özellikleri.

Items

Öğeler derleme sistemine giriştir ve genellikle dosyaları temsil eder. Öğeler, kullanıcı tanımlı öğe adlarına göre öğe türleri halinde gruplandırılır. Bu öğe türleri, derleme işleminin adımlarını gerçekleştirmek için tek tek öğeleri kullanan görevler için parametre olarak kullanılabilir.

Öğeler, öğe türünün adını bir ItemGroup öğesinin alt öğesi olarak içeren bir öğe oluşturularak proje dosyasında bildirilir. Örneğin, aşağıdaki kod iki dosya içeren adlı Compilebir öğe türü oluşturur.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

@(<ItemType>) söz dizimi kullanılarak proje dosyası genelinde öğe türlerine başvurulabilir. Örneğin, örnekteki öğe türüne kullanılarak @(Compile)başvurulur.

MSBuild'de, öğe ve öznitelik adları büyük/küçük harfe duyarlıdır. Ancak özellik, öğe ve meta veri adları değildir. Aşağıdaki örnek , veya comPilebaşka bir büyük/küçük harf çeşitlemesi öğe türünü Compileoluşturur ve öğe türüne "one.cs; two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Öğeler joker karakterler kullanılarak bildirilebilir ve daha gelişmiş derleme senaryoları için ek meta veriler içerebilir. Öğeler hakkında daha fazla bilgi için bkz . Öğeler.

Görevler

Görevler, MSBuild projelerinin derleme işlemlerini gerçekleştirmek için kullandığı yürütülebilir kod birimleridir. Örneğin, bir görev giriş dosyalarını derlayabilir veya bir dış araç çalıştırabilir. Görevler yeniden kullanılabilir ve farklı projelerdeki farklı geliştiriciler tarafından paylaşılabilir.

Görevin yürütme mantığı yönetilen kodda yazılır ve UsingTask öğesi kullanılarak MSBuild'e eşlenir. Arabirimi uygulayan ITask bir yönetilen tür yazarak kendi görevinizi yazabilirsiniz. Görevleri yazma hakkında daha fazla bilgi için bkz . Görev yazma.

MSBuild, gereksinimlerinize uygun olarak değiştirebileceğiniz yaygın görevler içerir. Örnek olarak dosyaları kopyalayan Copy, dizinler oluşturan MakeDir ve Visual C# kaynak kodu dosyalarını derleyen Csc verilebilir. Kullanım bilgileriyle birlikte kullanılabilir görevlerin listesi için bkz . Görev başvurusu.

Görev, hedef öğesinin alt öğesi olarak görevin adına sahip bir öğe oluşturularak MSBuild proje dosyasında yürütülür. Görevler genellikle öğesinin öznitelikleri olarak geçirilen parametreleri kabul eder. Hem MSBuild özellikleri hem de öğeleri parametre olarak kullanılabilir. Örneğin, aşağıdaki kod MakeDir görevini çağırır ve önceki örnekte bildirilen özelliğin değerini BuildDir geçirir.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Görevler hakkında daha fazla bilgi için bkz . Görevler.

Hedefler

Görevleri belirli bir sırada birlikte hedefler ve proje dosyasının bölümlerini derleme işlemine giriş noktaları olarak gösterir. Hedefler genellikle okunabilirliği artırmak ve genişletmeye izin vermek için mantıksal bölümler halinde gruplandırılır. Derleme adımlarını hedeflere bölmek, kodun bu bölümünü her hedefe kopyalamadan derleme işleminin bir parçasını diğer hedeflerden çağırmanıza olanak tanır. Örneğin, derleme işlemindeki birkaç giriş noktası başvuruların oluşturulmasını gerektiriyorsa, başvuruları derleyen bir hedef oluşturabilir ve ardından gerekli olduğu her giriş noktasından bu hedefi çalıştırabilirsiniz.

Hedefler, Hedef öğesi kullanılarak proje dosyasında bildirilir. Örneğin, aşağıdaki kod adlı Compilebir hedef oluşturur ve daha sonra önceki örnekte bildirilen öğe listesini içeren Csc görevini çağırır.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

Daha gelişmiş senaryolarda hedefler, birbirleri arasındaki ilişkileri tanımlamak ve bağımlılık analizi gerçekleştirmek için kullanılabilir, böylece hedef güncelse derleme işleminin tüm bölümleri atlanabilir. Hedefler hakkında daha fazla bilgi için bkz . Hedefler.

Derleme günlükleri

Derleme hatalarını, uyarılarını ve iletilerini konsola veya başka bir çıkış cihazına kaydedebilirsiniz. Daha fazla bilgi için bkz . MSBuild ile derleme günlüklerini alma.

Visual Studio'da MSBuild kullanma

Visual Studio, yönetilen projeler hakkındaki derleme bilgilerini depolamak için MSBuild proje dosyası biçimini kullanır. Visual Studio arabirimi kullanılarak eklenen veya değiştirilen proje ayarları, her proje için oluşturulan .*proj dosyasına yansıtılır. Visual Studio yönetilen projeler oluşturmak için barındırılan bir MSBuild örneği kullanır. Bu, yönetilen bir projenin Visual Studio'da veya komut isteminde (Visual Studio yüklü olmasa bile) derlenebileceği ve sonuçların aynı olacağı anlamına gelir.

Visual Studio'da MSBuild kullanma hakkında bir öğretici için bkz . İzlenecek Yol: MSBuild Kullanma.

Çoklu Sürüm Desteği

Visual Studio'yu kullanarak, .NET Framework veya .NET Core'un .NET 5 ve üzeri sürümleri de dahil olmak üzere çeşitli sürümlerinden herhangi birinde çalışacak bir uygulama derleyebilirsiniz. Örneğin, bir uygulamayı 32 bit platformda .NET Framework 4 üzerinde çalışacak şekilde derleyebilir ve aynı uygulamayı 64 bit platformda .NET Framework 4.8 üzerinde çalışacak şekilde derleyebilirsiniz. Birden fazla çerçeveye derleme özelliği çoklu hedef oluşturma olarak adlandırılır.

Çoklu hedeflemenin avantajlarından bazıları şunlardır:

  • .NET Framework'ün 3.5 ve 4.7.2 sürümleri gibi önceki sürümlerini hedefleyen uygulamalar geliştirebilirsiniz.

  • Hedef çerçevenin önceden tanımlanmış bir alt kümesi olan bir çerçeve profilini hedefleyebilirsiniz.

  • .NET Framework'ün geçerli sürümü için bir hizmet paketi yayınlanırsa, bunu hedefleyebilirsiniz.

  • Çoklu hedefleme, bir uygulamanın yalnızca hedef çerçevede ve platformda bulunan işlevleri kullanmasını garanti eder.

Daha fazla bilgi için bkz . Multitargeting.

Derlemeyi özelleştirme

MSBuild, çok çeşitli özel derleme senaryoları için destek sağlar. Yerleşik işlevlerin çoğu geçersiz kılınabilir veya genişletilebilir. Bkz. Derlemenizi özelleştirme.

MSBuild'e program aracılığıyla erişme

Derleme aracı geliştiriyorsanız, MSBuild'i bir .NET uygulamasından program aracılığıyla çağırmak isteyebilirsiniz. MSBuild API'sini kullanarak karmaşık bir derleme sisteminin tüm yönlerini denetleyebilirsiniz. MSBuild, bu amaçlar için bir .NET uygulamasından kullanabileceğiniz tam API'ye (Microsoft.Build ad alanı) sahip bir NuGet paketi sağlar. Bkz . MSBuild API'sini kullanma.

MSBuild açık kaynak

MSBuild, .NET ekosisteminin geri kalanı gibi kullanıcı katkılarını kabul eden açık kaynak bir projedir. MSBuild kaynağını içeren depo GitHub'da kullanılabilir: MSBuild GitHub deposu.

Ayrıca bkz.

Ünvan Açıklama
İzlenecek yol: Sıfırdan MSBuild proje dosyası oluşturma Yalnızca bir metin düzenleyicisi kullanarak artımlı olarak temel bir proje dosyasının nasıl oluşturulacağını gösterir.
İzlenecek Yol: MSBuild Kullanma MSBuild'in yapı taşları tanıtılmaktadır ve Visual Studio IDE'yi kapatmadan MSBuild projelerinin nasıl yazılması, işlenip ayıklanacağını gösterir.
MSBuild kavramları MSBuild'in dört yapı taşları sunar: özellikler, öğeler, hedefler ve görevler.
Öğeler MSBuild dosya biçiminin arkasındaki genel kavramları ve parçaların nasıl bir araya geldiği açıklanır.
MSBuild özellikleri Özellikleri ve özellik koleksiyonlarını tanıtır. Özellikler, derlemeleri yapılandırmak için kullanılabilecek anahtar/değer çiftleridir.
Hedefler Görevleri belirli bir sırada gruplandırma ve derleme işleminin bölümlerinin komut satırında çağrılmasını etkinleştirme işlemlerini açıklar.
Görevler ATOMik derleme işlemlerini gerçekleştirmek için MSBuild tarafından kullanılabilecek yürütülebilir kod biriminin nasıl oluşturulacağını gösterir.
Koşullar BIR MSBuild öğesinde özniteliğinin Condition nasıl kullanılacağını açıklar.
İşlem grubu oluşturma MSBuild'in görevlerde ve hedeflerde yürütme için öğe listelerini meta veriye göre nasıl kategorilere ayırdığı açıklanır.
Çoklu Sürüm Desteği Birden çok .NET sürümünü ve/veya birden çok platformu hedeflemeyi gösterir.
Derleme günlüklerini alma Derleme olaylarının, iletilerinin ve hatalarının nasıl günlüğe kaydedildiği açıklanır.
MSBuild projeleri nasıl derler? MSBuild içinde kullanılan iç derleme işlemini açıklar
Kod oluşturma için özel görev oluşturma Kod örneğiyle özel bir görevin nasıl oluşturulacağını gösterir.
REST API istemcisi oluşturmak için MSBuild kullanma Kod örneğiyle REST API istemci oluşturma işlemini işlemek için derlemeyi genişletmeyi gösterir.
Ek Kaynaklar MSBuild hakkında daha fazla bilgi için topluluk ve destek kaynaklarını listeler.

Başvuru