---

applyTo: "**/*.{cs,aspx.cs,ascx.cs,ashx.cs}"

---

共用函式庫使用規範 (CHMC.dll & CommonUtilities.dll)

overarching 原則

1. 優先使用，禁止重造輪子: 在實作任何底層功能（如加解密、日誌、檔案、組態讀取、通用計算）之前，必須優先查閱本文件，確認共用函式庫中是否已有可用的方法。

2. 記錄原因: 若現有方法確實無法滿足需求（例如效能、參數不符），應在程式碼註解中簡要記錄無法覆用的原因，然後再自行實作。

---

函式庫一：CHMC.dll

CHMC.dll 主要提供與應用程式核心功能相關的工具，包括加解密、組態管理、日誌記錄和郵件發送等。

CHMC.AES

• 用途: 提供 AES 對稱式加解密功能。
• 使用情境: 適用於需要高安全性的資料加密，例如儲存敏感的個人資訊。
• 注意事項:

- Encrypt(string plain_text) 和 Decrypt(string base64String) 使用預設金鑰，方便但不應與外部系統共用。

- 與外部系統交換加密資料時，應使用可傳入 key 和 iv 的多載版本。

- Decrypt 方法在失敗時會擲回 Exception，必須使用 try-catch 區塊包覆。

CHMC.Config

• 用途: 統一讀取 Web.config 或 App.config 中的設定。
• 使用情境:

- 讀取資料庫連線字串時，必須使用 ConnectionString() 或 ConnectionString(string name)。

- 讀取 appSettings 中的自訂設定時，必須使用 appSettings(string key)。

• 注意事項: 這些方法在找不到對應 Key 時會擲回 Exception，建議在 BLL 層進行呼叫並處理異常。

CHMC.DES

• 用途: 提供 DES 對稱式加解密功能。
• 使用情境: 主要用於與舊系統的相容性，新功能建議優先使用 CHMC.AES。
• 注意事項: DecryptString 方法在金鑰或向量錯誤時會回傳 "N/A"，而非擲回異常，呼叫端需對此回傳值進行判斷。

CHMC.Enumeration

• 用途: 提供全專案共用的常數與列舉。
• 使用情境:

- 進行分頁查詢時，使用 PagerTable, PagesCount, RowsCount 作為 DataTable 的欄位名。

- 方法回傳成功/失敗狀態時，使用 ReturnCode.SUCCESS 和 ReturnCode.FAILURE。

CHMC.Log

• 用途: 全專案唯一的日誌記錄工具。
• 使用情境:

- 在所有 try-catch 區塊的 catch 部分，必須呼叫 WriteLog(Exception ex) 來記錄完整的例外堆疊。

- 在關鍵業務流程節點，可以使用 WriteLog(string message) 記錄追蹤訊息。

• 注意事項: WriteLog 方法本身也可能因 I/O 問題擲回異常，但在應用程式層級通常不需額外處理。

CHMC.MailClient

• 用途: 建立及發送電子郵件。
• 使用情境: 用於發送系統通知、使用者註冊信、密碼重設信等。
• 注意事項: MailClient 實作了 IDisposable，必須使用 using 陳述式或在 finally 區塊中呼叫 Dispose() 來確保資源被釋放。

CHMC.StringHelper

• 用途: 提供多種字串處理輔助方法。
• 使用情境:

- 驗證台灣身分證字號時，使用 isIdentificationId。

- 產生隨機驗證碼或密碼時，使用 RandString。

- 與院內舊系統進行密碼交換時，使用 wf_s_encrypt 和 wf_s_decrypt。

CHMC.TripleDES

• 用途: 提供 TripleDES 對稱式加解密功能。
• 使用情境: 同 CHMC.DES，主要用於與特定舊系統的相容性，新功能建議優先使用 CHMC.AES。

---

函式庫二：CommonUtilities.dll

CommonUtilities.dll 提供更廣泛的通用工具，包括資料格式轉換、動態查詢、以及各種計算輔助。

CommonUtilities.CommonUtilities

• 用途: 包含多種實用工具。
• 使用情境:

- JSON: 當需要與前端進行 Ajax 通訊時，使用 JSON.JsonSerialize 和 JSON.JsonDeserialize 進行物件與 JSON 字串的轉換。

- XML: 當需要處理 XML 格式的資料時，使用 XMLFunction 或 DynamicXml。

- CSV: 當需要匯出報表為 CSV 格式時，使用 CSVFunction.ToCSV。

- LINQ: 當需要根據動態欄位名稱進行排序或篩選時，可考慮使用 Linq.DynamicProperties。

CommonUtilities.TypeExtensions

• 用途: 提供類型擴展方法與各種計算、驗證工具。
• 使用情境:

- Calc 類別:

- 驗證身分證字號：Calc.isCivIDValid

- 計算病歷號檢查碼：Calc.PatientIDCheckSum

- 計算年齡：Calc.CalculateAge

- 院內密碼加密：Calc.PasswordEcrypt (注意與 CHMC.StringHelper 中的 wf_s_encrypt 區分使用場景)

- DateTimeHelper 類別: 用於各種複雜的日期計算。

- EnumObject 類別: 當需要取得 Enum 成員上標註的 [Description("...")] 屬性文字時，使用 GetEnumDescription。