MSBuild

  • Artikel

Microsoft Build Engine adalah platform untuk membuat aplikasi. Mesin ini, yang juga dikenal sebagai MSBuild, menyediakan skema XML untuk file proyek yang mengontrol cara platform build memproses dan membangun perangkat lunak. Visual Studio menggunakan MSBuild, tetapi MSBuild tidak bergantung pada Visual Studio. Dengan memanggil msbuild.exe atau dotnet build pada file proyek atau solusi, Anda dapat mengatur dan membangun produk di lingkungan tempat Visual Studio tidak diinstal.

Visual Studio menggunakan MSBuild untuk memuat dan membangun proyek terkelola. File proyek di Visual Studio (.csproj, .vbproj, .vcxproj, dan lainnya) berisi kode XML MSBuild yang dijalankan saat Anda membangun proyek dengan menggunakan IDE. Proyek Visual Studio mengimpor semua pengaturan dan proses build yang diperlukan untuk melakukan pekerjaan pengembangan umum, tetapi Anda dapat memperluas atau memodifikasinya dari dalam Visual Studio atau dengan menggunakan editor XML.

Untuk menginstal MSBuild pada sistem Windows yang tidak memiliki Visual Studio, buka Build Tools for Visual Studio di halaman unduhan. Menginstal MSBuild dengan metode ini memberi Anda MSBuild.exe.

Untuk .NET Core dan .NET 5 atau yang lebih baru, cara lain untuk mendapatkan yang setara dengan MSBuild adalah dengan menginstal .NET SDK. Perintah dotnet build build .NET tersedia dengan .NET SDK di macOS, Windows, atau Linux. Perintah dotnet build build .NET adalah pembungkus tipis atas versi .NET Core MSBuild.exe. Anda dapat menggunakan antarmuka baris perintah .NET Core (CLI), yang menggunakan MSBuild, untuk membangun proyek yang menargetkan .NET Core dan .NET 5 dan yang lebih baru.

Mulai di Visual Studio 2022, MSBuild versi 64-bit digunakan saat Anda membangun di Visual Studio.

Untuk informasi tentang MSBuild untuk C++, lihat MSBuild (C++).

Contoh berikut mengilustrasikan kapan Anda mungkin menjalankan build dengan memanggil MSBuild dari baris perintah, bukan IDE Visual Studio.

  • Visual Studio tidak diinstal.

  • Anda ingin menggunakan MSBuild versi 64-bit, dan Anda menggunakan Visual Studio 2019 atau yang lebih lama. Versi MSBuild ini biasanya tidak perlu, tetapi memungkinkan MSBuild untuk mengakses lebih banyak memori.

  • Anda ingin menjalankan build dalam beberapa proses. Namun, Anda dapat menggunakan IDE untuk mencapai hasil yang sama pada proyek di C++ dan C#.

  • Anda ingin memodifikasi sistem build. Misalnya, Anda mungkin ingin mengaktifkan tindakan berikut:

    • Proses file terlebih dahulu sebelum mencapai pengkompilasi.

    • Salin output build ke tempat yang berbeda.

    • Buat file terkompresi dari output build.

    • Lakukan langkah pasca-pemrosesan. Misalnya, Anda mungkin ingin memberi stempel pada rakitan dengan versi yang berbeda.

Anda dapat menulis kode di IDE Visual Studio tetapi menjalankan build dengan menggunakan MSBuild. Sebagai alternatif lain, Anda dapat membangun kode di IDE di komputer pengembangan tetapi menjalankan MSBuild dari baris perintah untuk membangun kode yang terintegrasi dari repositori sumber dengan kolaborasi dari beberapa pengembang.

Catatan

Anda dapat menggunakan Alur Azure untuk mengompilasi, menguji, dan menyebarkan aplikasi Anda secara otomatis. Sistem build Anda dapat otomatis menjalankan build saat pengembang memeriksa kode (misalnya, sebagai bagian dari strategi Integrasi Berkelanjutan) atau sesuai dengan jadwal (misalnya, build Smoke Test malam). Alur Azure mengompilasi kode Anda dengan menggunakan MSBuild. Untuk informasi selengkapnya, lihat Alur Azure.

Untuk tutorial pengantar untuk MSBuild di Windows, lihat Panduan: Menggunakan MSBuild.

Menggunakan MSBuild pada prompt perintah

Untuk menjalankan MSBuild pada prompt perintah, teruskan file proyek ke MSBuild.exe, bersama dengan opsi baris perintah yang sesuai. Opsi baris perintah memungkinkan Anda mengatur properti, menjalankan target tertentu, dan mengatur opsi lain yang mengontrol proses build. Misalnya, Anda akan menggunakan sintaks baris perintah berikut untuk membangun file MyProj.proj dengan properti Configuration yang diatur ke Debug.

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

MSBuild tidak mengubah perilakunya berdasarkan ekstensi file, tetapi konvensinya adalah menggunakan ekstensi yang berakhiran proj seperti .csproj, , .vcxprojatau .vbproj, untuk file input MSBuild utama, yang disebut "file proyek."

Untuk informasi selengkapnya tentang opsi baris perintah MSBuild, lihat Referensi baris perintah.

Penting

Sebelum Anda mengunduh proyek, tentukan keterpercayaan kode.

Untuk .NET Core dan .NET 5 atau yang lebih baru, Anda biasanya menggunakan dotnet build untuk memanggil MSBuild. Lihat build dotnet. Jika Anda hanya menginstal .NET SDK, dan bukan Visual Studio atau Alat Build Visual Studio, maka Anda hanya memiliki MSBuild melalui dotnet build.

Baris dotnet build --help perintah mencantumkan opsi baris perintah khusus untuk dotnet build, bukan semua opsi MSBuild.exe, tetapi Anda masih dapat menggunakan semua opsi baris perintah yang tercantum dalam referensi baris perintah MSBuild. Opsi yang tidak diproses oleh dotnet build diteruskan ke MSBuild.

File proyek

MSBuild menggunakan format file proyek berbasis XML yang mudah digunakan dan dapat diperluas. Format file proyek MSBuild memungkinkan pengembang menggambarkan item yang akan dibangun, serta cara item tersebut dibangun untuk sistem operasi dan konfigurasi yang berbeda. Selain itu, format file proyek memungkinkan pengembang menulis aturan build yang dapat digunakan kembali yang dapat diperhitungkan ke dalam file terpisah sehingga build dapat dilakukan secara konsisten di berbagai proyek dalam produk.

Sistem build Visual Studio menyimpan logika khusus proyek dalam file proyek itu sendiri, dan menggunakan file XML MSBuild yang diimpor dengan ekstensi seperti .props dan .targets untuk menentukan logika build standar. File .props menentukan properti MSBuild, dan .targets file menentukan target MSBuild. Impor ini terkadang terlihat dalam file proyek Visual Studio, tetapi dalam proyek yang lebih baru seperti proyek .NET Core, .NET 5 dan .NET 6, Anda tidak melihat impor dalam file proyek; sebagai gantinya, Anda melihat referensi SDK, yang terlihat seperti ini:

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

Ini disebut proyek bergaya SDK. Saat Anda mereferensikan SDK seperti .NET SDK, impor file dan .target ditentukan secara implisit .props oleh SDK.

Bagian berikut menjelaskan beberapa elemen dasar format file proyek MSBuild. Untuk tutorial tentang cara membuat file proyek dasar, lihat Panduan: Membuat file proyek MSBuild dari awal.

Properti

Properti mewakili pasangan kunci/nilai yang dapat digunakan untuk mengonfigurasi build. Properti dideklarasikan dengan membuat elemen yang memiliki nama properti sebagai turunan dari elemen PropertyGroup. Misalnya, kode berikut membuat properti bernama BuildDir yang memiliki nilai Build.

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

Anda dapat menentukan properti secara kondisional dengan menempatkan atribut Condition dalam elemen. Konten elemen kondisional diabaikan kecuali kondisi mengevaluasi ke true. Dalam contoh berikut, Configuration properti ditentukan jika belum ditentukan.

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

Properti dapat dirujuk di seluruh file proyek dengan menggunakan sintaks $(<PropertyName>). Misalnya, Anda dapat mereferensikan properti dalam contoh sebelumnya dengan menggunakan $(BuildDir) dan $(Configuration).

Untuk informasi selengkapnya tentang properti, lihat Properti MSBuild.

Item

Item adalah input ke dalam sistem build dan biasanya mewakili file. Item dikelompokkan ke dalam jenis item berdasarkan nama item yang ditentukan pengguna. Jenis item ini dapat digunakan sebagai parameter untuk tugas, yang menggunakan item individual untuk melakukan langkah-langkah proses build.

Item dideklarasikan dalam file proyek dengan membuat elemen yang memiliki nama jenis item sebagai elemen turunan dari elemen ItemGroup. Misalnya, kode berikut membuat jenis item bernama Compile, yang mencakup dua file.

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

Jenis item dapat dirujuk di seluruh file proyek dengan menggunakan sintaks @(<ItemType>). Misalnya, jenis item dalam contoh akan dirujuk dengan menggunakan @(Compile).

Di MSBuild, elemen dan nama atribut peka huruf besar/kecil. Namun, tidak untuk nama properti, item, dan metadata. Contoh berikut membuat jenis item Compile, comPile, atau variasi kasus lainnya, dan memberikan jenis item nilai "one.cs;two.cs".

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

Item dapat dideklarasikan dengan menggunakan karakter wildcard dan dapat berisi metadata tambahan untuk skenario build tingkat lanjut lainnya. Untuk informasi selengkapnya tentang item, lihat Item.

Tugas

Tugas adalah unit kode yang dapat dieksekusi yang digunakan oleh proyek MSBuild untuk melakukan operasi build. Misalnya, tugas mungkin mengompilasi file input atau menjalankan alat eksternal. Tugas dapat digunakan kembali, dan dapat dibagikan oleh pengembang lain dalam proyek yang berbeda.

Logika eksekusi tugas ditulis dalam kode terkendali dan dipetakan ke MSBuild dengan menggunakan elemen UsingTask. Anda dapat menulis tugas Anda sendiri dengan penulisan jenis terkelola yang mengimplementasikan antarmuka ITask. Untuk informasi selengkapnya tentang cara menulis tugas, lihat Penulisan tugas.

MSBuild menyertakan tugas umum yang dapat Anda ubah agar sesuai dengan kebutuhan Anda. Contohnya adalah Salin yang menyalin file, MakeDir yang membuat direktori, dan Csc yang mengompilasi file kode sumber Visual C#. Untuk daftar tugas yang tersedia bersama dengan informasi penggunaan, lihat Referensi tugas.

Tugas dijalankan dalam file proyek MSBuild dengan membuat elemen yang memiliki nama tugas sebagai elemen turunan dari elemen Target. Tugas biasanya menerima parameter, yang diteruskan sebagai atribut elemen. Properti dan item MSBuild dapat digunakan sebagai parameter. Misalnya, kode berikut memanggil tugas MakeDir dan meneruskan nilai properti BuildDir yang dideklarasikan dalam contoh sebelumnya.

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

Untuk informasi selengkapnya tentang tugas, lihat Tugas.

Target

Menargetkan tugas grup bersama-sama dalam urutan tertentu dan mengekspos bagian file proyek sebagai titik masuk ke dalam proses build. Target sering dikelompokkan ke dalam bagian logis untuk meningkatkan keterbacaan dan memungkinkan ekspansi. Memecah langkah-langkah build ke beberapa target memungkinkan Anda memanggil satu bagian proses build dari target lain tanpa menyalin bagian kode tersebut ke setiap target. Misalnya, jika beberapa titik masuk ke dalam proses build memerlukan referensi untuk dibangun, Anda dapat membuat target yang membangun referensi lalu menjalankan target tersebut dari setiap titik masuk yang memerlukannya.

Target dideklarasikan dalam file proyek dengan menggunakan elemen Target. Misalnya, kode berikut membuat target bernama Compile, yang memanggil tugas Csc dengan daftar item yang dideklarasikan dalam contoh sebelumnya.

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

Dalam skenario tingkat lanjut lainnya, target dapat digunakan untuk menggambarkan hubungan satu sama lain dan melakukan analisis dependensi sehingga seluruh bagian dari proses build dapat dilewati jika target tersebut sudah diperbarui. Untuk informasi selengkapnya tentang target, lihat Target.

Log build

Anda dapat mencatat kesalahan build, peringatan, dan pesan ke konsol atau perangkat output lainnya. Untuk informasi selengkapnya, lihat Mendapatkan log build dengan MSBuild.

Menggunakan MSBuild di Visual Studio

Visual Studio menggunakan format file proyek MSBuild untuk menyimpan informasi build tentang proyek terkelola. Pengaturan proyek yang ditambahkan atau diubah dengan menggunakan antarmuka Visual Studio tercermin dalam file .*proj yang dihasilkan untuk setiap proyek. Visual Studio menggunakan instans MSBuild yang dihosting untuk membangun proyek terkelola. Ini berarti bahwa proyek terkelola dapat dibangun di Visual Studio atau pada prompt perintah (bahkan jika Visual Studio tidak diinstal), dan hasilnya akan identik.

Untuk tutorial tentang cara menggunakan MSBuild di Visual Studio, lihat Panduan: Menggunakan MSBuild.

Multi-penargetan

Dengan menggunakan Visual Studio, Anda dapat mengkompilasi aplikasi untuk dijalankan pada salah satu dari beberapa versi .NET Framework atau .NET Core, termasuk .NET 5 dan yang lebih baru. Misalnya, Anda dapat mengkompilasi aplikasi untuk dijalankan pada .NET Framework 4 pada platform 32-bit, dan Anda dapat mengkompilasi aplikasi yang sama untuk dijalankan pada .NET Framework 4.8 pada platform 64-bit. Kemampuan untuk mengompilasi ke lebih dari satu kerangka kerja disebut multi-penargetan.

Ini adalah beberapa manfaat multi-penargetan:

  • Anda dapat mengembangkan aplikasi yang menargetkan versi .NET Framework sebelumnya, seperti versi 3.5 dan 4.7.2.

  • Anda dapat menargetkan profil kerangka kerja, yang merupakan sekumpulan kerangka kerja target yang telah ditentukan sebelumnya.

  • Jika paket layanan untuk versi .NET Framework saat ini dirilis, Anda dapat menargetkannya.

  • Multi-penargetan menjamin bahwa aplikasi hanya menggunakan fungsionalitas yang tersedia dalam kerangka kerja dan platform yang ditargetkan.

Untuk informasi selengkapnya, lihat Multi-penargetan.

Menyesuaikan build

MSBuild menyediakan dukungan untuk berbagai skenario build kustom. Sebagian besar fungsionalitas bawaan dapat ditimpa atau diperluas. Lihat Menkustomisasi build Anda.

Mengakses MSBuild secara terprogram

Jika Anda mengembangkan alat build, Anda mungkin ingin memanggil MSBuild secara terprogram dari aplikasi .NET. Dengan menggunakan MSBuild API, Anda dapat mengontrol semua aspek sistem build yang kompleks. MSBuild menyediakan paket NuGet dengan API lengkap (namespace Microsoft.Build) yang dapat Anda gunakan dari aplikasi .NET untuk tujuan ini. Lihat Menggunakan MSBuild API.

MSBuild sumber terbuka

MSBuild adalah proyek sumber terbuka yang menerima kontribusi pengguna, sama seperti ekosistem .NET lainnya. Repositori yang berisi sumber MSBuild tersedia di GitHub: Repositori GitHub MSBuild.

Lihat juga

Judul Deskripsi
Panduan: Membuat file proyek MSBuild dari awal Memperlihatkan cara membuat file proyek dasar secara bertahap, dengan hanya menggunakan editor teks.
Panduan: Menggunakan MSBuild Memperkenalkan blok penyusun MSBuild dan menunjukkan cara menulis, memanipulasi, dan men-debug proyek MSBuild tanpa menutup IDE Visual Studio.
Konsep MSBuild Menunjukkan empat blok penyusun MSBuild: properti, item, target, dan tugas.
Item Menjelaskan konsep umum di balik format file MSBuild dan bagaimana bagian-bagian tersebut saling melengkapi.
Properti MSBuild Memperkenalkan properti dan koleksi properti. Properti adalah pasangan kunci/nilai yang dapat digunakan untuk mengonfigurasi build.
Target Menjelaskan cara mengelompokkan tugas bersama-sama dalam urutan tertentu dan mengaktifkan bagian dari proses build untuk dipanggil pada baris perintah.
Tugas Memperlihatkan cara membuat unit kode yang dapat dieksekusi yang dapat digunakan oleh MSBuild untuk melakukan operasi build atomik.
Kondisi Membahas cara menggunakan atribut Condition dalam elemen MSBuild.
Batching Membahas bagaimana MSBuild mengategorikan daftar item menurut metadata untuk eksekusi dalam tugas dan target.
Multi-penargetan Menunjukkan cara menargetkan beberapa versi .NET dan/atau beberapa platform.
Mendapatkan log build Menjelaskan cara mencatat peristiwa build, pesan, dan kesalahan.
Cara MSBuild membangun proyek Menjelaskan proses build internal yang digunakan dalam MSBuild
Membuat tugas kustom untuk pembuatan kode Memperlihatkan cara membuat tugas kustom, dengan contoh kode.
Menggunakan MSBuild untuk menghasilkan klien REST API Menunjukkan cara memperluas build untuk menangani pembuatan klien REST API, dengan contoh kode.
Sumber Daya Tambahan: Mencantumkan komunitas dan sumber daya dukungan untuk informasi selengkapnya tentang MSBuild.

Referensi