Bagikan melalui

MSBuild

Microsoft Build Engine adalah platform untuk membangun 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 build msbuild.exe atau dotnet 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 di 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 teks.

Menginstal MSBuild

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 build .NET dotnet build tersedia dengan .NET SDK di macOS, Windows, atau Linux. Perintah build .NET dotnet build adalah pembungkus tipis di atas versi .NET Core untuk MSBuild.exe. Anda dapat menggunakan antarmuka baris perintah (CLI) .NET Core, yang menggunakan MSBuild, untuk membangun proyek yang menargetkan .NET Core dan .NET 5 dan versi yang lebih baru.

Tentang MSBuild

Dimulai dengan Visual Studio 2022, saat Anda membuat di Visual Studio, MSBuild versi 64-bit digunakan.

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

Contoh berikut mengilustrasikan kapan Anda mungkin menjalankan build dengan memanggil MSBuild dari baris perintah alih-alih 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 melakukan build dalam beberapa proses. Namun, Anda dapat menggunakan IDE untuk mencapai hasil yang sama pada proyek di C++ dan C#.

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

    • Pra-proses berkas sebelum mencapai kompilator.

    • Salin output build ke tempat yang berbeda.

    • Buat file terkompresi dari output build.

    • Lakukan langkah pasca-pemrosesan. Misalnya, Anda mungkin ingin menyematkan suatu versi berbeda pada rakitan.

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.

Nota

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

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

Gunakan 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 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, .vcxproj, atau .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 kepercayaan 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 Visual Studio Build Tools, maka Anda hanya memiliki MSBuild melalui dotnet build.

Baris perintah dotnet build --help mencantumkan opsi baris perintah khusus untuk dotnet build, tidak 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 dan dapat diperluas. Format file proyek MSBuild memungkinkan pengembang menggambarkan item yang akan dibangun, dan juga bagaimana mereka 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 file .targets menentukan target MSBuild. Impor ini terkadang terlihat dalam file proyek Visual Studio, tetapi dalam proyek .NET SDK, yang digunakan dalam .NET Core (dan .NET 5 dan yang lebih baru), 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 .props dan .target ditentukan secara implisit oleh SDK.

Bagian berikut menjelaskan beberapa elemen dasar format file proyek MSBuild. Untuk tutorial tentang cara membuat file proyek dasar, lihat Walkthrough: 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 bersyarat diabaikan kecuali jika kondisi menghasilkan nilai true. Dalam contoh berikut, properti Configuration 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 tipe item sebagai 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 terhadap besar/kecilnya huruf. Namun, nama properti, item, dan metadata tidak berubah. 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-item dapat dideklarasikan dengan menggunakan karakter wildcard dan dapat berisi metadata tambahan untuk skenario build yang lebih canggih. Untuk informasi selengkapnya tentang item, lihat item .

Tugas

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

Logika eksekusi tugas ditulis dalam kode terkelola dan dipetakan ke MSBuild dengan menggunakan elemen UsingTask. Anda dapat membuat tugas Anda sendiri dengan menulis tipe 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 Copy, yang menyalin file, MakeDir, yang membuat direktori, dan Csc, yang mengkompilasi 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 anak dari elemen Target. Tugas biasanya menerima parameter, yang diteruskan sebagai atribut elemen. Properti MSBuild dan item dapat digunakan sebagai parameter. Misalnya, kode berikut memanggil tugas MakeDir dan meneruskannya nilai dari properti BuildDir yang telah 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 build menjadi target memungkinkan Anda memanggil satu bagian proses build dari target lain tanpa menyalin bagian kode tersebut ke setiap target. Misalnya, jika beberapa titik entri ke dalam proses build memerlukan referensi untuk dibangun, Anda dapat membuat target yang membangun referensi lalu menjalankan target tersebut dari setiap titik masuk di mana diperlukan.

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

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

Dalam skenario yang lebih canggih, target dapat digunakan untuk menggambarkan hubungan satu sama lain dan melakukan analisis dependensi sehingga seluruh bagian dari proses build dapat dilewati jika target tersebut up-to-date. Untuk informasi selengkapnya tentang target, lihat Target.

Membangun log

Anda dapat mencatat kesalahan build, peringatan, dan pesan ke konsol atau perangkat output lainnya. Untuk informasi selengkapnya, lihat Cara memperoleh 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.

Memfokuskan pada Banyak Target

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 3.5 SP1 pada platform 32-bit, dan Anda dapat mengkompilasi aplikasi yang sama untuk dijalankan pada .NET Framework 4.8 pada platform 64-bit. Kemampuan untuk mengkompilasi ke lebih dari satu kerangka kerja diberi nama multitargeting.

Ini adalah beberapa manfaat multitarget:

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

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

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

  • Multitargeting menjamin bahwa aplikasi hanya menggunakan fungsionalitas yang tersedia dalam kerangka kerja dan platform target.

Untuk informasi selengkapnya, lihat Multitargeting.

Menyesuaikan rancangan

MSBuild menyediakan dukungan untuk berbagai skenario build kustom. Sebagian besar fungsionalitas bawaan dapat ditimpa atau diperluas. Lihat Kustomisasibuild 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 adalah sumber terbuka

MSBuild adalah proyek sumber terbuka yang menerima kontribusi pengguna di repositori MSBuild GitHub.

Lihat juga

Titel Deskripsi
Walkthrough: Membuat file proyek MSBuild dari awal Memperlihatkan cara membuat file proyek dasar secara bertahap, dengan hanya menggunakan editor teks.
Langkah-langkah : Menggunakan MSBuild Memperkenalkan blok penyusun MSBuild dan menunjukkan cara menulis, memanipulasi, dan men-debug proyek MSBuild tanpa menutup IDE Visual Studio.
Konsep MSBuild Memperkenalkan empat komponen MSBuild: properti, item, target, dan tugas.
Item Menjelaskan konsep umum di balik format file MSBuild dan bagaimana potongan-potongannya cocok bersama-sama.
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 Menunjukkan cara membuat unit kode yang dapat dieksekusi yang dapat digunakan oleh MSBuild untuk melakukan operasi build atom.
Kondisi Membahas cara menggunakan atribut Condition dalam elemen MSBuild.
Batching Membahas bagaimana MSBuild mengategorikan daftar item menurut metadata untuk eksekusi dalam tugas dan target.
Multipenargetan Menunjukkan cara menargetkan beberapa versi .NET dan/atau beberapa platform.
Mendapatkan log build Menjelaskan cara mencatat peristiwa build, pesan, dan kesalahan.
Bagaimana MSBuild membangun proyek Menjelaskan proses build internal yang digunakan dalam MSBuild
Praktik terbaik penggunaan MSBuild yang aman Menjelaskan praktik terbaik untuk mengonfigurasi dan menjalankan build Anda dengan 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

  • referensi MSBuild
    Tautan ke topik yang berisi informasi referensi.

  • Glosarium
    Menentukan istilah MSBuild umum.

  • Last updated on