Memahami file proyek
oleh Jason Lee
File proyek Microsoft Build Engine (MSBuild) terletak di jantung proses build dan penyebaran. Topik ini dimulai dengan gambaran umum konseptual MSBuild dan file proyek. Ini menjelaskan komponen utama yang akan Anda temui ketika Anda bekerja dengan file proyek, dan bekerja melalui contoh bagaimana Anda dapat menggunakan file proyek untuk menyebarkan aplikasi dunia nyata.
Yang akan Anda pelajari:
- Bagaimana MSBuild menggunakan file proyek MSBuild untuk membangun proyek.
- Bagaimana MSBuild terintegrasi dengan teknologi penyebaran, seperti Alat Penyebaran Web (Web Deploy) Internet Information Services (IIS).
- Cara memahami komponen utama file proyek.
- Bagaimana Anda dapat menggunakan file proyek untuk membangun dan menyebarkan aplikasi yang kompleks.
MSBuild dan File Proyek
Saat Anda membuat dan membangun solusi di Visual Studio, Visual Studio menggunakan MSBuild untuk membangun setiap proyek dalam solusi Anda. Setiap proyek Visual Studio menyertakan file proyek MSBuild, dengan ekstensi file yang mencerminkan jenis proyek—misalnya, proyek C# (.csproj), proyek Visual Basic.NET (.vbproj), atau proyek database (.dbproj). Untuk membangun proyek, MSBuild harus memproses file proyek yang terkait dengan proyek. File proyek adalah dokumen XML yang berisi semua informasi dan instruksi yang dibutuhkan MSBuild untuk membangun proyek Anda, seperti konten yang akan disertakan, persyaratan platform, informasi penerapan versi, server web atau pengaturan server database, dan tugas yang harus dilakukan.
File proyek MSBuild didasarkan pada skema XML MSBuild, dan akibatnya proses build sepenuhnya terbuka dan transparan. Selain itu, Anda tidak perlu menginstal Visual Studio untuk menggunakan mesin MSBuild—MSBuild.exe yang dapat dieksekusi adalah bagian dari .NET Framework, dan Anda dapat menjalankannya dari prompt perintah. Sebagai pengembang, Anda dapat membuat file proyek MSBuild Anda sendiri, menggunakan skema XML MSBuild, untuk memberlakukan kontrol canggih dan terperinci atas cara proyek Anda dibangun dan disebarkan. File proyek kustom ini berfungsi dengan cara yang sama persis dengan file proyek yang dihasilkan Visual Studio secara otomatis.
Catatan
Anda juga dapat menggunakan file proyek MSBuild dengan layanan Team Build di Team Foundation Server (TFS). Misalnya, Anda dapat menggunakan file proyek dalam skenario integrasi berkelanjutan (CI) untuk mengotomatiskan penyebaran ke lingkungan pengujian saat kode baru dicek masuk. Untuk informasi selengkapnya, lihat Mengonfigurasi Server Team Foundation untuk Penyebaran Web Otomatis.
Konvensi Penamaan File Proyek
Saat membuat file proyek sendiri, Anda dapat menggunakan ekstensi file apa pun yang Anda suka. Namun, untuk membuat solusi Anda lebih mudah dipahami orang lain, Anda harus menggunakan konvensi umum ini:
- Gunakan ekstensi .proj saat Anda membuat file proyek yang membangun proyek.
- Gunakan ekstensi .targets saat Anda membuat file proyek yang dapat digunakan kembali untuk mengimpor ke file proyek lain. File dengan ekstensi .targets biasanya tidak membangun apa pun sendiri, file tersebut hanya berisi instruksi yang dapat Anda impor ke file .proj Anda.
Integrasi dengan Teknologi Penyebaran
Jika Anda telah bekerja dengan proyek aplikasi web di Visual Studio 2010, seperti aplikasi web ASP.NET dan ASP.NET aplikasi web MVC, Anda akan tahu bahwa proyek-proyek ini menyertakan dukungan bawaan untuk pengemasan dan penyebaran aplikasi web ke lingkungan target. Halaman Properti untuk proyek ini mencakup tab Paket/Terbitkan Web dan Paket/Terbitkan SQL yang dapat Anda gunakan untuk mengonfigurasi bagaimana komponen aplikasi Anda dikemas dan disebarkan. Ini memperlihatkan tab Web Paket/Terbitkan :
Teknologi yang mendasar di balik kemampuan ini dikenal sebagai Web Publishing Pipeline (WPP). WPP pada dasarnya menyaingkan MSBuild dan Web Deploy untuk menyediakan proses build, paket, dan penyebaran yang lengkap untuk aplikasi web Anda.
Kabar baiknya adalah Anda dapat memanfaatkan titik integrasi yang disediakan WPP ketika Anda membuat file proyek kustom untuk proyek web. Anda dapat menyertakan instruksi penyebaran dalam file proyek, yang memungkinkan Anda membangun proyek, membuat paket penyebaran web, dan menginstal paket ini di server jarak jauh melalui satu file proyek dan satu panggilan ke MSBuild. Anda juga dapat memanggil executable lainnya sebagai bagian dari proses build Anda. Misalnya, Anda dapat menjalankan alat baris perintah VSDBCMD.exe untuk menyebarkan database dari file skema. Selama topik ini, Anda akan melihat bagaimana Anda dapat memanfaatkan kemampuan ini untuk memenuhi persyaratan skenario penyebaran perusahaan Anda.
Catatan
Untuk informasi selengkapnya tentang cara kerja proses penyebaran aplikasi web, lihat Gambaran Umum Penyebaran Proyek Aplikasi Web ASP.NET.
Anatomi File Proyek
Sebelum Anda melihat proses build secara lebih rinci, ada baiknya mengambil beberapa saat untuk membiasakan diri dengan struktur dasar file proyek MSBuild. Bagian ini memberikan gambaran umum tentang elemen yang lebih umum yang akan Anda temui saat meninjau, mengedit, atau membuat file proyek. Secara khusus, Anda akan mempelajari:
- Cara menggunakan properti untuk mengelola variabel untuk proses build.
- Cara menggunakan item untuk mengidentifikasi input ke proses build, seperti file kode.
- Cara menggunakan target dan tugas untuk memberikan instruksi eksekusi ke MSBuild, menggunakan properti dan item yang ditentukan di tempat lain dalam file proyek.
Ini menunjukkan hubungan antara elemen kunci dalam file proyek MSBuild:
Elemen Proyek
Elemen Project adalah elemen root dari setiap file proyek. Selain mengidentifikasi skema XML untuk file proyek, elemen Project dapat menyertakan atribut untuk menentukan titik masuk untuk proses build. Misalnya, dalam solusi sampel Contact Manager, file Publish.proj menentukan bahwa build harus dimulai dengan memanggil target bernama FullPublish.
<Project ToolsVersion="4.0" DefaultTargets="FullPublish"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
</Project>
Properti dan Kondisi
File proyek biasanya perlu memberikan banyak informasi yang berbeda untuk berhasil membangun dan menyebarkan proyek Anda. Informasi ini dapat mencakup nama server, string koneksi, kredensial, konfigurasi build, jalur file sumber dan tujuan, dan informasi lain yang ingin Anda sertakan untuk mendukung kustomisasi. Dalam file proyek, properti harus ditentukan dalam elemen PropertyGroup . Properti MSBuild terdiri dari pasangan kunci-nilai. Dalam elemen PropertyGroup , nama elemen menentukan kunci properti dan konten elemen menentukan nilai properti. Misalnya, Anda dapat menentukan properti bernama ServerName dan ConnectionString untuk menyimpan nama server statis dan string koneksi.
<PropertyGroup>
<ServerName>FABRIKAM\TEST1</ServerName>
<ConnectionString>
Data Source=FABRIKAM\TESTDB;InitialCatalog=ContactManager,...
</ConnectionString>
</PropertyGroup>
Untuk mengambil nilai properti, gunakan format $(PropertyName). Misalnya, untuk mengambil nilai properti ServerName , Anda akan mengetik:
$(ServerName)
Catatan
Anda akan melihat contoh bagaimana dan kapan menggunakan nilai properti nanti dalam topik ini.
Menyematkan informasi sebagai properti statis dalam file proyek tidak selalu merupakan pendekatan ideal untuk mengelola proses build. Dalam banyak skenario, Anda mungkin ingin mendapatkan informasi dari sumber lain atau memberdayakan pengguna untuk memberikan informasi dari prompt perintah. MSBuild memungkinkan Anda menentukan nilai properti apa pun sebagai parameter baris perintah. Misalnya, pengguna dapat memberikan nilai untuk ServerName saat ia menjalankan MSBuild.exe dari baris perintah.
msbuild.exe Publish.proj /p:ServerName=FABRIKAM\TESTWEB1
Catatan
Untuk informasi selengkapnya tentang argumen dan sakelar yang dapat Anda gunakan dengan MSBuild.exe, lihat Referensi Baris Perintah MSBuild.
Anda dapat menggunakan sintaks properti yang sama untuk mendapatkan nilai variabel lingkungan dan properti proyek bawaan. Banyak properti yang umum digunakan didefinisikan untuk Anda, dan Anda dapat menggunakannya dalam file proyek Anda dengan menyertakan nama parameter yang relevan. Misalnya, untuk mengambil platform proyek saat ini—misalnya, x86 atau AnyCpu—Anda dapat menyertakan referensi properti $(Platform) dalam file proyek Anda. Untuk informasi selengkapnya, lihat Makro untuk Perintah dan Properti Build, Properti Proyek MSBuild Umum, dan Properti Khusus.
Properti sering digunakan bersama dengan kondisi. Sebagian besar elemen MSBuild mendukung atribut Condition , yang memungkinkan Anda menentukan kriteria di mana MSBuild harus mengevaluasi elemen . Misalnya, pertimbangkan definisi properti ini:
<PropertyGroup>
<OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\</OutputRoot>
...
</PropertyGroup>
Ketika MSBuild memproses definisi properti ini, MSBuild pertama-tama memeriksa apakah nilai properti $(OutputRoot) tersedia. Jika nilai properti kosong—dengan kata lain, pengguna belum memberikan nilai untuk properti ini—kondisi mengevaluasi ke true dan nilai properti diatur ke .. \Terbitkan\Keluar. Jika pengguna telah memberikan nilai untuk properti ini, kondisi mengevaluasi ke false dan nilai properti statis tidak digunakan.
Untuk informasi selengkapnya tentang berbagai cara di mana Anda dapat menentukan kondisi, lihat Kondisi MSBuild.
Item dan Grup Item
Salah satu peran penting dari file proyek adalah menentukan input ke proses build. Biasanya, input ini adalah file—file kode, file konfigurasi, file perintah, dan file lain yang perlu Anda proses atau salin sebagai bagian dari proses build. Dalam skema proyek MSBuild, input ini diwakili oleh elemen Item . Dalam file proyek, item harus ditentukan dalam elemen ItemGroup . Sama seperti elemen Properti , Anda dapat memberi nama elemen Item sesuka Anda. Namun, Anda harus menentukan atribut Sertakan untuk mengidentifikasi file atau wildcard yang diwakili item.
<ItemGroup>
<ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/>
</ItemGroup>
Dengan menentukan beberapa elemen Item dengan nama yang sama, Anda secara efektif membuat daftar sumber daya bernama. Cara yang baik untuk melihat tindakan ini adalah dengan melihat ke dalam salah satu file proyek yang dibuat Visual Studio. Misalnya, file ContactManager.Mvc.csproj dalam solusi sampel mencakup banyak grup item, masing-masing dengan beberapa elemen Item bernama identik.
<ItemGroup>
<Reference Include="Microsoft.CSharp" />
<Reference Include="System.Runtime.Serialization" />
<Reference Include="System.ServiceModel" />
...
</ItemGroup>
<ItemGroup>
<Compile Include="Controllers\AccountController.cs" />
<Compile Include="Controllers\ContactsController.cs" />
<Compile Include="Controllers\HomeController.cs" />
...
</ItemGroup>
<ItemGroup>
<Content Include="Content\Custom.css" />
<Content Include="CreateDatabase.sql" />
<Content Include="DropDatabase.sql" />
...
</ItemGroup>
Dengan cara ini, file proyek menginstruksikan MSBuild untuk membuat daftar file yang perlu diproses dengan cara yang sama—daftar Referensi menyertakan rakitan yang harus diberlakukan untuk build yang berhasil, daftar Kompilasi menyertakan file kode yang harus dikompilasi, dan daftar Konten menyertakan sumber daya yang harus disalin tanpa diubah. Kita akan melihat bagaimana proses build mereferensikan dan menggunakan item ini nanti dalam topik ini.
Elemen item juga dapat menyertakan elemen turunan ItemMetadata . Ini adalah pasangan kunci-nilai yang ditentukan pengguna dan pada dasarnya mewakili properti yang khusus untuk item tersebut. Misalnya, banyak elemen item Kompilasi dalam file proyek termasuk elemen anak DependentUpon .
<Compile Include="Global.asax.cs">
<DependentUpon>Global.asax</DependentUpon>
</Compile>
Catatan
Selain metadata item yang dibuat pengguna, semua item diberi berbagai metadata umum pada pembuatan. Untuk informasi selengkapnya, lihat Metadata Item Terkenal.
Anda dapat membuat elemen ItemGroup dalam elemen Project tingkat akar atau dalam elemen Target tertentu. Elemen ItemGroup juga mendukung atribut Condition , yang memungkinkan Anda menyesuaikan input dengan proses build sesuai dengan kondisi seperti konfigurasi atau platform proyek.
Target dan Tugas
Dalam skema MSBuild, elemen Tugas mewakili instruksi build individu (atau tugas). MSBuild mencakup banyak tugas yang telah ditentukan sebelumnya. Contohnya:
- Tugas Salin menyalin file ke lokasi baru.
- Tugas Csc memanggil pengkompilasi Visual C#.
- Tugas Vbc memanggil pengkompilasi Visual Basic.
- Tugas Exec menjalankan program tertentu.
- Tugas Pesan menulis pesan ke pencatat.
Catatan
Untuk detail lengkap tugas yang tersedia di luar kotak, lihat Referensi Tugas MSBuild. Untuk informasi selengkapnya tentang tugas, termasuk cara membuat tugas kustom Anda sendiri, lihat Tugas MSBuild.
Tugas harus selalu dimuat dalam elemen Target . Elemen Target adalah sekumpulan satu atau beberapa tugas yang dijalankan secara berurutan, dan file proyek dapat berisi beberapa target. Saat Anda ingin menjalankan tugas, atau sekumpulan tugas, Anda memanggil target yang berisi tugas tersebut. Misalnya, Anda memiliki file proyek sederhana yang mencatat pesan.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Anda dapat memanggil target dari baris perintah, dengan menggunakan sakelar /t untuk menentukan target.
msbuild.exe Publish.proj /t:LogMessage
Atau, Anda dapat menambahkan atribut DefaultTargets ke elemen Project , untuk menentukan target yang ingin Anda panggil.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
DefaultTargets="FullPublish">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Dalam hal ini, Anda tidak perlu menentukan target dari baris perintah. Anda cukup menentukan file proyek, dan MSBuild akan memanggil target FullPublish untuk Anda.
msbuild.exe Publish.proj
Target dan tugas dapat menyertakan atribut Kondisi . Dengan demikian, Anda dapat memilih untuk menghilangkan seluruh target atau tugas individual jika kondisi tertentu terpenuhi.
Secara umum, saat Anda membuat tugas dan target yang berguna, Anda harus merujuk ke properti dan item yang telah Anda tentukan di tempat lain dalam file proyek:
- Untuk menggunakan nilai properti, ketik $(PropertyName), di mana PropertyName adalah nama elemen Properti atau nama parameter.
- Untuk menggunakan item, ketik @(ItemName), di mana ItemName adalah nama elemen Item .
Catatan
Ingatlah bahwa jika Anda membuat beberapa item dengan nama yang sama, Anda sedang membuat daftar. Sebaliknya, jika Anda membuat beberapa properti dengan nama yang sama, nilai properti terakhir yang Anda berikan akan menimpa properti sebelumnya dengan nama yang sama—properti hanya dapat berisi satu nilai.
Misalnya, dalam file Publish.proj dalam solusi sampel, lihat target BuildProjects .
<Target Name="BuildProjects" Condition=" '$(BuildingInTeamBuild)'!='true' ">
<MSBuild Projects="@(ProjectsToBuild)"
Properties="OutDir=$(OutputRoot);
Configuration=$(Configuration);
DeployOnBuild=true;
DeployTarget=Package"
Targets="Build" />
</Target>
Dalam sampel ini, Anda dapat mengamati poin-poin utama ini:
Jika parameter BuildingInTeamBuild ditentukan dan memiliki nilai true, tidak ada tugas dalam target ini yang akan dijalankan.
Target berisi satu instans tugas MSBuild . Tugas ini memungkinkan Anda membangun proyek MSBuild lainnya.
Item ProjectsToBuild diteruskan ke tugas. Item ini dapat mewakili daftar file proyek atau solusi, semuanya ditentukan oleh elemen item ProjectsToBuild dalam grup item. Dalam hal ini, item ProjectsToBuild mengacu pada satu file solusi.
<ItemGroup> <ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/> </ItemGroup>Nilai properti yang diteruskan ke tugas MSBuild menyertakan parameter bernama OutputRoot and Configuration. Ini diatur ke nilai parameter jika disediakan, atau nilai properti statis jika tidak.
<PropertyGroup> ... <Configuration Condition=" '$(Configuration)'=='' ">Release </Configuration> <OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\ </OutputRoot> ... </PropertyGroup>
Anda juga dapat melihat bahwa tugas MSBuild memanggil target bernama Build. Ini adalah salah satu dari beberapa target bawaan yang banyak digunakan dalam file proyek Visual Studio dan tersedia untuk Anda dalam file proyek kustom Anda, seperti Build, Clean, Rebuild, dan Publish. Anda akan mempelajari selengkapnya tentang menggunakan target dan tugas untuk mengontrol proses build, dan tentang tugas MSBuild khususnya, nanti dalam topik ini.
Catatan
Untuk informasi selengkapnya tentang target, lihat Target MSBuild.
Memisahkan File Proyek untuk Mendukung Beberapa Lingkungan
Misalkan Anda ingin dapat menyebarkan solusi ke beberapa lingkungan, seperti server pengujian, platform penahapan, dan lingkungan produksi. Konfigurasi dapat bervariasi secara substansial antara lingkungan ini—bukan hanya dalam hal nama server, string koneksi, dan sebagainya, tetapi juga berpotensi dalam hal kredensial, pengaturan keamanan, dan banyak faktor lainnya. Jika Anda perlu melakukan ini secara teratur, tidak terlalu mudah untuk mengedit beberapa properti dalam file proyek Anda setiap kali Anda mengalihkan lingkungan target. Juga bukan solusi yang ideal untuk mengharuskan daftar nilai properti yang tidak ada habisnya untuk disediakan untuk proses build.
Untungnya ada alternatif. MSBuild memungkinkan Anda membagi konfigurasi build di beberapa file proyek. Untuk melihat cara kerjanya, dalam solusi sampel, perhatikan bahwa ada dua file proyek kustom:
- Publish.proj, yang berisi properti, item, dan target yang umum untuk semua lingkungan.
- Env-Dev.proj, yang berisi properti yang khusus untuk lingkungan pengembang.
Sekarang perhatikan bahwa file Publish.proj menyertakan elemen Impor , tepat di bawah tag Proyek pembuka.
<Import Project="$(TargetEnvPropsFile)"/>
Elemen Impor digunakan untuk mengimpor konten file proyek MSBuild lain ke dalam file proyek MSBuild saat ini. Dalam hal ini, parameter TargetEnvPropsFile menyediakan nama file file proyek yang ingin Anda impor. Anda dapat memberikan nilai untuk parameter ini saat menjalankan MSBuild.
msbuild.exe Publish.proj /p:TargetEnvPropsFile=EnvConfig\Env-Dev.proj
Ini secara efektif menggabungkan konten dari dua file ke dalam satu file proyek. Dengan menggunakan pendekatan ini, Anda dapat membuat satu file proyek yang berisi konfigurasi build universal dan beberapa file proyek tambahan yang berisi properti khusus lingkungan. Akibatnya, hanya menjalankan perintah dengan nilai parameter yang berbeda memungkinkan Anda menyebarkan solusi Anda ke lingkungan yang berbeda.
Memisahkan file proyek Anda dengan cara ini adalah praktik yang baik untuk diikuti. Ini memungkinkan pengembang untuk menyebarkan ke beberapa lingkungan dengan menjalankan satu perintah, sambil menghindari duplikasi properti build universal di beberapa file proyek.
Catatan
Untuk panduan tentang cara menyesuaikan file proyek khusus lingkungan untuk lingkungan server Anda sendiri, lihat Mengonfigurasi Properti Penyebaran untuk Lingkungan Target.
Kesimpulan
Topik ini memberikan pengenalan umum untuk file proyek MSBuild dan menjelaskan bagaimana Anda dapat membuat file proyek kustom Anda sendiri untuk mengontrol proses build. Ini juga memperkenalkan konsep memisahkan file proyek menjadi instruksi build universal dan properti build khusus lingkungan, untuk memudahkan membangun dan menyebarkan proyek ke beberapa tujuan.
Topik berikutnya, Memahami Proses Build, memberikan lebih banyak wawasan tentang bagaimana Anda dapat menggunakan file proyek untuk mengontrol pembangunan dan penyebaran dengan memanah Anda melalui penyebaran solusi dengan tingkat kompleksitas yang realistis.
Bacaan lebih lanjut
Untuk pengenalan yang lebih mendalam tentang file proyek dan WPP, lihat Di dalam Microsoft Build Engine: Menggunakan MSBuild dan Team Foundation Build oleh Sayed Ibrahim Hashimi dan William Bartholomew, ISBN: 978-0-7356-4524-0.
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk