Tutorial: Menggunakan MSBuild

MSBuild adalah platform build untuk Microsoft dan Visual Studio. Tutorial ini memperkenalkan Anda ke blok penyusun MSBuild dan menunjukkan kepada Anda cara menulis, memanipulasi, dan men-debug proyek MSBuild. Anda belajar tentang:

• Membuat dan memanipulasi file proyek.

• Cara menggunakan properti build.

• Cara menggunakan item build.

Anda dapat menjalankan MSBuild dari Visual Studio, atau dari Jendela Perintah. Dalam tutorial ini, Anda membuat file proyek MSBuild menggunakan Visual Studio. Anda mengedit file proyek di Visual Studio, dan menggunakan Jendela Perintah untuk mem-build proyek dan memeriksa hasilnya.

Menginstal MSBuild

Jika Anda memiliki Visual Studio, Anda sudah menginstal MSBuild. Dengan Visual Studio 2022, itu diinstal di bawah folder penginstalan Visual Studio. Untuk penginstalan default umum pada Windows 10, MSBuild.exe berada di bawah folder penginstalan di MSBuild\Current\Bin.

Di alat penginstal Visual Studio, navigasikan ke Komponen Individu, dan cari kotak centang untuk MSBuild. Ini secara otomatis dipilih saat Anda memilih salah satu beban kerja lain untuk diinstal.

Untuk menginstal MSBuild pada sistem yang tidak memiliki Visual Studio, buka Alat Build untuk Visual Studio 2022 di halaman unduhan. Cara lain untuk mendapatkan MSBuild adalah dengan menginstal SDK .NET.

Membuat proyek MSBuild

Sistem proyek Visual Studio didasarkan pada MSBuild. Sangat mudah untuk membuat file proyek baru menggunakan Visual Studio. Di bagian ini, Anda membuat file proyek C#. Anda dapat memilih untuk membuat file proyek Visual Basic sebagai gantinya. Dalam konteks tutorial ini, perbedaan antara dua file proyek adalah kecil.

Untuk membuat file proyek

1. Buka Visual Studio dan buat proyek:

   Dalam kotak pencarian, ketik winforms, lalu pilih Buat Aplikasi Formulir Windows baru (.NET Framework). Dalam kotak dialog yang muncul, pilih Buat.

   Di kotak Nama proyek, ketik BuildApp. Masukkan Lokasi untuk solusi, misalnya, D:\.

2. Klik OK atau Buat untuk membuat file proyek.

Memeriksa file proyek

Di bagian sebelumnya, Anda menggunakan Visual Studio untuk membuat file proyek C#. File proyek diwakili dalam Penjelajah Solusi oleh node proyek bernama BuildApp. Anda dapat menggunakan editor kode Visual Studio untuk memeriksa file proyek.

Untuk memeriksa file proyek

1. Di Penjelajah Solusi, klik node proyek BuildApp.

2. Di browser Properti, perhatikan bahwa properti File Proyek adalah BuildApp.csproj. Semua file proyek diberi nama dengan akhiran proj. Jika Anda telah membuat proyek Visual Basic, nama file proyek adalah BuildApp.vbproj.

3. Klik kanan node proyek lagi, lalu klik Edit BuildApp.csproj.

   File proyek muncul di editor kode.

Catatan

Untuk beberapa jenis proyek, seperti C++, Anda perlu membatalkan pemuatan proyek (klik kanan pada file proyek dan pilih Batal muat proyek) sebelum Anda dapat membuka dan mengedit file proyek.

Target dan tugas

File proyek adalah file berformat XML dengan node akar Proyek.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0"  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

Sebagian besar proyek .NET memiliki Sdk atribut . Proyek-proyek ini disebut proyek bergaya SDK.

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

Ada banyak variasi .NET SDK untuk tujuan khusus; mereka dijelaskan di .NET Project SDK.

Pekerjaan mem-build aplikasi dilakukan dengan elemen Target dan Tugas.

• Tugas adalah unit kerja terkecil, dengan kata lain, "atom" dari build. Tugas adalah komponen yang dapat dieksekusi independen, yang dapat memiliki input dan output. Tidak ada tugas yang saat ini dirujuk atau ditentukan dalam file proyek. Anda menambahkan tugas ke file proyek di bagian berikut. Untuk informasi selengkapnya, lihat Tugas.

• Target adalah urutan tugas yang diberi nama. Ini mungkin urutan tugas bernama, tetapi secara kritis, mewakili sesuatu yang akan dibangun atau dilakukan, sehingga harus didefinisikan dengan cara yang berorientasi pada tujuan. Untuk informasi selengkapnya, lihat Target.

Target default tidak ditentukan dalam file proyek. Sebaliknya, ini ditentukan dalam proyek yang diimpor. Elemen Impor menentukan proyek yang diimpor. Misalnya, dalam proyek C#, target default diimpor dari file Microsoft.CSharp.targets.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

File yang diimpor secara efektif dimasukkan ke dalam file proyek di mana pun file tersebut direferensikan.

Dalam proyek bergaya SDK, Anda tidak melihat elemen impor ini, karena atribut SDK menyebabkan file ini diimpor secara implisit.

MSBuild melacak target build, dan menjamin bahwa setiap target di-build tidak lebih dari sekali.

Menambahkan target dan tugas

Tambahkan target ke file proyek. Tambahkan tugas ke target yang mencetak pesan.

Untuk menambahkan target dan tugas

1. Tambahkan baris ini ke file proyek, tepat setelah pernyataan Impor atau elemen Project pembukaan.

   <Target Name="HelloWorld">
   </Target>
   

   Kode ini membuat target bernama HelloWorld. Perhatikan bahwa Anda memiliki dukungan IntelliSense saat mengedit file proyek.

2. Tambahkan baris ke target HelloWorld, sehingga bagian yang dihasilkan terlihat seperti ini:

   <Target Name="HelloWorld">
     <Message Text="Hello"></Message>  <Message Text="World"></Message>
   </Target>
   

3. Simpan file proyek.

Tugas ini Message adalah salah satu dari banyak tugas yang dikirim dengan MSBuild. Untuk daftar lengkap tugas dan informasi penggunaan yang tersedia, lihat Referensi tugas.

Tugas mengambil Message nilai string atribut Teks sebagai input dan menampilkannya pada perangkat output (atau menulisnya ke satu atau beberapa log, jika berlaku). Target HelloWorld menjalankan tugas Pesan dua kali: pertama untuk menampilkan "Halo", lalu menampilkan "Dunia."

Mem-build target

Jika Anda mencoba membangun proyek ini dari Visual Studio, proyek ini tidak membangun target yang Anda tentukan. Itu karena Visual Studio memilih target default, yang masih merupakan target dalam file yang diimpor .targets .

Jalankan MSBuild dari Perintah Pengembang untuk Visual Studio untuk membangun target HelloWorld yang ditentukan sebelumnya. Gunakan sakelar baris perintah -target atau -t untuk memilih target.

Catatan

Kami akan merujuk ke Prompt Perintah Pengembang sebagai Jendela Perintah di bagian berikut.

Untuk mem-build target:

1. Buka Jendela Perintah.

   Dalam kotak pencarian di taskbar, mulai ketik nama alat, seperti dev atau developer command prompt. Ini menampilkan daftar aplikasi terinstal yang cocok dengan pola pencarian Anda.

   Jika Anda perlu menemukannya secara manual, filenya adalah LaunchDevCmd.bat di folder penginstalan {Visual Studio}\Common7\Tools .

2. Dari jendela perintah, navigasikan ke folder yang berisi file proyek, dalam hal ini, D:\BuildApp\BuildApp.

3. Jalankan msbuild dengan sakelar perintah -t:HelloWorld. Perintah ini memilih dan membangun target HelloWorld:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Periksa output di Jendela perintah. Anda akan melihat dua baris "Halo" dan "Dunia":

   Hello
   World
   

Catatan

Jika sebaliknya Anda melihat The target "HelloWorld" does not exist in the project, Anda mungkin lupa menyimpan file proyek di editor kode. Simpan file dan coba lagi.

Dengan bergantian antara editor kode dan jendela perintah, Anda dapat mengubah file proyek dan melihat hasilnya dengan cepat.

Properti build

Properti build adalah pasangan nama-nilai yang memandu build. Beberapa properti build sudah ditentukan di bagian atas file proyek:

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Semua properti adalah elemen turunan dari elemen PropertyGroup. Nama properti adalah nama elemen turunan, dan nilai properti adalah elemen teks dari elemen turunan. Contohnya,

<TargetFrameworkVersion>v4.5</TargetFrameworkVersion>

mendefinisikan properti bernama TargetFrameworkVersion, memberinya nilai string "v4.5."

Properti build dapat ditentukan ulang kapan saja. Jika

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

muncul nanti dalam file proyek, atau dalam file yang diimpor nanti dalam file proyek, maka TargetFrameworkVersion mengambil nilai baru "v3.5."

Memeriksa nilai properti

Untuk mendapatkan nilai properti, gunakan sintaksis berikut, di mana PropertyName adalah nama properti:

$(PropertyName)

Gunakan sintaksis ini untuk memeriksa beberapa properti dalam file proyek.

Untuk memeriksa nilai properti

1. Dari editor kode, ganti target HelloWorld dengan kode ini:

   <Target Name="HelloWorld">
     <Message Text="Configuration is $(Configuration)" />
     <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
   </Target>
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat kedua baris ini (output Anda mungkin berbeda):

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
   

Properti kondisional

Banyak properti seperti Configuration ditentukan secara kondisional, yaitu, atribut Condition muncul di elemen properti. Properti kondisional ditentukan atau didefinisikan ulang hanya jika kondisi mengevaluasi ke "true." Properti yang tidak ditentukan diberikan nilai default string kosong. Contohnya,

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

berarti "Jika properti Konfigurasi belum ditentukan, tentukan dan berikan nilai 'Debug'."

Hampir semua elemen MSBuild dapat memiliki atribut Kondisi. Untuk diskusi lebih lanjut tentang penggunaan atribut Kondisi, lihat Kondisi.

Properti yang dipesan

MSBuild mencadangkan beberapa nama properti untuk menyimpan informasi tentang file proyek dan biner MSBuild. MSBuildToolsPath adalah contoh properti yang dicadangkan. Properti yang dicadangkan direferensikan dengan notasi $ seperti properti lainnya. Untuk informasi selengkapnya, lihat Cara: Mereferensikan nama atau lokasi file proyek dan Properti MSBuild yang dicadangkan dan dikenal.

Variabel lingkungan

Anda dapat mereferensikan variabel lingkungan dalam file proyek dengan cara yang sama seperti properti build. Misalnya, untuk menggunakan variabel lingkungan PATH dalam file proyek Anda, gunakan $(Path). Jika proyek berisi definisi properti yang memiliki nama yang sama dengan variabel lingkungan, properti dalam proyek akan mengambil alih nilai variabel lingkungan. Untuk informasi selengkapnya, lihat Cara: Menggunakan variabel lingkungan dalam build.

Mengatur properti dari baris perintah

Properti dapat ditentukan pada baris perintah menggunakan sakelar baris perintah -property atau -p. Nilai properti yang diterima dari baris perintah mengambil alih nilai properti yang ditetapkan dalam file proyek dan variabel lingkungan.

Untuk mengatur nilai properti dari baris perintah:

1. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release
   

2. Memeriksa output. Anda akan melihat baris ini:

   Configuration is Release.
   

MSBuild membuat properti Konfigurasi dan memberinya nilai "Rilis."

Karakter khusus

Karakter tertentu memiliki arti khusus dalam file proyek MSBuild. Contoh karakter ini termasuk titik koma (;) dan tanda bintang (*). Untuk menggunakan karakter khusus ini sebagai literal dalam file proyek, karakter tersebut harus ditentukan menggunakan sintaksis %<xx>, di mana <xx> mewakili nilai heksadesimal ASCII karakter tersebut.

Ubah tugas Pesan untuk menampilkan nilai properti Konfigurasi dengan karakter khusus agar lebih mudah dibaca.

Untuk menggunakan karakter khusus dalam tugas Pesan:

1. Dari editor kode, ganti kedua tugas Pesan dengan baris ini:

   <Message Text="%24(Configuration) is %22$(Configuration)%22" />
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat baris ini:

   $(Configuration) is "Debug"
   

Untuk informasi selengkapnya, lihat Karakter khusus MSBuild.

Mem-build item

Item adalah bagian dari informasi, biasanya nama file, yang digunakan sebagai input ke sistem build. Misalnya, kumpulan item yang mewakili file sumber mungkin diteruskan ke tugas bernama Kompilasi untuk mengompilasinya ke dalam rakitan.

Semua item adalah elemen turunan dari elemen ItemGroup. Nama item adalah nama elemen turunan, dan nilai item adalah nilai atribut Sertakan elemen turunan. Nilai item dengan nama yang sama dikumpulkan ke dalam tipe item dengan nama tersebut. Contohnya,

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

menentukan grup item yang berisi dua item. Tipe item Kompilasi memiliki dua nilai: Program.cs dan Properties\AssemblyInfo.cs.

Kode berikut membuat jenis item yang sama dengan mendeklarasikan kedua file dalam satu Include atribut, dipisahkan oleh titik koma.

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

Untuk informasi selengkapnya, lihat Item.

Catatan

Jalur file relatif terhadap folder yang berisi file proyek MSBuild, bahkan jika file proyek adalah file proyek yang diimpor. Ada beberapa pengecualian untuk hal ini, seperti saat menggunakan elemen Impor dan UsingTask.

Memeriksa nilai tipe item

Untuk mendapatkan nilai tipe item, gunakan sintaks berikut, di mana ItemType adalah nama jenis item:

@(ItemType)

Gunakan sintaks ini untuk memeriksa Compile jenis item dalam file proyek.

Untuk memeriksa nilai tipe item:

1. Dari editor kode, ganti tugas target HelloWorld dengan kode ini:

   <Target Name="HelloWorld">
     <Message Text="Compile item type contains @(Compile)" />
   </Target>
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat garis panjang ini:

   Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
   

Nilai tipe item dipisahkan dengan titik koma secara default.

Untuk mengubah pemisah tipe item, gunakan sintaksis berikut, di mana ItemType adalah tipe item dan Pemisah adalah string dari satu atau beberapa karakter pemisah:

@(ItemType, Separator)

Ubah tugas Pesan untuk menggunakan pengembalian pengangkutan dan umpan baris (%0A%0D) untuk menampilkan Kompilasi item satu per baris.

Untuk menampilkan nilai tipe item satu per baris

1. Dari editor kode, ganti tugas Pesan dengan baris ini:

   <Message Text="Compile item type contains @(Compile, '%0A%0D')" />
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat baris-baris ini:

   Compile item type contains Form1.cs
   Form1.Designer.cs
   Program.cs
   Properties\AssemblyInfo.cs
   Properties\Resources.Designer.cs
   Properties\Settings.Designer.cs
   

Sertakan, Kecualikan, dan wildcard

Anda dapat menggunakan wildcard "*", "**", dan "?" dengan atribut Sertakan untuk menambahkan item ke tipe item. Contohnya,

<Photos Include="images\*.jpeg" />

menambahkan semua file dengan ekstensi file .jpeg di folder gambar ke tipe item Foto, sementara

<Photos Include="images\**\*.jpeg" />

menambahkan semua file dengan ekstensi file .jpeg di folder gambar, dan semua subfoldernya, ke tipe item Foto. Untuk contoh selengkapnya, lihat Cara: Memilih file yang akan di-build.

Perhatikan bahwa sebagai item dinyatakan ditambahkan ke jenis item. Contohnya,

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

membuat tipe item bernama Foto yang berisi semua file di folder gambar dengan ekstensi file baik .jpeg atau .gif. Baris-baris tersebut setara dengan baris berikut:

<Photos Include="images\*.jpeg;images\*.gif" />

Anda dapat mengecualikan item dari jenis item dengan Exclude atribut . Contohnya,

<Compile Include="*.cs" Exclude="*Designer*">

menambahkan semua file dengan ekstensi file .cs ke tipe item Kompilasi, kecuali untuk file yang namanya berisi string Perancang. Untuk contoh lainnya, lihat Cara: Mengecualikan file dari build.

Atribut Exclude hanya memengaruhi item yang ditambahkan oleh atribut Sertakan dalam elemen item yang berisi keduanya. Contohnya,

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

tidak akan mengecualikan file Form1.cs, yang ditambahkan dalam elemen item sebelumnya.

Untuk menyertakan dan mengecualikan item

1. Dari editor kode, ganti tugas Pesan dengan baris ini:

   <Message Text="XFiles item type contains @(XFiles)" />
   

2. Tambahkan grup item ini tepat setelah elemen Impor:

   <ItemGroup>
      <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
   </ItemGroup>
   

3. Simpan file proyek.

4. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Memeriksa output. Anda akan melihat baris ini:

   XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx
   

Metadata item

Item dapat berisi metadata selain informasi yang dikumpulkan dari Include atribut dan Exclude . Tugas yang memerlukan informasi lebih lanjut tentang item daripada hanya nilai item yang dapat menggunakan metadata ini.

Metadata item dideklarasikan dalam file proyek dengan membuat elemen dengan nama metadata sebagai elemen turunan dari item tersebut. Item dapat memiliki nilai metadata nol atau lebih. Misalnya, item CSFile berikut memiliki metadata Kultur dengan nilai "Fr":

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Untuk mendapatkan nilai metadata jenis item, gunakan sintaks berikut, di mana ItemType adalah nama jenis item dan MetaDataName adalah nama metadata:

%(ItemType.MetaDataName)

Untuk memeriksa metadata item:

1. Dari editor kode, ganti tugas Pesan dengan baris ini:

   <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat baris-baris ini:

   Compile.DependentUpon:
   Compile.DependentUpon: Form1.cs
   Compile.DependentUpon: Resources.resx
   Compile.DependentUpon: Settings.settings
   

Perhatikan bagaimana frasa "Compile.DependentUpon" muncul beberapa kali. Penggunaan metadata dengan sintaks ini dalam target menyebabkan "batching." Batching berarti bahwa tugas dalam target dijalankan sekali untuk setiap nilai metadata unik. Batching adalah skrip MSBuild yang setara dengan konstruksi pemrograman "foreach loop" umum. Untuk informasi selengkapnya, lihat Batching.

Metadata terkenal

Setiap kali item ditambahkan ke daftar item, item tersebut diberi beberapa metadata terkenal. Misalnya, %(Filename) mengembalikan nama file item apa pun. Untuk daftar lengkap metadata terkenal, lihat Metadata item terkenal.

Untuk memeriksa metadata terkenal:

1. Dari editor kode, ganti tugas Pesan dengan baris ini:

   <Message Text="Compile Filename: %(Compile.Filename)" />
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat baris-baris ini:

   Compile Filename: Form1
   Compile Filename: Form1.Designer
   Compile Filename: Program
   Compile Filename: AssemblyInfo
   Compile Filename: Resources.Designer
   Compile Filename: Settings.Designer
   

Dengan membandingkan dua contoh sebelumnya, Anda dapat melihat bahwa meskipun tidak setiap item dalam jenis item Kompilasi memiliki metadata DependentUpon, semua item memiliki metadata Nama File yang terkenal.

Transformasi metadata

Daftar item dapat diubah menjadi daftar item baru. Untuk mengubah daftar item, gunakan sintaksis berikut, dengan <ItemType> adalah nama tipe item dan <MetadataName> adalah nama metadata:

@(ItemType -> '%(MetadataName)')

Misalnya, daftar item dari file sumber dapat diubah menjadi kumpulan file objek menggunakan ekspresi seperti @(SourceFiles -> '%(Filename).obj'). Untuk mengetahui informasi selengkapnya, lihat Transformasi.

Untuk mengubah item menggunakan metadata:

1. Dari editor kode, ganti tugas Pesan dengan baris ini:

   <Message Text="Backup files: @(Compile->'%(filename).bak')" />
   

2. Simpan file proyek.

3. Dari Jendela Perintah, masukkan dan jalankan baris ini:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Memeriksa output. Anda akan melihat baris ini:

   Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
   

Perhatikan bahwa metadata yang dinyatakan dalam sintaks ini tidak menyebabkan batching.

Langkah berikutnya

Untuk mempelajari cara membuat file proyek sederhana satu langkah pada satu waktu, di Windows, coba Buat file proyek MSBuild dari awal.

Jika Anda terutama menggunakan .NET SDK, lanjutkan membaca di Referensi MSBuild untuk Proyek .NET SDK.

Konten terkait

• Gambaran Umum MSBuild
• Referensi MSBuild