MSBuild

Microsoft Build Engine, uygulama oluşturmaya yönelik bir platformdur. MSBuild olarak da bilinen bu altyapı, derleme platformunun yazılımları nasıl işlediğini ve derlediğini denetleyen bir proje dosyası için bir XML şeması sağlar. Visual Studio MSBuild kullanır, ancak MSBuild Visual Studio'ya bağımlı değildir. Proje veya çözüm dosyanızda msbuild.exe veya dotnet derleme ç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, .vcxprojve diğerleri) IDE'de 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'dan veya bir metin düzenleyicisi kullanarak genişletebilir veya değiştirebilirsiniz.

MSBuild'i yükleme

MSBuild'i Visual Studio içermeyen bir Windows sistemine yüklemek için, indirme sayfasındaVisual Studio için Derleme Araçları bölümüne gidin. MSBuild'i bu yöntemle yüklemek size MSBuild.exesağ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 komutu dotnet 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.

MSBuild Hakkında

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ımı 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 eğitici için bkz. Walkthrough: MSBuildKullanma.

Komut isteminde MSBuild kullanma

Komut isteminde MSBuild'i çalıştırmak için, uygun komut satırı seçenekleriyle birlikte bir proje dosyasını MSBuild.exegeçirmeniz gerekir. 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 Configurationolarak ayarlanmış MyProj.proj Debug oluşturmak için aşağıdaki komut satırı söz dizimini 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 proj, .csprojveya .vcxprojgibi .vbproj biten 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 dotnet build kullanırsınız. Bkz. dotnet build. Visual Studio veya Visual Studio Derleme Araçları'nı değil yalnızca .NET SDK'sını yüklerseniz, MSBuild'i yalnızca dotnet buildaracılığıyla yüklemeniz gerekir.

komut satırı dotnet build --help, dotnet buildseçeneklerinin tümünü değil, özel komut satırı seçeneklerini listeler, ancak MSBuild komut satırı başvurusunda listelenen tüm komut satırı seçeneklerini kullanmaya devam edebilirsiniz. dotnet build tarafından 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 standart derleme mantığını tanımlamak için .props ve .targets gibi uzantılarla içeri aktarılan MSBuild XML dosyalarını kullanır. .props dosyaları MSBuild özelliklerini ve .targets dosyaları MSBuild hedeflerini tanımlar. Bu içeri aktarmalar bazen Visual Studio proje dosyasında görünür, ancak .NET Core'da (ve .NET 5 ve üzeri) kullanılan .NET SDK projelerinde, 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şvurduğunda, .props ve .target dosyalarının içeri aktarılması 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.

Özellikler

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

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

öğesine bir Condition özniteliği yerleştirerek bir özelliği koşullu olarak tanımlayabilirsiniz. Koşul trueolarak değerlendirildiğinde, koşullu öğelerin içeriği dikkate alınmaz. Aşağıdaki örnekte, Configuration özelliği henüz tanımlanmamışsa tanımlanır.

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

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

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

Eşya

Öğ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 Compileadlı bir öğe türü oluşturur.

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

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

MSBuild'de, öğe ve öznitelik adları büyük/küçük harfe duyarlıdır. Ancak özellik, öğe ve meta veri adları için bu geçerli değildir. Aşağıdaki örnek, Compile, comPileveya başka bir büyük/küçük harf varyasyonu olan bir öğe türü oluşturur ve öğe türüne "one.cs;two.cs" değerini verir.

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

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. ITask arabirimini uygulayan bir yönetilen tür yazarak kendi görev tanımınızı 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 kopyala, dizinler oluşturan MakeDir ve Visual C# kaynak kod dosyalarını derleyen Csc verilebilir. Kullanım bilgileriyle birlikte kullanılabilir görevlerin listesi için bkz. Görev başvurusu.

Görev, bir Target öğesinin alt öğesi olarak görevin adıyla 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 BuildDir özelliğinin değerini geçirir.

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

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

Hedef

Belirli bir düzende görevleri gruplandırır ve proje dosyasının bölümlerini oluşturma sürecine giriş noktaları olarak sunar. 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 proje dosyasında Target öğesi kullanılarak bildirilir. Örneğin aşağıdaki kod, önceki örnekte bildirilen öğe listesini içeren Compile görevini çağıran adlı bir hedef oluşturur.

<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 up-to-date ise 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. MSBuildile 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'i kullanma hakkında bir kılavuz için bkz. İzlenecek Yol: MSBuild'i Kullanma.

Çoklu Hedef Oluşturma

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 3.5 SP1 ü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 ç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. çoklu hedefleme .

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ştirin.

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'siniiçin kullanma.

MSBuild açık kaynaktır

MSBuild, MSBuild GitHub deposunda kullanıcı katkılarını kabul eden bir açık kaynak projedir.

Ayrıca bkz.

Başlık	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.
Rehber: MSBuild Kullanımı	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.
Öğeleri	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.
Hedefleri	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	MSBuild tarafından atomik derleme işlemlerini gerçekleştirmek için kullanılabilecek yürütülebilir bir kod biriminin nasıl oluşturulacağını gösterir.
Koşullar	bir MSBuild öğesinde Condition özniteliğinin nasıl kullanılacağını açıklar.
toplu işleme	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 hedefleme	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 kaydedileceğini açıklar.
MSBuild projeleri nasıl oluşturur?	MSBuild içinde kullanılan iç derleme işlemini açıklar
Güvenli MSBuild kullanımı en iyi yöntemleri	MSBuild ile derlemelerinizi yapılandırmak ve çalıştırmak için en iyi yöntemleri 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.

Referans

• MSBuild başvuru
  Başvuru bilgileri içeren konulara bağlantılar.

• Sözlük
  Yaygın MSBuild terimlerini tanımlar.