C# 前置處理器指示詞

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

可為 Null 的內容

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

這兩個內容都可以在專案層級指定（C# 原始程式碼外部）。 指示 #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：關閉上述條件式編譯。

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

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

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

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

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

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

以 指示詞開頭的條件 #if 式指示詞必須明確地以 #endif 指示詞終止。 #define 可讓您定義符號。 藉由使用符號做為傳遞至 指示詞的 #if 運算式，運算式會評估為 true 。 您也可以使用 DefineConstants 編譯器選項來定義符號。 您可以使用 來取消定義符號 #undef 。 使用 #define 建立的符號範圍是定義它的檔案。 您使用 DefineConstants 或 所 #define 定義的 符號不會與相同名稱的變數衝突。 也就是說，變數名稱不應該傳遞至預處理器指示詞，而且符號只能由預處理器指示詞進行評估。

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

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

#else可讓您建立複合條件式指示詞，如此一來，如果上述 #if 或 （選擇性） #elif 指示詞中沒有任何運算式評估為 true ，編譯器將會評估 和下一個 #endif 之間的所有程式碼 #else 。 #endif（#endif） 必須是 之後 #else 的下一個預處理器指示詞。

#endif 會指定以 指示詞開頭 #if 的條件式指示詞結尾。

建置系統也會察覺到預先定義的預處理器符號，這些符號代表 SDK 樣式專案中的不同 目標架構 。 建立可針對多個 .NET 版本的應用程式時，它們很有用。

目標 Framework	符號	其他符號 （適用于 .NET 5+ SDK）	平臺符號（僅適用于 當您指定 OS 特定的 TFM 時）
.NET Framework	NETFRAMEWORK, NET48, NET472, NET471, NET47, NET462, NET461, NET46, NET452, NET451, NET45, NET40, NET35, NET20	NET48_OR_GREATER, NET472_OR_GREATER, NET471_OR_GREATER, NET47_OR_GREATER, NET462_OR_GREATER, NET461_OR_GREATER, NET46_OR_GREATER, NET452_OR_GREATER, NET451_OR_GREATER, NET45_OR_GREATER, NET40_OR_GREATER, NET35_OR_GREATER, NET20_OR_GREATER
.NET Standard	NETSTANDARD, NETSTANDARD2_1, NETSTANDARD2_0, NETSTANDARD1_6, NETSTANDARD1_5, NETSTANDARD1_4, NETSTANDARD1_3, NETSTANDARD1_2, NETSTANDARD1_1, NETSTANDARD1_0	NETSTANDARD2_1_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NETSTANDARD1_6_OR_GREATER, NETSTANDARD1_5_OR_GREATER, NETSTANDARD1_4_OR_GREATER, NETSTANDARD1_3_OR_GREATER, NETSTANDARD1_2_OR_GREATER, NETSTANDARD1_1_OR_GREATER, NETSTANDARD1_0_OR_GREATER
.NET 5+ （和 .NET Core）	NET, NET7_0, NET6_0, NET5_0, NETCOREAPP, NETCOREAPP3_1, NETCOREAPP3_0, NETCOREAPP2_2, NETCOREAPP2_1, NETCOREAPP2_0, NETCOREAPP1_1, NETCOREAPP1_0	NET7_0_OR_GREATER, NET6_0_OR_GREATER, NET5_0_OR_GREATER, NETCOREAPP3_1_OR_GREATER, NETCOREAPP3_0_OR_GREATER, NETCOREAPP2_2_OR_GREATER, NETCOREAPP2_1_OR_GREATER, NETCOREAPP2_0_OR_GREATER, NETCOREAPP1_1_OR_GREATER, NETCOREAPP1_0_OR_GREATER	ANDROID, IOS, MACCATALYST, MACOS, TVOS, WINDOWS, [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 所使用的 目標架構 Moniker （TFM） 不同。

注意

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

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

下列範例示範如何在檔案上定義 MYTEST 符號，然後測試 和 DEBUG 符號的值 MYTEST 。 此範例的輸出取決於您在偵錯或 發行 組態模式上 建置專案。

#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 和 C++ 中進行宣告，您就不能使用 #define 指示詞進行宣告。 在 C# 中的常數是特別定義為類別或結構的靜態成員。 如果您有數個這類常數，請考慮建立個別的「常數」類別來保留它們。

符號可以用來指定編譯的條件。 您可以使用 或 #elif 來測試符號 #if 。 您也可以使用 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 詞會隱藏偵錯工具的後續幾行，如此一來，當開發人員逐步執行程式碼時，將會逐步執行 a #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 。 這個 razor 程式碼片段產生的 C# 看起來如下： page.g.cs

  _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 行，第 6 欄 page.razor 是文字 @DateTime.NowAndThen 開始的位置。 指示詞中會指出 (2, 6) 這一點。 該範圍 @DateTime.NowAndThen 結尾為第 2 行，資料行 27。 指示詞中的 會指出 (2, 27) 這一點。 的文字 DateTime.NowAndThen 從 的第 15 page.g.cs 欄開始。 指示詞中的 會指出 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
    }
}