語言功能規則的 C# 編譯器選項

下列選項可控制編譯器如何解譯語言功能。 新的 MSBuild 語法會顯示在 Bold 中。 較舊的 csc.exe 語法會顯示在 中 code style

  • CheckForOverflowUnderflow / -checked :產生溢位檢查。
  • AllowUnsafeBlocks / -unsafe :允許 'unsafe' 程式碼。
  • DefineConstants / -define :定義條件式編譯符號 (s) 。
  • LangVersion / -langversion :指定語言版本,例如 default (最新的主要版本) ,或 latest (最新版本,包括次要版本) 。
  • 可為 / -nullable Null:啟用可為 Null 的內容或可為 Null 的警告。

CheckForOverflowUnderflow

CheckForOverflowUnderflow選項會控制預設溢位檢查內容,以在整數算術溢位的情況下定義程式列為。

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

CheckForOverflowUnderflowtrue 時,預設內容是已檢查的內容,且已啟用溢位檢查;否則,預設內容為未核取的內容。 此選項的預設值為 false ,也就是已停用溢位檢查。

您也可以使用 checkedunchecked 語句,明確控制程式代碼部分的溢位檢查內容。

如需溢位檢查內容如何影響作業以及哪些作業受到影響的資訊,請參閱unchecked 語句的相關 checked 文章

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# 語言規格中所含的語法。

<LangVersion>9.0</LangVersion>

下列是有效值:

意義
preview 編譯器會接受最新預覽版本的所有有效語言語法。
latest 編譯器會接受編譯器最新已發行版本 (包括次要版本) 的語法。
latestMajor
default
編譯器會接受編譯器最新已發行主要版本的語法。
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,以及安裝的 SDK 或 Visual Studio 版本。 這些規則是使用 C# 語言版本設定來定義。

C# 應用程式所參考的中繼資料不受 LangVersion 編譯器選項約束。

因為 C# 編譯器的每個版本都包含語言規格的延伸模組, 所以 LangVersion 不會提供舊版編譯器的對等功能。

此外,雖然 C# 版本更新通常會與主要 .NET 版本一致,但新的語法和功能不一定會系結至該特定架構版本。 雖然新功能一定需要也要與 C# 修訂一起發行的新編譯器更新,但是每個特定功能都有自己的最低 .NET API 或通用語言執行平台需求,可讓它包含 NuGet 套件或其他程式庫以在舊版架構上執行。

無論您使用哪一個 LangVersion 設定,請使用目前版本的 Common Language Runtime 來建立您的.exe或.dll。 其中一個例外狀況是 friend 元件和 ModuleAssemblyName,其作用於 -langversion:ISO-1

如需指定 C# 語言版本的其他方式,請參閱 C# 語言版本設定

如需如何以程式設計方式設定這個編譯器選項的詳細資訊,請參閱 LanguageVersion

C# 語言規格

版本 連結 描述
C# 7.0 與更新版本 link C# 語言規格第 7 版 - 非官方草稿:.NET Foundation
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 C# 語言規格版本 1.2:Microsoft Corporation
C# 1.0 下載 DOC C# 語言規格版本 1.0:Microsoft Corporation

支援所有語言功能所需的最低 SDK 版本

下表列出支援對應語言版本的 C# 編譯器之 SDK 的最低版本:

C# 版本 最低 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>

引數必須是 、 disablewarningsannotationsenable 其中一個。 自 enable 變數會啟用可為 Null 的內容。 指定 disable 將會停用可為 Null 的內容。 提供自 warnings 變數時,會啟用可為 Null 的警告內容。 指定 annotations 引數時,會啟用可為 Null 的注釋內容。

注意

如果未設定任何值,則會套用預設值 disable ,不過預設會提供 .NET 6 範本,並將 可為 Null 的值設定為 enable

流程分析可用來推斷可執行程式碼中變數的 Null 性。 變數的推斷 Null 性與變數的宣告可為 Null 性無關。 即使有條件地省略方法呼叫,也會進行分析。 例如, Debug.Assert 在發行模式中。

以下列屬性標注的方法調用也會影響流程分析:

重要

全域可為 Null 的內容不適用於產生的程式碼檔案。 不論此設定為何,標示為產生的任何原始程式檔都會 停用 可為 Null 的內容。 檔案標示為產生的方式有四種:

  1. 在 .editorconfig 中,于套用至該檔案的 區段中指定 generated_code = true
  2. <auto-generated><auto-generated/> 放在檔案頂端的批註中。 它可以在該批註中的任何一行上,但批註區塊必須是檔案中的第一個專案。
  3. 使用TemporaryGeneratedFile_開機檔案名
  4. 使用.designer.cs.generated.cs.g.cs 或 .g.i.cs結束檔案名。

產生器可以使用預處理器指示詞加入宣告 #nullable