Opsi Pengompilasi 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
: Mengizinkan kode 'tak terkelola'. - DefineConstants /
-define
: Menentukan simbol kompilasi kondisional. - LangVersion /
-langversion
: Menentukan versi bahasa, sepertidefault
(versi utama yang terbaru), ataulatest
(versi terbaru, termasuk versi minor). - Nullable /
-nullable
: Mengaktifkan konteks yang dapat diubah ke null atau peringatan yang dapat diubah ke null.
Catatan
Lihat Opsi pengkompilasi untuk informasi selengkapnya tentang mengonfigurasi opsi ini untuk proyek Anda.
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; jika tidak, konteks default adalah konteks yang tidak dicentang. Nilai default untuk opsi ini adalah false
, yaitu 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 terpengaruh, 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.
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 memungkinkan simbol untuk diberikan nilai, seperti dalam bahasa pemrogram seperti C++. Misalnya, #define
tidak dapat digunakan untuk membuat makro atau untuk menentukan konstanta. Jika Anda perlu menentukan konstanta, gunakan variabel enum
. Jika Anda ingin membuat makro gaya C++, 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
Mengatur elemen ke LangVersion
latest
tidak disarankan. Pengaturan berarti latest
pengkompilasi yang diinstal menggunakan versi terbarunya. Itu dapat berubah dari mesin 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>
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. |
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 . Anda dapat memperbarui kerangka kerja target untuk mengakses fitur bahasa pemrogram yang lebih baru.
Menentukan LangVersion dengan
default
nilai berbeda dari menghilangkan opsi LangVersion. Menentukandefault
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 kedefault
.Metadata yang dirujuk oleh aplikasi C# Anda tidak tunduk pada opsi pengompilasi LangVersion.
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 memungkinkannya berjalan pada kerangka kerja downlevel 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
Opsi Dapat Diubah ke Null memungkinkan Anda menentukan konteks dapat diubah ke null. Hal ini dapat diatur 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 yang dapat diubah ke null. Menentukan disable
akan menonaktifkan konteks yang dapat diubah ke null. Saat Anda menentukan warnings
argumen, konteks peringatan nullable diaktifkan. Saat Anda menentukan annotations
argumen, konteks anotasi yang dapat diubah ke null diaktifkan. Nilai dijelaskan dan dijelaskan dalam artikel tentang konteks Nullable. Anda dapat mempelajari lebih lanjut tentang tugas yang terlibat dalam mengaktifkan jenis referensi nullable di basis kode yang ada di artikel kami tentang strategi migrasi nullable.
Catatan
Ketika tidak ada nilai yang ditetapkan, disable
nilai default akan diterapkan, tetapi templat .NET 6 secara default disediakan dengan nilai Dapat Diubah ke Null diatur ke enable
.
Analisis alur digunakan untuk menyimpulkan kemampuan yang dapat diubah ke null dari variabel-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. Panggilan metode dianalisis bahkan ketika panggilan tersebut dihilangkan secara kondisional. Misalnya, Debug.Assert dalam mode rilis.
Pemanggilan metode yang dianotasikan dengan atribut berikut juga akan memengaruhi analisis alur:
- Prakondisi sederhana: AllowNullAttribute dan DisallowNullAttribute
- Pascakondisi sederhana: MaybeNullAttribute dan NotNullAttribute
- Pascakondisi kondisional: MaybeNullWhenAttribute dan NotNullWhenAttribute
- DoesNotReturnIfAttribute (misalnya,
DoesNotReturnIf(false)
untuk Debug.Assert) dan DoesNotReturnAttribute - NotNullIfNotNullAttribute
- Pascakondisi anggota: MemberNotNullAttribute(String) dan MemberNotNullAttribute(String[])
Penting
Konteks global yang dapat diubah ke null 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. Ada empat cara file ditandai sebagai dihasilkan:
- Dalam .editorconfig, tentukan
generated_code = true
di bagian yang berlaku untuk file tersebut. - Memasukkan
<auto-generated>
atau<auto-generated/>
pada komentar di bagian atas file. Ini bisa berada di baris mana pun dalam komentar itu, tetapi blok komentar harus menjadi elemen pertama dalam file. - Memulai nama file dengan TemporaryGeneratedFile_
- Mengakhiri nama file dengan .designer.cs, .generated.cs, .g.cs, atau .g.i.cs.
Generator dapat ikut serta dengan menggunakan direktif pra-prosesor #nullable
.