C# 預處理器指令完整指南：條件編譯、區域標記、警告控制與行號控制

C# 預處理器指令以 # 開頭，不產生 IL 指令，而是影響編譯器行為。常用於條件編譯 (Debug/Release 差異)、程式碼區塊摺疊、自訂警告/錯誤、行號對應 (原始碼產生器)。本文完整整理所有指令用法。

1. 符號定義與移除

#define DEBUG        // 定義符號 (僅影響目前檔案，必須在最頂端)
#undef  DEBUG        // 移除符號

// 命令列定義 (不修改原始碼)
csc /define:DEBUG;TRACE Program.cs
// 或 MSBuild 屬性 DEBUG;TRACE

符號不像 C/C++ 宏可帶數值，只有「定義/未定義」兩種狀態。

2. 條件編譯：#if #elif #else #endif

#if DEBUG
    Console.WriteLine("Debug 模式");
#elif RELEASE
    Console.WriteLine("Release 模式");
#else
    Console.WriteLine("其他組態");
#endif

// 邏輯運算子支援
#if DEBUG && !TEST
    // ...
#endif

// 等價於
#if (DEBUG == true) && (TEST != true)
    // ...
#endif

3. 編譯器警告/錯誤：#warning #error

#warning "TODO: 重構此方法"          // 編譯警告，不中斷建置
#error  "不支援的目標框架"            // 編譯錯誤，立即中斷建置

// 實務範例：防止同時定義衝突符號
#if DEBUG && RELEASE
#error "DEBUG 與 RELEASE 不可同時定義"
#endif

#warning "記得移除測試用程式碼"

4. 程式碼區域摺疊：#region #endregion

#region 公用介面
public void MethodA() { }
public void MethodB() { }
#endregion

#region 私用實作
private void Helper() { }
#endregion

僅影響 Visual Studio / VS Code 編輯器摺疊顯示，不影響編譯輸出。

5. 行號與檔名控制：#line

// 原始碼產生器常用：將產出程式碼對應回原始範本行號
#line 100 "OriginalTemplate.tt"
public void GeneratedMethod() { }
#line default  // 恢復預設行號

除錯時堆疊追蹤將顯示 OriginalTemplate.tt:100。

6. 編譯器指示：#pragma

// 抑制特定警告 (CS0168: 變數宣告未使用)
#pragma warning disable 0168
int unusedVar;
#pragma warning restore 0168

// 抑制區塊內所有警告
#pragma warning disable
// ...
#pragma warning restore

// 產生檢查和 (用於 ASP.NET Razor 偵錯)
#pragma checksum "file.cs" "{406EA660-64CF-4C82-B6F0-42D48172A799}" "ABCDEF..."

7. 完整指令速查表

實務建議

• 條件編譯優先使用建置組態 (DefineConstants) 而非原始碼 #define，避免散落各檔案難以維護。
• #region 別過度使用，建議僅用於大型類別的「公用/私用/事件/介面實作」等邏輯分層。
• #pragma warning disable 盡量縮小範圍，並在旁加註解說明原因。
• 原始碼產生器 (Source Generator) 開發者必須熟悉 #line 與 #pragma checksum。