語言功能規則的 C# 編譯器選項
下列選項可控制編譯器如何解譯語言功能。 新的 MSBuild 語法會以「粗體」顯示。 較舊的 csc.exe 語法會以code style顯示。
- CheckForOverflowUnderflow /
-checked：產生溢位檢查。 - AllowUnsafeBlocks /
-unsafe：允許「unsafe」程式碼。 - DefineConstants /
-define：定義條件式編譯符號。 - LangVersion /
-langversion：指定語言版本，例如default(最新主要版本) 或latest(最新版本，包括次要版本)。 - Nullable /
-nullable：啟用可為 Null 的內容或可為 Null 的警告。
注意
如需為專案設定這些選項的詳細資訊，請參閱 [編譯器選項]。
CheckForOverflowUnderflow
CheckForOverflowUnderflow 選項會控制預設溢位檢查內容，此內容會定義整數算術溢位時的程式行為。
<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
CheckForOverflowUnderflow 為 true 時，預設內容為已檢查的內容，並啟用溢位檢查；否則，預設內容為未檢查的內容。 這個選項的預設值是 false，也就是溢位檢查已停用。
您也可以使用 checked 和 unchecked 陳述式，明確控制程式碼部分的溢位檢查內容。
如需溢位檢查內容如何影響作業和哪些作業受到影響的資訊，請參閱 checked 和 unchecked 陳述式的文章。
AllowUnsafeBlocks
AllowUnsafeBlocks 編譯器選項允許程式碼使用 unsafe 關鍵字來進行編譯。 這個選項的預設值為 false，表示不允許不安全的程式碼。
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
如需 Unsafe 程式碼的詳細資訊，請參閱 Unsafe 程式碼和指標。
DefineConstants
DefineConstants 選項會定義程式的所有原始程式碼檔案中的符號。
<DefineConstants>name;name2</DefineConstants>
這個選項會指定您要定義的一個或多個符號名稱。 DefineConstants 選項的作用與 #define 前置處理器指示詞相同，不同之處在於編譯器選項對專案中的所有檔案都有效。 直到原始程式檔中的 #undef 指示詞移除符號的定義之前，符號在原始程式檔中都會維持已定義狀態。 使用 -define 選項時，某個檔案中的 #undef 指示詞不會對專案中的其他原始程式碼檔造成影響。 您可以使用此選項建立的符號，搭配 #if、#else、#elif 和 #endif，有條件地編譯原始程式檔。 C# 編譯器本身不會定義任何您可以在原始程式碼中使用的符號或巨集；所有符號定義都必須是使用者定義。
注意
C# #define 指示詞不允許指定數值給符號，這點和 C++ 語言相同。 例如，#define 不能用來建立巨集或定義常數。 如果您需要定義常數，請使用 enum 變數。 如果您想要建立 C++ 樣式巨集，請考慮替代項目，例如泛型。 由於巨集非常可能發生錯誤，因此 C# 不允許使用巨集，而是提供較為安全的替代項目。
LangVersion
C# 編譯器的預設語言版本取決於您應用程式的目標 Framework，以及安裝的 SDK 或 Visual Studio 版本。 這些規則會以 C# 語言版本設定來定義。
警告
不建議將 LangVersion 元素設定為 latest。 此 latest 設定表示已安裝的編譯器會使用其最新版本。 這個版本可能會因電腦而異，導致組建不可靠。 此外，它所啟用的語言功能可能需要目前 SDK 中未包含的執行階段或程式庫功能。
LangVersion 選項會讓編譯器只接受指定 C# 語言規格中包含的語法，例如：
<LangVersion>9.0</LangVersion>
下列是有效值：
| 值 | 意義 |
|---|---|
preview |
編譯器會接受最新預覽版本的所有有效語言語法。 |
latest |
編譯器會接受編譯器最新已發行版本 (包括次要版本) 的語法。 |
latestMajor或 default |
編譯器會接受編譯器最新已發行主要版本的語法。 |
13.0 |
編譯器只接受 C# 13 或更低版本中所含的語法。 |
12.0 |
編譯器只接受 C# 12 或更低版本中所含的語法。 |
11.0 |
編譯器只接受 C# 11 或更低版本中所含的語法。 |
10.0 |
編譯器只接受 C# 10 或更低版本中所含的語法。 |
9.0 |
編譯器只接受 C# 9 或更低版本中所含的語法。 |
8.0 |
編譯器只會接受 C# 8.0 或更低版本中所含的語法。 |
7.3 |
編譯器只會接受 C# 7.3 或更低版本中所含的語法。 |
7.2 |
編譯器只會接受 C# 7.2 或更低版本中所含的語法。 |
7.1 |
編譯器只會接受 C# 7.1 或更低版本中所含的語法。 |
7 |
編譯器只會接受 C# 7.0 或更低版本中所含的語法。 |
6 |
編譯器只會接受 C# 6.0 或更低版本中所含的語法。 |
5 |
編譯器只會接受 C# 5.0 或更低版本中所含的語法。 |
4 |
編譯器只會接受 C# 4.0 或更低版本中所含的語法。 |
3 |
編譯器只會接受 C# 3.0 或更低版本中所含的語法。 |
ISO-2或 2 |
編譯器只接受 ISO/IEC 23270:2006 C# (2.0) 中所含的語法。 |
ISO-1或 1 |
編譯器只接受 ISO/IEC 23270:2003 C# (1.0/1.2) 中所含的語法。 |
考量
若要確保您的專案使用目標 Framework 建議的預設編譯器版本，請勿使用 LangVersion 選項。 您可以更新目標 Framework 以存取較新的語言功能。
使用
default值指定LangVersion 與省略 LangVersion 選項不同。 指定default會使用編譯器支援的最新語言版本，而不考慮目標 Framework。 例如，如果未指定 LangVersion ，則從 Visual Studio 17.6 版建置以 .NET 6 為目標的專案會使用 C# 10，但如果 LangVersion 設定為default，則會使用 C# 11。C# 應用程式所參考的中繼資料不限於 LangVersion 編譯器選項。
因為每個版本的 C# 編譯器都包含語言規格的延伸模組，所以 LangVersion 不會提供舊版編譯器的相等功能。
雖然 C# 版本更新通常會與主要 .NET 版本一致，但是新語法和功能不需要繫結至該特定基礎結構版本。 每個特定功能都有本身的最低 .NET API 或通用語言執行平台需求，可藉由包含 NuGet 套件或其他程式庫，在舊版基礎結構上執行。
不論使用的 LangVersion 設定為何，都可以使用目前版本的通用語言執行平台來建立 .exe 或 .dll。 其中一個例外狀況是 Friend 組件和 ModuleAssemblyName，這些都是在 -langversion:ISO-1 下運作。
如需其他方式來指定 C# 語言版本，請參閱 C# 語言版本設定。
如需如何以程式設計方式設定這個編譯器選項的詳細資訊，請參閱 LanguageVersion。
C# 語言規格
| 版本 | 連結 | 描述 |
|---|---|---|
| C# 8.0 與更新版本 | 下載 PDF | C# 語言規格版本 7：.NET Foundation |
| C# 7.3 | 下載 PDF | 標準 ECMA-334 第 7 版 |
| C# 6.0 | 下載 PDF | 標準 ECMA-334 第 6 版 |
| C# 5.0 | 下載 PDF | 標準 ECMA-334 第 5 版 |
| C# 3.0 | 下載 DOC | C# 語言規格版本 3.0：Microsoft Corporation |
| C# 2.0 | 下載 PDF | 標準 ECMA-334 第 4 版 |
| C# 1.2 | 下載 DOC | 標準 ECMA-334 第 2 版 |
| C# 1.0 | 下載 DOC | 標準 ECMA-334 第 1 版 |
支援所有語言功能所需的最低 SDK 版本
下表列出提供 C# 編譯器支援對應語言版本的 SDK 最低版本：
| C# 版本 | 最低 SDK 版本 |
|---|---|
| C# 12 | Microsoft Visual Studio/Build Tools 2022 17.8 版，或 .NET 8 SDK |
| C# 11 | Microsoft Visual Studio/Build Tools 2022 17.4 版，或 .NET 7 SDK |
| C# 10 | Microsoft Visual Studio/Build Tools 2022，或 .NET 6 SDK |
| C# 9.0 | Microsoft Visual Studio/Build Tools 2019 16.8 版，或 .NET 5 SDK |
| C# 8.0 | Microsoft Visual Studio/Build Tools 2019 16.3 版，或 .NET Core 3.0 SDK |
| C# 7.3 | Microsoft Visual Studio/Build Tools 2017 15.7 版 |
| C# 7.2 | Microsoft Visual Studio/Build Tools 2017 15.5 版 |
| C# 7.1 | Microsoft Visual Studio/Build Tools 2017 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 或配套的 .NET Framework 4.5 編譯器 |
| C# 4 | Microsoft Visual Studio/Build Tools 2010 或配套的 .NET Framework 4.0 編譯器 |
| C# 3 | Microsoft Visual Studio/Build Tools 2008 或配套的 .NET Framework 3.5 編譯器 |
| C# 2 | Microsoft Visual Studio/Build Tools 2005 或配套的 .NET Framework 2.0 編譯器 |
| C# 1.0/1.2 | Microsoft Visual Studio/Build Tools .NET 2002 或配套的 .NET Framework 1.0 編譯器 |
Nullable
[可為 Null] 選項可讓您指定可為 Null 的內容。 您可以使用 <Nullable> 標記，在專案的設定中設定這個項目：
<Nullable>enable</Nullable>
引數必須是 enable、disable、warnings 或 annotations 的其中一個。 enable 變數會啟用可為 Null 的內容。 指定 disable 將停用可為 Null 的內容。 您指定 warnings 引數時，會啟用可為 Null 的警告內容。 您指定 annotations 引數時，會啟用可為 Null 的註釋內容。 這些值會在關於可為 Null 內容的文章中描述和解說。 在我們關於可為 Null 移轉策略的文章中，您可以深入瞭解在現有程式碼基底中啟用可為 Null參考型別的相關工作。
注意
未設定任何值時，會套用預設值 disable，不過預設會提供 .NET 6 範本，並將可為 Null 的值設定為 enable。
流程分析可用來對於可執行程式碼中的變數推斷變數的可 Null 性。 變數的推斷可 Null 性與變數宣告的 Null 屬性無關。 即使有條件地省略方法呼叫，也會進行分析。 例如，發行模式中的 Debug.Assert。
使用下列屬性標註的方法叫用也會影響流程分析：
- 簡單的前置條件：AllowNullAttribute 和 DisallowNullAttribute
- 簡單的後置條件：MaybeNullAttribute 和 NotNullAttribute
- 條件式後置條件：MaybeNullWhenAttribute 和 NotNullWhenAttribute
- DoesNotReturnIfAttribute (例如，Debug.Assert 的
DoesNotReturnIf(false)) 和 DoesNotReturnAttribute - NotNullIfNotNullAttribute
- 成員後置條件：MemberNotNullAttribute(String) 和 MemberNotNullAttribute(String[])
重要
內容全域可為 null 不適用於產生的程式碼檔案。 不論此設定為何，所有標記為產生的來源檔案，都會「停用」內容可為 null。 有四種方式可將檔案標記為是產生的檔案：
- 在 .editorconfig 中，於套用至該檔案的區段中，指定
generated_code = true。 - 將
<auto-generated>或<auto-generated/>置於檔案頂端的註解中。 它可以在註解的任一行，但註解區塊必須是檔案中的第一個元素。 - 使用 TemporaryGeneratedFile_ 做為檔案名稱的開頭
- 使用 .designer.cs、.generated.cs、.g.cs 或 .g.i.cs 做為檔案名稱的結尾。
產生器可以選擇使用 #nullable 前置處理指示詞。
