C# 進階筆記：委派、事件與 XML 文件註解完整指南

委派

四種常見使用模式

1. 一般委派：執行期建立，傳遞方法參考

   
   public delegate bool CompareDelegate(object lhs, object rhs);
   
   public void SetOrder(CompareDelegate comparer) { ... }
   
   // 使用
   var comparer = new CompareDelegate(Employee.CompareById);
   employees.SetOrder(comparer);
   

2. 靜態唯讀委派：類別層級單一實例，節省記憶體

   
   public static readonly CompareDelegate ById = new CompareDelegate(Employee.CompareById);
   employees.SetOrder(Employee.ById);
   

3. 屬性委派：延遲建立，用時才 new

   
   public static CompareDelegate ById => new CompareDelegate(Employee.CompareById);
   

4. 多播委派：串聯多個方法，回傳型別必須為 void

   
   public delegate void StringHandler(string s);
   
   StringHandler writer = WriteLog;
   StringHandler logger = LogToFile;
   StringHandler storer = StoreToDb;
   
   StringHandler multicast = writer + logger + storer;
   multicast -= logger; // 移除
   multicast("Hello");  // 依序呼叫 writer → storer
   

事件

標準事件模式

// 1. 事件參數類別
public class OfficeEventArgs : EventArgs
{
    public int ChangeCounter { get; }
    public OfficeEventArgs(int counter) => ChangeCounter = counter;
}

// 2. 發佈者
public class Office
{
    // 委派型別
    public delegate void OfficeChangedHandler(object sender, OfficeEventArgs e);

    // 事件
    public event OfficeChangedHandler OfficeChanged;

    // 觸發方法
    protected virtual void OnOfficeChanged(OfficeEventArgs e)
    {
        OfficeChanged?.Invoke(this, e); // 執行緒安全寫法
    }

    // 業務邏輯
    private int _counter;
    public string this[int index]
    {
        set
        {
            _counter++;
            OnOfficeChanged(new OfficeEventArgs(_counter));
        }
    }
}

// 3. 訂閱者
public class OfficeWatcher
{
    public OfficeWatcher(Office office)
    {
        office.OfficeChanged += OnOfficeChanged; // 訂閱
    }

    private void OnOfficeChanged(object sender, OfficeEventArgs e)
    {
        Console.WriteLine($"Office 變更次數: {e.ChangeCounter}");
    }
}

XML 文件註解與產生

三斜線註解標籤

產生文件步驟

1. 專案屬性 → 建置 → 輸出 → 勾選「XML 文件檔案」，指定路徑（如 bin\Debug\MyLib.xml）
2. 建置專案 (Ctrl+Shift+B)，產生 XML 檔
3. 使用工具產生人類可讀格式：
   • Sandcastle Help File Builder (SHFB) → 產生 .chm/.html
   • DocFX / DocFX Console → 靜態網站
   • Visual Studio 延伸模組「Generate XML Documentation」

範例

/// <summary>
/// 計算兩個整數的最大公因數
/// </summary>
/// <param name="a">第一個整數</param>
/// <param name="b">第二個整數</param>
/// <returns>最大公因數</returns>
/// <exception cref="ArgumentException">參數不可為負數</exception>
public int Gcd(int a, int b)
{
    if (a < 0 || b < 0) throw new ArgumentException();
    while (b != 0) { int t = b; b = a % b; a = t; }
    return a;
}