C# 前置處理器指示詞

發行項
11/12/2024

雖然編譯器沒有另外的前置處理器，但處理本節中所述的指示詞時，會像是有前置處理器一樣。您可以使用這些指示詞來協助條件式編譯。不同於 C 和 C++ 指示詞，您無法使用這些指示詞來建立巨集。每個前置處理器指示詞都必須是該行中的唯一指令。

可為 Null 的內容

#nullable前置處理器指示詞將可為 Null 註釋內容及可為 Null 警告內容設為停用。這個指示詞會控制可為 Null 的注釋是否有效，以及是否提供可為 Null 的警告。每個內容都會停用或啟用。

這兩個內容都可以專案層級指定 (在 C# 原始程式碼外部)，並將 Nullable 元素新增至 PropertyGroup 元素。 #nullable 指示詞會控制批註和警告內容，並優先於專案層級設定。指示詞會設定它控制的內容，直到另一個指示詞覆寫，或直到來源檔案的結尾為止。

指示詞的效果如下所示：

#nullable disable：將可為 Null 註釋及警告內容設定為停用。
#nullable enable：將可為 Null 註釋及警告內容設定為啟用。
#nullable restore：將可為 Null 註釋及警告內容還原至專案設定。
#nullable disable annotations：將可為 Null 註釋內容設定為停用。
#nullable enable annotations：將可為 Null 註釋內容設定為啟用。
#nullable restore annotations：將可為 Null 註釋內容還原至專案設定。
#nullable disable warnings：將可為 Null 警告內容設為停用。
#nullable enable warnings：將可為 Null 警告內容設為啟用。
#nullable restore warnings：將可為 Null 警告內容還原至專案設定。

條件式編譯

您可以使用四個預處理器指示詞來控制條件式編譯：

#if：開啟條件式編譯，其中只有在定義指定的符號時，才會編譯器代碼。
#elif：關閉上述條件式編譯，並根據定義指定的符號來開啟新的條件式編譯。
#else：關閉上述條件式編譯，如果先前指定的符號尚未定義，則開啟新的條件式編譯。
#endif：關閉先前的條件式編譯。

C# 編譯器只會在定義指定的符號時，或在未使用 ! not 運算子時，編譯 #if 指示詞和 #endif 指示詞之間的程式碼。不同於 C 和 C++，無法指派符號的數值。 C# 中的 #if 陳述式是布林值，且只測試是否已經定義符號。例如，定義時 DEBUG 會編譯下列程式碼：

#if DEBUG
    Console.WriteLine("Debug version");
#endif

未定義 MYTEST 時，會編譯下列程式代碼：

#if !MYTEST
    Console.WriteLine("MYTEST is not defined");
#endif

您能使用運算子 == (相等) 和 != (不等) 來測試 bool 值 true 或 false。 true 表示已定義符號。 #if DEBUG 陳述式的意義與 #if (DEBUG == true) 一樣。您可以使用 && (和) 、|| (或) ，以及 ! (不) 運算子來評估是否已定義多個符號。您也可以使用括弧來將符號和運算子分組。

以下是複雜的指示詞，可讓您的程式碼利用較新的 .NET 功能，同時保持回溯相容。例如，假設您在程式碼中使用 NuGet 套件，但套件僅支援 .NET 6 和更新版本，以及 .NET Standard 2.0 和更新版本：

#if (NET6_0_OR_GREATER || NETSTANDARD2_0_OR_GREATER)
    Console.WriteLine("Using .NET 6+ or .NET Standard 2+ code.");
#else
    Console.WriteLine("Using older code that doesn't support the above .NET versions.");
#endif

#if 連同 #else、#elif、#endif、#define 和 #undef 指示詞，可讓您根據一或多個符號是否存在來包含或排除程式碼。在編譯偵錯組建的程式碼時，或是在針對特定組態進行編譯時，條件式編譯非常實用。

以一個 #if 指示詞開頭的條件指示詞必須明確地以一個 #endif 指示詞終止。 #define 可讓您定義符號。使用該符號作為傳遞到 #if 指示詞的運算式，運算式就會評估為 true。您也可以使用 DefineConstants 編譯器選項來定義符號。您可以使用 #undef 來取消定義符號。使用 #define 建立的符號範圍是定義它的檔案。透過 DefineConstants 或 #define 定義的符號不會與相同名稱的變數發生衝突。也就是說，您不應將變數名稱傳遞給前置處理器指示詞，而且符號僅能由前置處理器指示詞來評估。

#elif 可讓您建立複合條件指示詞。如果前面的 #if 和任何前面的選擇性 #elif 指示詞運算式都不是評估為 true，就會評估 #elif 運算式。如果 #elif 運算式評估為 true，編譯器會評估 #elif 與下一個條件指示詞之間的所有程式碼。例如：

#define VC7
//...
#if DEBUG
    Console.WriteLine("Debug build");
#elif VC7
    Console.WriteLine("Visual Studio 7");
#endif

#else 可讓您建立複合條件指示詞，如此，如果前面的 #if 或 (選擇性) #elif 指示詞中沒有運算式評估為 true，則編譯器會評估 #else 與後續 #endif 之間的所有程式碼。 #endif(#endif) 必須是 #else 後面的下一個前置處理器指示詞。

#endif 指定條件指示詞的結尾，而其開始於 #if 指示詞。

建置系統也能分辨 SDK 樣式專案中代表不同目標 Framework 的預先定義前置處理器符號。若要建立能以多個 .NET 版本為目標的應用程式，這些符號就很實用。

目標 Framework	符號	其他符號 (適用於 .NET 5+ SDK)	平台符號 (僅可於指定 OS 特定 TFM 後使用)
.NET Framework
.NET Standard
.NET 5+ (和 .NET Core)			`[OS][version]` (例如 `IOS15_1`)、 `[OS][version]_OR_GREATER` (例如 `IOS15_1_OR_GREATER`)

注意

無論您的目標版本為何，系統都會定義無版本符號。
系統只會針對您設定為目標的版本定義版本特定符號。
系統會針對您的目標版本和所有更早版本定義 <framework>_OR_GREATER 符號。舉例來說，如果您要以 .NET Framework 2.0 為目標，則會定義下列符號：NET20、NET20_OR_GREATER、NET11_OR_GREATER 與 NET10_OR_GREATER。
NETSTANDARD<x>_<y>_OR_GREATER 符號只會針對 .NET Standard 目標定義，而不是針對實作 .NET Standard 的目標，例如 .NET Core 和 .NET Framework。
這些與 MSBuild TargetFramework 屬性和 NuGet 所使用的目標 Framework Moniker (TFM) 不同。

注意

針對傳統的非 SDK 樣式專案，您必須透過專案的屬性頁面，手動為 Visual Studio 中不同目標架構設定條件式編譯符號。

其他預先定義符號包括 DEBUG 和 TRACE 常數。您可以使用 #define 來覆寫為專案所設定的值。例如，DEBUG 符號會根據您的組建組態屬性 ("Debug" 或 "Release" 模式) 而自動設定。

以下範例說明如何在檔案上定義 MYTEST 符號，然後測試 MYTEST 和 DEBUG 符號的值。此範例的輸出視您使用 Debug 或 Release 組態模式建置專案而有所不同。

#define MYTEST
using System;
public class MyClass
{
    static void Main()
    {
#if (DEBUG && !MYTEST)
        Console.WriteLine("DEBUG is defined");
#elif (!DEBUG && MYTEST)
        Console.WriteLine("MYTEST is defined");
#elif (DEBUG && MYTEST)
        Console.WriteLine("DEBUG and MYTEST are defined");
#else
        Console.WriteLine("DEBUG and MYTEST are not defined");
#endif
    }
}

以下範例說明如何測試不同的目標 Framework，讓您可以盡可能使用較新的 API：

public class MyClass
{
    static void Main()
    {
#if NET40
        WebClient _client = new WebClient();
#else
        HttpClient _client = new HttpClient();
#endif
    }
    //...
}

定義符號

您可以使用下列兩個預處理器指示詞來定義或取消定義條件式編譯的符號：

#define：定義符號。
#undef：取消符號的定義。

您可以使用 #define 來定義符號。當您將符號作為運算式傳遞給 #if 指示詞時，運算式會判斷值為 true，如下列範例所示：

#define VERBOSE

#if VERBOSE
   Console.WriteLine("Verbose output version");
#endif

注意

在 C# 中，應該使用 const 關鍵字來定義基本常數。 const 宣告會建立無法在執行階段修改的 static 成員。如果常數值通常是在 C 和 C++ 中進行宣告，您就不能使用 #define 指示詞進行宣告。如果您有數個這類常數，請考慮建立個別的「常數」類別來保留它們。

符號可以用來指定編譯的條件。您可以使用 #if 或 #elif 來測試符號。您也可以使用 ConditionalAttribute 執行條件式編譯。您可以定義符號，但不能將值指派給符號。如果您要使用的任何指示並不是前置處理器指示詞，則檔案中必須先出現 #define 指示詞才行。您也可以使用 DefineConstants 編譯器選項來定義符號。您可以使用 #undef 來取消定義符號。

定義區域

您可以使用下列兩個預處理器指示詞，定義大綱中可折疊的程式碼區域：

#region：啟動區域。
#endregion：結束區域。

#region 可讓您指定程式碼區塊，當您使用程式碼編輯器的大綱時，可以展開或摺疊該程式碼區塊。在較長的程式碼檔案中，摺疊或隱藏一或多個區域是很方便的，如此您可以專注於目前處理的檔案部分。下例示範如何定義區域：

#region MyClass definition
public class MyClass
{
    static void Main()
    {
    }
}
#endregion

#region 區塊必須以 #endregion 指示詞結束。 #region 區塊無法與 #if 區塊重疊。不過，#region 區塊可以巢狀方式置於一個 #if 區塊中，而一個 #if 區塊可以巢狀方式置於 #region 區塊中。

錯誤和警告資訊

您可以指示編譯器使用下列指示詞產生使用者定義的編譯器錯誤和警告，以及控制行資訊：

#error：產生具有指定訊息的編譯器錯誤。
#warning：產生具有特定訊息的編譯器警告。
#line：變更以編譯器訊息列印的行號。

#error 可讓您從您程式碼中的特定位置產生 CS1029 使用者定義錯誤。例如：

#error Deprecated code in this method.

注意

編譯器會以特殊方式處理 #error version，並報告編譯器錯誤 CS8304，其中包含使用的編譯器和語言版本的訊息。

#warning 可讓您從程式碼中的特定位置產生 CS1030 層級一的編譯器警告。例如：

#warning Deprecated code in this method.

#line 可讓您修改編譯器的行號以及 (選擇性) 錯誤和警告的檔案名稱輸出。

下列範例示範如何報告兩個與行號建立關聯的警告。 #line 200 指示詞會將下一行的行號強制為 200 (但預設值為 #6)，而且在下一個 #line 指示詞之前，檔案名稱將會回報為 "Special"。 #line default 指示詞會將行編號還原為其預設編號，這會計算已由先前的指示詞重新編號的行。

class MainClass
{
    static void Main()
    {
#line 200 "Special"
        int i;
        int j;
#line default
        char c;
        float f;
#line hidden // numbering not affected
        string s;
        double d;
    }
}

編譯會產生下列輸出：

Special(200,13): warning CS0168: The variable 'i' is declared but never used
Special(201,13): warning CS0168: The variable 'j' is declared but never used
MainClass.cs(9,14): warning CS0168: The variable 'c' is declared but never used
MainClass.cs(10,15): warning CS0168: The variable 'f' is declared but never used
MainClass.cs(12,16): warning CS0168: The variable 's' is declared but never used
MainClass.cs(13,16): warning CS0168: The variable 'd' is declared but never used

#line 指示詞可以用於建置程序中的自動化中繼步驟。例如，如果已從原始程式碼檔中移除行，但您仍然想要編譯器根據檔案中的原始行編號來產生輸出，則可以移除行，然後模擬具有 #line 的原始行編號。

#line hidden 指示詞會隱藏偵錯工具中的後續行，如此一來，開發人員逐步執行程式碼時，會逐步執行 #line hidden 與下一個 #line 指示詞 (假設它不是另一個 #line hidden 指示詞) 之間的任何行。此選項也可用來讓 ASP.NET 區分使用者定義的程式碼與電腦產生的程式碼。雖然 ASP.NET 是這項功能的主要取用者，但是可能會有更多來源產生器利用它。

#line hidden 指示詞不會影響錯誤報告中的檔案名稱或行號。也就是說，如果隱藏區塊中編譯器發現錯誤，則編譯器會報告錯誤的目前檔案名稱和行號。

#line filename 指示詞指定您想要在編譯器輸出中顯示的檔案名稱。預設會使用原始程式碼檔的實際名稱。檔案名稱必須以雙引號 ("") 括住，而且前面必須有行號。

從 C# 10 開始，您可以使用 #line 指示詞的新形式：

#line (1, 1) - (5, 60) 10 "partial-class.cs"
/*34567*/int b = 0;

此表單的元件包括：

(1, 1)：指示詞後面一行第一個字元的起始行和資料行。在此範例中，下一行會回報為第 1 行，第 1 欄。
(5, 60)：標示區域的結束行和資料行。
10：#line 指示詞要生效的資料行位移。在此範例中，第 10 個資料行會回報為第一欄。這就是宣告 int b = 0; 開始的位置。這是選用欄位。如果省略，指示詞會對第一個資料行生效。
"partial-class.cs"：輸出檔的名稱。

上述範例會產生下列警告：

partial-class.cs(1,5,1,6): warning CS0219: The variable 'b' is assigned but its value is never used

在重新對應之後，變數 b 位於檔案 partial-class.cs 的第一行，第六個字元。

網域特定語言 (DSL) 通常會使用此格式，以提供更好的來源檔案對應至產生的 C# 輸出。這個擴充 #line 指示詞最常見的用法是將產生的檔案中出現的警告或錯誤重新對應至原始來源。例如，請參考這個 Razor 頁面：

@page "/"
Time: @DateTime.NowAndThen

屬性 DateTime.Now 輸入錯誤為 DateTime.NowAndThen。在 page.g.cs 中，這個 Razor 程式碼片段產生的 C# 看起來如下：

  _builder.Add("Time: ");
#line (2, 6) - (2, 27) 15 "page.razor"
  _builder.Add(DateTime.NowAndThen);

上述程式碼片段的編譯器輸出為：

page.razor(2, 2, 2, 27)error CS0117: 'DateTime' does not contain a definition for 'NowAndThen'

第 2 行，page.razor 中的第 6 欄是文字 @DateTime.NowAndThen 開始的位置。指示詞中由 (2, 6) 指出。 @DateTime.NowAndThen 範圍結束於第 2 行，第 27 欄。指示詞中指出 (2, 27)。 DateTime.NowAndThen 的文字從 page.g.cs 的第 15 欄開始。指示詞中由 15 指出。將所有引數放在一起，編譯器會在 page.razor 中報告其位置中的錯誤。開發人員可以直接導覽至其原始程式碼中的錯誤，而不是產生的來源。

若要查看此格式的更多範例，請參閱範例一節中的功能規格。

Pragma

#pragma 將編譯編譯器所在檔案的特殊指示提供給編譯器。編譯器必須支援指示。換句話說，您不能使用 #pragma 來建立自訂前置處理指示。

#pragma warning：啟用或停用警告。
#pragma checksum：產生總和檢查碼。

#pragma pragma-name pragma-arguments

其中 pragma-name 是已辨識 pragma 的名稱，而 pragma-arguments 是 pragma 特定的引數。

#pragma warning

#pragma warning 可以啟用或停用特定警告。

#pragma warning disable warning-list
#pragma warning restore warning-list

warning-list 為警告編號的逗點分隔清單。 "CS" 前置詞是選擇性的。未指定警告編號時，disable 會停用所有警告，而 restore 會啟用所有警告。

注意

若要尋找 Visual Studio 中的警告編號，請建立專案，然後在 [輸出] 視窗中尋找警告編號。

disable 會從來源檔案的下一行開始生效。警告會在 restore 後面的這一行還原。如果檔案中沒有 restore，警告會還原至相同編譯中任何稍後檔案的第一行的預設狀態。

// pragma_warning.cs
using System;

#pragma warning disable 414, CS3021
[CLSCompliant(false)]
public class C
{
    int i = 1;
    static void Main()
    {
    }
}
#pragma warning restore CS3021
[CLSCompliant(false)]  // CS3021
public class D
{
    int i = 1;
    public static void F()
    {
    }
}

#pragma checksum

產生原始程式檔的總和檢查碼，協助偵錯 ASP.NET 頁面。

#pragma checksum "filename" "{guid}" "checksum bytes"

其中 "filename" 是需要監視變更或更新的檔案名，"{guid}" 是雜湊演算法的全域唯一識別碼 (GUID)，而且 "checksum_bytes" 是代表總和檢查碼位元組的十六進位數位字串。必須是偶數的十六進位數字。奇數的數字會導致編譯時期警告，並且忽略指示詞。

Visual Studio 偵錯工具會使用總和檢查碼來確定一定會找到正確的來源。編譯器會計算來源檔案的總和檢查碼，然後將輸出發至程式資料庫 (PDB) 檔案。然後偵錯工具會使用 PDB 比較總和檢查碼計算來源檔案。

這個解決方案不適用於 ASP.NET 專案，因為計算過的總和檢查碼適合產生的來源檔案，不是 .aspx 檔案。若要解決這個問題，#pragma checksum 會為 ASP.NET 頁面提供總和檢查碼支援。

當您在 Visual C# 中建立 ASP.NET 專案時，所產生原始程式檔會包含來源 .aspx 檔案的總和檢查碼。接著編譯器會將這項資訊寫入 PDB 檔案中。

如果編譯器在檔案中找不到任何 #pragma checksum 指示詞，它會計算總和檢查碼並將值寫入 PDB 檔案。

class TestClass
{
    static int Main()
    {
        #pragma checksum "file.cs" "{406EA660-64CF-4C82-B6F0-42D48172A799}" "ab007f1d23d9" // New checksum
    }
}

共用方式為