Instruction asset

編輯一般指令

共用內容只保存一份；工具差異放在專用補充，下載時才組合。

基本資料

名稱

唯一代稱

小寫英文、數字與連字號；建立後仍可修改但不可重複。

簡短說明

主要分類

預設排序

標籤

尚無標籤，可先到「分類與標籤」建立。

共用 Markdown 與即時預覽

共用指令內容

---
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`。

格式化預覽

工具與套用範圍

適用工具

GitHub Copilot Codex Claude Code Cursor Antigravity

套用範圍

指定路徑模式

每行一筆。當次下載仍可覆寫，不會修改此正式設定。

工具專用補充

只填差異，不要複製整份共用內容。

GitHub Copilot

Codex

Claude Code

Cursor

Antigravity

修改說明

選填；會保存在這次建立的新版本中。

取消