NBearV3 ORM 進階教學：實體自關聯、IndexProperty 與 BatchUpdate 效能優化、Gateway 強型別查詢深度解析

教學目標

全面掌握 NBearV3 ORM 進階功能：實體自關聯設計、效能相關屬性（IndexProperty、BatchUpdate）配置、Gateway 強型別查詢方法在不同屬性設定下的效能差異分析。

Step 1：環境準備

基於 ORM_Tutorial 複製專案重命名為 ORM_Adv_Tutorial，引用 dist 目錄 DLL 與基礎教學程式碼。

Step 2：擴展實體設計與元資料

IndexProperty：自動建立資料庫索引

[IndexProperty]
Guid ParentID { get; set; }

標記後，生成資料庫腳本時自動為該欄位建立單欄索引，提升以此欄位為條件的查詢效能。

自關聯：實體關聯自身

[FkQuery("ParentID", Contained=true, LazyLoad=true)]
Group[] SubGroups { get; set; }

Group 實體 1 對多關聯自身，形成樹狀結構。注意： NBearV3 不支援多對多自關聯，也不支援繼承體系中的多對多關聯。

BatchUpdate：批次更新大幅降低資料庫連線數

[BatchUpdate(10)]
public interface User : Entity { ... }

[BatchUpdate(10)]
public interface LocalUser : User { ... }

效能影響驚人：原本 20 個級聯 Delete 需 20 次連線，設 BatchUpdate(10) 後僅需 2 次連線（每 10 筆一批）。

Step 3：生成程式碼、配置與資料庫腳本

1. 編譯 EntityDesigns
2. 執行 EntityDesignToEntity.exe 載入 DLL
3. Generate Entities → Entities\Entities.cs
4. Generate Configuration → website\EntityConfig.xml
5. Generate DB Script → website\db.sql（於 SQL Server tempdb 執行）

Step 4：Gateway 強型別查詢方法實戰與 SQL 日誌分析

刪除 Default.aspx.cs 原始碼，參考教學目錄範例建立新頁面，展示 Gateway 大多數強型別查詢方法。

關鍵觀察重點

1. BatchUpdate 前後差異：觀察 Save/Delete 時實際執行的 SQL 陳述式數量與連線次數
2. LazyLoad 時機差異：LazyLoad=true 首次存取時載入，LazyLoad=false 實例化即載入，SQL 日誌明顯可見

附錄：進階技巧

Entity.Attach()/Detach()/IsAttached() 靈活控制 Insert/Update

• 新 new Entity() → IsAttached() == false → Save() 執行 Insert
• Gateway.Find() 取得 → IsAttached() == true → Save() 僅 Update 修改欄位
• 技巧 1：避免 Select 再 Update — 已知 ID 需更新單欄位時：new User { ID=id }.Attach(); user.Status=...; gateway.Save(user); 僅 1 次 Update
• 技巧 2：批量修改前 Detach — 避免頻繁觸發 OnPropertyChanged 事件：user.Detach(); /* 批量修改 */ user.Attach(); gateway.Save(user);

Gateway.RegisterSqlLogger()/UnregisterSqlLogger()

gateway.RegisterSqlLogger(new LogHandler(WriteLine));  // 註冊 SQL 日誌輸出
// 開發/調試/效能優化必備，監控強型別 API 底層真實 SQL 互動

總結

善用 IndexProperty 建立索引、BatchUpdate 減少資料庫往返、LazyLoad 控制載入時機、Attach/Detach 靈活切換持久化狀態，配合 SqlLogger 監控 SQL，能構建高效能 ORM 應用。