Opsi Pengompilasi C# yang mengontrol pembuatan kode

Opsi berikut mengontrol pembuatan kode oleh pengompilasi. Sintaksis MSBuild baru ditampilkan dalam cetak tebal. Sintaks csc.exe yang lebih lama ditampilkan dalam huruf code style.

• DebugType / -debug: Mengeluarkan (atau tidak mengeluarkan) informasi debug.
• Optimize / -optimize: Mengaktifkan pengoptimalan.
• Deterministic / -deterministic: Menghasilkan output setara byte-for-byte dari sumber input yang sama.
• ProduceOnlyReferenceAssembly / -refonly: Menghasilkan rakitan referensi, bukan rakitan lengkap, sebagai output utama.

Catatan

Lihat Opsi pengkompilasi untuk informasi selengkapnya tentang mengonfigurasi opsi ini untuk proyek Anda.

DebugType

Opsi DebugType menyebabkan pengompilasi menghasilkan informasi penelusuran kesalahan dan menempatkannya dalam file atau file output. Nilai default adalah portable untuk konfigurasi build Debug dan Rilis, yang berarti file PDB dihasilkan secara default untuk semua konfigurasi.

<DebugType>pdbonly</DebugType>

Untuk semua versi pengompilasi yang dimulai dengan C# 6.0, tidak ada perbedaan antara pdbonly dan full. Pilih pdbonly. Untuk mengubah lokasi file .pdb, lihat PdbFile.

Nilai berikut ini valid:

Nilai	Makna
full	Keluarkan informasi penelusuran kesalahan ke file .pdb menggunakan format default untuk platform saat ini: Windows: File pdb untuk Windows. Linux/macOS: File PDB Portabel.
pdbonly	Sama seperti full. Lihat catatan di bawah ini untuk informasi selengkapnya.
portable	Keluarkan informasi penelusuran kesalahan ke file .pdb menggunakan format PDB Portabel lintas platform.
embedded	Keluarkan informasi debugging ke dalam .dll/.exe itu sendiri (file .pdb tidak dibuat) menggunakan format Portable PDB.
none	Jangan menghasilkan file PDB.

Penting

Informasi berikut hanya berlaku untuk pengompilasi dengan versi yang lebih lama dari C# 6.0. Nilai elemen ini dapat berupa full atau pdbonly. Argumen full, yang berlaku jika Anda tidak menentukan pdbonly, memungkinkan pelampiran debugger ke program yang sedang berjalan. Penentuan pdbonly memungkinkan penelusuran kesalahan kode sumber saat program dimulai di debugger, tetapi hanya akan menampilkan kode rakitan ketika program yang sedang berjalan dilampirkan ke debugger. Gunakan opsi ini untuk membuat versi debug. Jika Anda menggunakan Full, ketahuilah bahwa ada beberapa dampak pada kecepatan dan ukuran kode yang dioptimalkan JIT dan dampak kecil pada kualitas kode dengan full. Kami menyarankan pdbonly atau tanpa PDB untuk menghasilkan kode rilis. Salah satu perbedaan antara pdbonly dan full adalah bahwa dengan full pengompilasi mengeluarkan DebuggableAttribute, yang digunakan untuk memberi tahu pengompilasi JIT bahwa informasi debug tersedia. Oleh karena itu, Anda akan mendapatkan kesalahan jika kode Anda berisi DebuggableAttribute yang diatur ke false jika Anda menggunakan full. Untuk informasi selengkapnya tentang cara mengonfigurasi performa debug aplikasi, lihat Membuat Gambar Lebih Mudah Di-debug.

Menonaktifkan pembuatan PDB untuk build Rilis

Untuk menekan pembuatan file PDB untuk build Rilis sambil menyimpannya untuk build Debug, tambahkan properti berikut ke file proyek Anda:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <DebugType>none</DebugType>
</PropertyGroup>

Anda juga dapat mengatur DebugSymbols ke false untuk kompilasi rilis:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <DebugSymbols>false</DebugSymbols>
</PropertyGroup>

Catatan

Di .NET 8 dan versi yang lebih baru, mengatur DebugSymbols menjadi false seharusnya menekan pembuatan PDB sesuai dengan dokumentasi perubahan besar. Namun, cara yang paling dapat diandalkan untuk menonaktifkan pembuatan PDB adalah dengan secara eksplisit diatur DebugType ke none.

Optimalkan

Opsi Optimize mengaktifkan atau menonaktifkan pengoptimalan yang dilakukan oleh pengompilasi untuk membuat file output Anda lebih kecil, lebih cepat, dan lebih efisien. Opsi Optimize diaktifkan secara default untuk konfigurasi build Rilis. Ini nonaktif secara default untuk Debug dan konfigurasi build lainnya.

<Optimize>true</Optimize>

Anda menetapkan opsi Optimize dari halaman properti build untuk proyek Anda di Visual Studio.

Optimize juga memberi tahu Common Language Runtime untuk mengoptimalkan kode pada waktu jalan. Secara default, pengoptimalan dinonaktifkan. Tentukan Optimize+ untuk mengaktifkan pengoptimalan. Saat membuat modul yang akan digunakan oleh rakitan, gunakan pengaturan Optimize yang sama seperti yang digunakan oleh rakitan. Dimungkinkan untuk menggabungkan opsi Optimize dan Debug.

Deterministik

Menyebabkan pengompilasi menghasilkan rakitan dengan output byte demi byte yang identik pada setiap kompilasi untuk input yang identik.

<Deterministic>true</Deterministic>

Untuk proyek .NET modern, kompilasi deterministik diaktifkan secara default ( Deterministic properti default ke true). Ketika kompilasi deterministik diaktifkan, tanda waktu dan bidang MVID diganti dengan nilai yang berasal dari hash semua input kompilasi, memastikan output biner yang identik untuk input yang identik.

Ketika kompilasi deterministik dinonaktifkan (<Deterministic>false</Deterministic>), output kompilator dari set input tertentu unik, karena kompilator menambahkan tanda waktu dan MVID ( Module.ModuleVersionId. Pada dasarnya ini adalah GUID yang secara unik mengidentifikasi modul dan versi.) yang dihasilkan dari angka acak.

Anda menggunakan opsi <Deterministic> untuk menghasilkan rakitan deterministik, yang konten binernya identik di seluruh kompilasi selama input tetap sama. Pengompilasi mempertimbangkan input berikut yang memengaruhi determinisme:

• Urutan parameter baris perintah.
• Isi dari file respons .rsp pengompilasi.
• Versi yang tepat dari pengompilasi yang digunakan, dan rakitan referensinya.
• Jalur direktori saat ini.
• Konten biner dari semua file secara eksplisit diteruskan ke pengkompilasi baik secara langsung maupun tidak langsung, termasuk:
  • File sumber
  • Perakitan yang Direferensikan
  • Modul yang Direferensikan
  • Sumber
  • File kunci nama yang kuat
  • @ file respon
  • Penganalisis
  • Set aturan
  • Data Tautan Sumber yang diekstrak dari repositori (misalnya, git commit SHA, URL repositori, dll.)
  • File lain yang dapat digunakan oleh penganalisis
• Budaya saat ini (untuk bahasa di mana pesan diagnostik dan pengecualian diproduksi).
• Pengodean bawaan (atau halaman kode saat ini) jika pengodean tidak ditentukan.
• Keberadaan, ketiadaan, dan konten file pada jalur pencarian pengompilasi (ditentukan, misalnya, oleh -lib atau -recurse).
• Platform Common Language Runtime (CLR) tempat pengompilasi dijalankan.
• Nilai %LIBPATH%, yang dapat mempengaruhi pemuatan dependensi penganalisis.

Kompilasi deterministic dapat digunakan untuk menetapkan apakah suatu biner dikompilasi dari sumber terpercaya. Output deterministic dapat berguna jika sumber tersedia untuk umum. Ini juga dapat menentukan apakah ada langkah build yang bergantung pada perubahan terhadap biner yang digunakan dalam proses build.

Tetap gunakan "ProduceOnlyReferenceAssembly" untuk istilah teknis ini.

Opsi ProduceOnlyReferenceAssembly menunjukkan bahwa rakitan referensi harus berupa output dan bukan rakitan implementasi, sebagai output utama. Parameter ProduceOnlyReferenceAssembly secara diam-diam menonaktifkan output PDB, karena rakitan referensi tidak dapat dijalankan.

<ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>

Rakitan referensi adalah jenis rakitan khusus. Rakitan referensi hanya berisi jumlah minimum metadata yang diperlukan untuk mewakili permukaan API publik pustaka. Ini termasuk deklarasi untuk semua anggota yang signifikan saat merujuk assembly dalam alat pengembangan, tetapi mengecualikan semua implementasi anggota dan deklarasi anggota privat yang tidak memiliki dampak yang dapat diamati pada kontrak API-nya. Untuk informasi selengkapnya, lihat Rakitan referensi.

Opsi ProduceOnlyReferenceAssembly dan ProduceReferenceAssembly bersifat eksklusif secara mutual.