C# partial 部分類型完整解析：分割定義、屬性累加、修飾符一致性與介面合併

partial 關鍵字允許將單一類別、結構、介面或方法的定義分散在多個原始檔中，編譯時自動合併。常用於：自動產生程式碼與手寫程式碼分離 (如 WinForms Designer、EF Core Context)、大型類別模組化、多人協作。本文完整說明語法規則、限制與進階特性。

基本語法

// File1.cs
public partial class Person
{
    public string Name { get; set; }
    public void SayHello() => Console.WriteLine($"Hi, {Name}");
}

// File2.cs
public partial class Person
{
    public int Age { get; set; }
    public void SayAge() => Console.WriteLine($"Age: {Age}");
}

// 編譯後等同於
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public void SayHello() { ... }
    public void SayAge() { ... }
}

適用目標與限制

核心規則

• 所有部分都必須標記 partial (C# 2.0+ 要求)。
• 同一命名空間 內 (或全域命名空間)。
• 同時編譯 (同一專案或模組)。
• 存取修飾符一致：若一部分標記 public，其他部分不可標記 internal；若無標記則預設一致。
• 基類一致：各部分若指定基類必須相同；可僅在一部分指定。
• 介面列表累加：各部分實作的介面會合併。

屬性累加效應

[Serializable]
[Obsolete("v1")]
partial class Entity { }

[DataContract]
[Obsolete("v2")]
partial class Entity { }

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

// 注意：AllowMultiple=true 的屬性可重複套用 (如 Obsolete)，否則會疊加

修飾符傳播規則

Partial Methods (部分方法)

public partial class Generator
{
    // 宣告 (簽名) - 必須無回傳值、無 out、可有 ref/in
    partial void OnGenerated(string code);

    public void Generate()
    {
        string code = "// generated";
        OnGenerated(code); // 若無實作，呼叫點會被編譯器移除 (零成本)
    }
}

// 另一個檔案可選擇實作
public partial class Generator
{
    partial void OnGenerated(string code)
    {
        Console.WriteLine("Generated: " + code);
        File.WriteAllText("output.cs", code);
    }
}

特性：

• 編譯時若無實作，呼叫點與簽名完全移除，不產生 IL。
• 常用於程式碼產生器提供「擴充點」給開發者注入邏輯。

實務應用場景

1. WinForms/WPF 設計器：Form1.Designer.cs (自動產生) + Form1.cs (手寫)。
2. Entity Framework Core DbContext：OnModelCreating 部分方法分離實體設定。
3. 大型領域模型：Order.Core.cs、Order.Pricing.cs、Order.Shipping.cs 分模組維護。
4. 原始碼產生器：產生 partial class DTO 讓開發者補充驗證邏輯。

常見錯誤與除錯

• CS0260：修飾符不一致 (如一部分 public 一部分 internal)。
• CS0261：基類不一致。
• CS0759：Partial method 宣告有實作但簽名不符 (如回傳值型別不同)。
• 同一類別在不同組件 (DLL) 中定義 partial → 無法合併，必須在同一編譯單元。