C# partial 關鍵字深度解析：分部類型、分部方法與實戰最佳實務

什麼是分部類型？

partial 讓單一類別、結構、介面或委派的定義可分散在多個 .cs 檔案中。編譯時編譯器會將其合併為單一型別。C# 2.0 引入，主要解決：

• 超大型別拆分維護
• 程式碼產生器產出的程式碼與手寫程式碼隔離（如 WinForms Designer、EF Core Context、ASP.NET Core Razor Pages）
• 團隊並行開發同一型別

基本語法

// File: Customer.Data.cs
public partial class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

// File: Customer.Behavior.cs
public partial class Customer
{
    public void SendWelcomeEmail() => Console.WriteLine($"Welcome {Name}!");
    public bool IsVip => Id < 100;
}

編譯後等同於單一檔案完整定義。

限制與規則

屬性與介面的「累加」特性

// File1.cs
[Serializable, Obsolete("v1")]
partial class Entity { }

// File2.cs
[DataContract, Obsolete("v2")]
partial class Entity { }

// 編譯後等同於：
[Serializable, Obsolete("v1"), DataContract, Obsolete("v2")]
class Entity { }

• 屬性會合併（允許重複的屬性如 Obsolete 會全部保留）
• 實作的介面清單會聯集合併

分部方法

讓產生器宣告「掛點」，開發者選擇性實作。若無實作，呼叫端與宣告皆會被編譯器移除（零成本）。

規則

• 簽章：partial void MethodName(parameters)
• 必須 void 回傳、不可有 out 參數
• 預設 private，不可標記存取修飾詞
• 可為 static、unsafe、泛型
• 可在介面中宣告（C# 8+）

範例：Entity Framework Core 實體驗證掛點

// 產生器產出
public partial class Order
{
    partial void OnValidateSave();
    public void Save()
    {
        OnValidateSave(); // 若無實作，此行編譯後消失
        // 存資料庫邏輯
    }
}

// 開發者實作
public partial class Order
{
    partial void OnValidateSave()
    {
        if (Amount <= 0) throw new InvalidOperationException("金額需大於 0");
    }
}

實戰最佳實務

常見誤區

• ❌ 將 partial 用於方法分割（除非是分部方法）
• ❌ 跨專案/組件使用（編譯器無法合併）
• ❌ 同一型別不同部分使用不同基類
• ✅ 善用分部方法作為擴充點，而非大量虛擬方法
• ✅ 產生器程式碼標記 [GeneratedCode] 屬性，便於工具識別

結語

partial 是「編譯時合併」的語法糖，零執行期成本。善用它可實現關注點分離、產生器與手寫程式碼共存、大型團隊並行開發。核心原則：單一職責原則延伸至檔案層級——每個 .cs 檔只負責一件事。