Opsi pengkompilasi C# untuk aturan fitur bahasa

Opsi berikut mengontrol cara pengompilasi menafsirkan fitur bahasa. Sintaksis MSBuild baru ditampilkan dalam Huruf tebal. Sintaks csc.exe yang lebih lama ditampilkan dalam huruf code style.

  • CheckForOverflowUnderflow / -checked: Menghasilkan pemeriksaan luapan.
  • AllowUnsafeBlocks / -unsafe: Izinkan unsafe kode.
  • DefineConstants / -define: Tentukan simbol kompilasi bersyarat.
  • LangVersion / -langversion: Menentukan versi bahasa, sepertidefault (versi utama yang terbaru), atau latest (versi terbaru, termasuk versi minor).
  • Nullable / -nullable: Mengaktifkan konteks yang dapat diubah ke null atau peringatan yang dapat diubah ke null.

Catatan

Untuk informasi selengkapnya tentang mengonfigurasi opsi ini untuk proyek Anda, lihat Opsi pengkompilasi.

CheckForOverflowUnderflow

Opsi CheckForOverflowUnderflow mengontrol konteks pemeriksaan luapan default yang menentukan perilaku program jika luapan aritmatika bilangan bulat.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Ketika CheckForOverflowUnderflow adalah true, konteks default adalah konteks yang diperiksa dan pemeriksaan luapan diaktifkan. Ketika CheckForOverflowUnderflow adalah false, konteks default adalah konteks yang tidak dicentang. Nilai default untuk opsi ini adalah false, yang berarti pemeriksaan luapan dinonaktifkan.

Anda juga dapat secara eksplisit mengontrol konteks pemeriksaan luapan untuk bagian kode Anda dengan menggunakan checked pernyataan dan unchecked .

Untuk informasi tentang bagaimana konteks pemeriksaan luapan memengaruhi operasi dan operasi apa yang dipengaruhinya, lihat artikel tentang checked dan unchecked pernyataan.

AllowUnsafeBlocks

Opsi pengompilasi AllowUnsafeBlocks memungkinkan kode yang menggunakan kata kunci tak terkelola untuk dikompilasi. Nilai default untuk opsi ini adalah false, yang berarti kode tidak aman tidak diizinkan.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Untuk informasi selengkapnya tentang kode tak terkelola, lihat Kode Tak Terkelola dan Penunjuk.

Mengaktifkan aturan keamanan memori yang diperbarui

Aturan keamanan memori yang diperbarui adalah fitur pratinjau di C# 15 dan .NET 11. Mereka menggunakan dua pengaturan kompilator independen:

  • Versi preview bahasa memungkinkan sintaksis baru dan relaksasi pointer.
  • Fitur updated-memory-safety-rules pengkompilasi memungkinkan aturan yang diperbarui, termasuk kewajiban penelepon yang memerlukan tidak aman , dan menyebabkan kompilator merekam pilihan dalam perakitan dengan MemorySafetyRulesAttribute atribut .

Properti SDK yang stabil di masa mendatang, MemorySafetyRules, direncanakan sebagai tingkat aktivasi ketiga saat fitur keluar dari pratinjau (misalnya, <MemorySafetyRules>2</MemorySafetyRules>), tetapi properti tersebut belum diimplementasikan.

Untuk proyek, gunakan kedua pengaturan:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>

Untuk program berbasis file, tambahkan arahan yang setara:

#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview

Properti AllowUnsafeBlocks independen. Ini mengontrol apakah sumber dapat menggunakan unsafe kata kunci. Proyek dapat mengaktifkan aturan yang diperbarui tanpa mengizinkan kode yang tidak aman, dalam hal ini menerima kesalahan saat memanggil API yang memerlukan API yang tidak aman.

Apakah satu assembly memberlakukan aturan yang diperbarui terhadap aturan lain tergantung pada sisi mana yang ikut serta:

  • Penelepon model yang diperbarui, penelepon model yang diperbarui: Penanda callee unsafe melakukan perjalanan melalui metadata. Penelepon membungkus setiap panggilan ke anggota yang memerlukan tidak aman dalam blok unsafe .
  • Pemanggil model yang diperbarui, penerima panggilan model asli: Mode kompatibilitas memperlakukan anggota penerima panggilan dengan jenis penunjuk dalam tanda tangannya sebagai memerlukan-tidak aman, sehingga situs panggilan memerlukan blok penutup unsafe . Mode ini membuat API berbasis pointer tidak kehilangan persyaratannya unsafe secara diam-diam.
  • Penelepon model asli, penelepon model yang diperbarui: Aturan penunjuk asli masih berlaku. Anggota yang memerlukan tidak aman yang tidak memiliki jenis penunjuk dalam tanda tangannya menjadi dapat dipanggil dari kode aman, karena pemanggil model asli tidak dapat membaca penanda baru.

DefineConstants

Opsi DefineConstants menentukan simbol di semua file kode sumber program Anda.

<DefineConstants>name;name2</DefineConstants>

Opsi ini menentukan nama dari satu atau beberapa simbol yang ingin Anda tentukan. Opsi DefineConstants memiliki pengaruh yang sama dengan direktif praprosesor #define kecuali apabila opsi pengompilasi berlaku untuk semua file dalam proyek. Simbol tetap ditentukan dalam file sumber hingga direktif #undef dalam file sumber menghapus penentuan tersebut. Saat Anda menggunakan opsi -define, direktif #undef dalam satu file tidak berpengaruh pada file kode sumber lain dalam proyek. Anda dapat menggunakan simbol yang dibuat oleh opsi ini dengan #if, #else, #elif, dan #endif untuk mengompilasi file sumber secara kondisional. Pengompilasi C# sendiri tidak menentukan simbol atau makro yang dapat Anda gunakan dalam kode sumber; semua penentuan simbol harus dilakukan oleh pengguna.

Catatan

Direktif C# #define tidak mengizinkan simbol memiliki nilai, seperti dalam bahasa seperti C++. Misalnya, #define tidak dapat membuat makro atau menentukan konstanta. Jika Anda perlu menentukan konstanta, gunakan variabel enum. Jika Anda ingin membuat makro C++-style, pertimbangkan alternatif seperti generik. Karena makro terkenal rawan kesalahan, C# akan menolak penggunaannya dan memberikan alternatif yang lebih aman.

LangVersion

Versi bahasa default untuk pengkompilasi C# bergantung pada kerangka kerja target untuk aplikasi Anda dan versi SDK atau Visual Studio yang diinstal. Aturan tersebut ditentukan dalam penerapan versi bahasa C#.

Peringatan

Jangan atur elemen ke LangVersionlatest. Pengaturan berarti latest pengkompilasi yang diinstal menggunakan versi terbarunya. Versi tersebut dapat berubah dari komputer ke mesin, membuat build tidak dapat diandalkan. Selain itu, ini memungkinkan fitur bahasa yang mungkin memerlukan fitur runtime atau pustaka yang tidak disertakan dalam SDK saat ini.

Opsi LangVersion menyebabkan pengkompilasi hanya menerima sintaks yang disertakan dalam spesifikasi bahasa C# yang ditentukan, misalnya:

<LangVersion>9.0</LangVersion>

Beberapa fitur pratinjau memerlukan keikutsertaan terpisah selain <LangVersion>preview</LangVersion>. Misalnya, aturan keamanan memori C# 15 yang diperbarui menggunakan updated-memory-safety-rules fitur pengkompilasi. Untuk informasi selengkapnya, lihat Mengaktifkan aturan keamanan memori yang diperbarui.

Nilai berikut ini valid:

Nilai Makna
preview Kompilator menerima semua sintaks bahasa yang valid dari versi pratinjau terbaru.
latest Kompilator menerima sintaks dari versi kompilator terbaru yang dirilis (termasuk versi minor).
latestMajor
atau default		 Kompilator menerima sintaks dari versi utama kompilator terbaru yang dirilis.
15.0 Pengkompilasi hanya menerima sintaksis yang disertakan dalam C# 15 atau yang lebih rendah.
14.0 Pengkompilasi hanya menerima sintaksis yang disertakan dalam C# 14 atau yang lebih rendah.
13.0 Pengkompilasi hanya menerima sintaksis yang disertakan dalam C# 13 atau yang lebih rendah.
12.0 Pengkompilasi hanya menerima sintaksis yang disertakan dalam C# 12 atau yang lebih rendah.
11.0 Pengkompilasi hanya menerima sintaksis yang disertakan dalam C# 11 atau yang lebih rendah.
10.0 Kompilator hanya menerima sintaks yang disertakan dalam C# 10 atau lebih rendah.
9.0 Kompilator hanya menerima sintaks yang disertakan dalam C# 9 atau lebih rendah.
8.0 Kompilator hanya menerima sintaks yang disertakan dalam C# 8.0 atau lebih rendah.
7.3 Kompilator hanya menerima sintaks yang disertakan dalam C# 7.3 atau lebih rendah.
7.2 Kompilator hanya menerima sintaks yang disertakan dalam C# 7.2 atau lebih rendah.
7.1 Kompilator hanya menerima sintaks yang disertakan dalam C# 7.1 atau lebih rendah.
7 Kompilator hanya menerima sintaks yang disertakan dalam C# 7.0 atau lebih rendah.
6 Kompilator hanya menerima sintaks yang disertakan dalam C# 6.0 atau lebih rendah.
5 Kompilator hanya menerima sintaks yang disertakan dalam C# 5.0 atau lebih rendah.
4 Kompilator hanya menerima sintaks yang disertakan dalam C# 4.0 atau lebih rendah.
3 Kompilator hanya menerima sintaks yang disertakan dalam C# 3.0 atau lebih rendah.
ISO-2
atau 2		 Kompilator hanya menerima sintaks yang disertakan dalam ISO/IEC 23270:2006 C# (2.0).
ISO-1
atau 1		 Kompilator hanya menerima sintaks yang disertakan dalam ISO/IEC 23270:2003 C# (1.0/1.2).

Pertimbangan

  • Untuk memastikan bahwa proyek Anda menggunakan versi kompilator default yang direkomendasikan untuk kerangka kerja target Anda, jangan gunakan opsi LangVersion . Perbarui kerangka kerja target untuk mengakses fitur bahasa yang lebih baru.

  • Menentukan LangVersion dengan nilai berbeda dari menghilangkan default. Menentukan default menggunakan versi terbaru bahasa yang didukung pengkompilasi, tanpa memperhitungkan kerangka kerja target. Misalnya, membangun proyek yang menargetkan .NET 6 dari Visual Studio versi 17.6 menggunakan C# 10 jika LangVersion tidak ditentukan, tetapi menggunakan C# 11 jika LangVersion diatur ke default.

  • Opsi pengkompilasi LangVersion tidak memengaruhi metadata yang direferensikan oleh aplikasi C# Anda.

  • Karena setiap versi pengompilasi C# berisi ekstensi untuk spesifikasi bahasa, LangVersion tidak memberi Anda fungsionalitas yang setara dengan versi pengompilasi yang lebih lama.

  • Meskipun pembaruan versi C# umumnya bertepatan dengan rilis .NET utama, sintaks dan fitur baru tidak selalu terkait dengan versi kerangka kerja tertentu tersebut. Setiap fitur tertentu memiliki API .NET minimum sendiri atau persyaratan runtime bahasa umum yang mungkin memungkinkannya berjalan pada kerangka kerja tingkat bawah dengan menyertakan paket NuGet atau pustaka lainnya.

  • Terlepas dari pengaturan LangVersion mana yang Anda gunakan, gunakan versi runtime bahasa umum saat ini untuk membuat .exe atau .dll Anda. Satu pengecualian adalah perakitan teman dan ModuleAssemblyName, yang bekerja di bawah -langversion:ISO-1.

Untuk cara lain dalam menentukan versi bahasa C#, lihat penerapan versi bahasa C#.

Untuk informasi tentang cara mengatur opsi pengompilasi ini secara terprogram, lihat LanguageVersion.

Spesifikasi bahasa C#

Versi Tautan Deskripsi
C# 8.0 dan yang lebih baru unduh PDF Spesifikasi Bahasa C# Versi 7: .NET Foundation
C# 7.3 unduh PDF Ecma-334 Standar Edisi ke-7
C# 6.0 unduh PDF Ecma-334 Standar Edisi ke-6
C# 5.0 Unduh PDF ECMA-334 Standar Edisi ke-5
C# 3.0 Unduh DOC Spesifikasi Bahasa C# Versi 3.0: Microsoft Corporation
C# 2.0 Unduh PDF ECMA-334 Standar Edisi ke-4
C# 1.2 Unduh DOC ECMA-334 2Nd Edition Standar
C# 1.0 Unduh DOC ECMA-334 1st Edition Standar

Versi SDK minimum diperlukan untuk mendukung semua fitur bahasa

Tabel berikut mencantumkan versi minimum SDK dengan pengompilasi C# yang mendukung versi bahasa yang sesuai:

Versi C# Versi SDK minimum
C# 12 Microsoft Visual Studio/Build Tools 2022 versi 17.8, atau .NET 8 SDK
C# 11 Microsoft Visual Studio/Build Tools 2022 versi 17.4, atau .NET 7 SDK
C# 10 Microsoft Visual Studio/Build Tools 2022, atau .NET 6 SDK
C# 9.0 Microsoft Visual Studio/Build Tools 2019 versi 16.8, atau .NET 5 SDK
C# 8.0 Microsoft Visual Studio/Build Tools 2019, versi 16.3, atau .NET Core 3.0 SDK
C# 7.3 Microsoft Visual Studio/Build Tools 2017, versi 15.7
C# 7.2 Microsoft Visual Studio/Build Tools 2017, versi 15.5
C# 7.1 Microsoft Visual Studio/Build Tools 2017, versi 15.3
C# 7.0 Microsoft Visual Studio/Build Tools 2017
C# 6 Microsoft Visual Studio/Build Tools 2015
C# 5 Microsoft Visual Studio/Build Tools 2012 atau bundel pengompilasi .NET Framework 4.5
C# 4 Microsoft Visual Studio/Build Tools 2010 atau bundel pengompilasi .NET Framework 4.0
C# 3 Microsoft Visual Studio/Build Tools 2008 atau bundel pengompilasi .NET Framework 3.5
C# 2 Microsoft Visual Studio/Build Tools 2005 atau bundel pengompilasi .NET Framework 2.0
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 atau bundel pengompilasi .NET Framework 1.0

Dapat diubah ke null

Gunakan opsi Nullable untuk menentukan konteks nullable. Atur dalam konfigurasi proyek dengan menggunakan <Nullable> tag:

<Nullable>enable</Nullable>

Argumen harus merupakan salah satu dari enable, disable, warnings, atau annotations. Argumen enable mengaktifkan konteks nullable. Argumen disable menonaktifkan konteks nullable. Argumen warnings mengaktifkan konteks peringatan nullable. Argumen annotations mengaktifkan konteks anotasi yang dapat diubah ke null. Untuk informasi selengkapnya tentang nilai-nilai ini, lihat Konteks yang dapat diubah ke null. Untuk mempelajari selengkapnya tentang mengaktifkan jenis referensi nullable di basis kode yang ada, lihat strategi migrasi nullable.

Catatan

Jika Anda tidak menetapkan nilai, nilai defaultnya adalah disable. Namun, .NET 6 dan templat yang lebih baru mengatur nilai Nullable ke enable secara default.

Analisis alur menyimpulkan nullability variabel dalam kode yang dapat dieksekusi. Kemampuan dapat diubah ke null yang disimpulkan dari variabel tidak bergantung pada pernyataan kemampuan dapat diubah ke null variabel tersebut. Pengkompilasi menganalisis panggilan metode bahkan ketika panggilan dihilangkan secara kondisional dari output yang dikompilasi. Misalnya, pengkompilasi masih menganalisis panggilan ke untuk Debug.Assert nullability meskipun panggilan bersyarkat dan tidak dikompilasi ke dalam build rilis.

Pemanggilan metode yang dianotasi dengan atribut berikut juga memengaruhi analisis alur:

Penting

Konteks nullable global tidak berlaku untuk file kode yang dihasilkan. Terlepas dari pengaturan ini, konteks yang dapat diubah ke null akan dinonaktifkan untuk file sumber apa pun yang ditandai sebagai dihasilkan. File ditandai sebagai dihasilkan dengan salah satu cara berikut:

  1. Dalam .editorconfig, tentukan generated_code = true di bagian yang berlaku untuk file tersebut.
  2. Sertakan <auto-generated> atau <auto-generated/> dalam komentar di bagian atas file. Anda dapat menempatkannya di baris mana pun di komentar, tetapi blok komentar harus menjadi elemen pertama dalam file.
  3. Memulai nama file dengan TemporaryGeneratedFile_
  4. Mengakhiri nama file dengan .designer.cs, .generated.cs, .g.cs, atau .g.i.cs.

Generator dapat ikut serta dengan menggunakan #nullable direktif pra-prosesor.

  • Last updated on