NHibernate 基礎配置完整指南：從環境建置到常見錯誤排除

前言

對初學者而言，NHibernate 最大的門檻往往在於「配置」。相較於 LINQ to SQL 或 Entity Framework 的開箱即用，NHibernate 需要映射檔案、設定檔、組件參考等多重配置。本文整理實戰經驗，帶您從零建置 NHibernate 環境，並解決常見配置陷阱。

開發環境

• Visual Studio 2008 SP1
• NHibernate 2.1.2.GA-bin

一、啟用 Visual Studio 智能提示

編寫 .hbm.xml 映射檔時，若無智能提示極易出錯。解決方法：

1. 從 NHibernate 安裝目錄找到兩個 XSD 檔案：
   • nhibernate-mapping.xsd
   • nhibernate-configuration.xsd
2. 複製到 VS 架構目錄：
   C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas\
3. 重啟 VS，編輯映射檔即可享有完整 IntelliSense

二、必要組件參考

專案需引用下列組件（2.1.2 版）：

三、映射檔案設為「嵌入資源」

所有 *.hbm.xml 檔案在屬性視窗中，將 Build Action 設為 Embedded Resource。否則執行時會拋出找不到映射資源的異常。

四、unsaved-value 設定

識別物件是否為暫態（未持久化）的關鍵：

• 整數主鍵：unsaved-value="0"
• Guid 主鍵：unsaved-value="00000000-0000-0000-0000-000000000000"
• 字串主鍵：unsaved-value="null" 或空字串

詳細說明請參考：CSDN 部落格文章

五、NHibernate 設定檔配置

1. 從 Configuration_Templates 資料夾複製對應資料庫的設定檔（如 hibernate.cfg.xml）
2. 關鍵步驟：在 <session-factory> 區段加入組件對應：
   <mapping assembly="Model" />
3. 設定資料庫連線字串、方言、連線提供者等參數

六、映射檔 class 節點屬性正確性

錯誤的 name、assembly、namespace 會導致：

NHibernate.MappingException: persistent class not found

檢查清單：

• name：完整類型名稱（含命名空間）
• assembly：組件名稱（不含 .dll）
• namespace：命名空間（可選，若 name 已含完整命名空間可省略）

七、NHibernate 2.1.2 版關鍵變更

• 必須設定延遲載入方式（proxyfactory.factory_class）
• 設定檔不需設為「永遠複製」，預設即可
• 相依組件增加（因強制需代理工廠）
• 所有實體類別屬性必須標記 virtual（除非明確關閉延遲載入）

八、配置檢查清單總結

總結

NHibernate 配置雖繁瑣，但遵循「映射檔嵌入資源、設定檔加入組件對應、代理工廠必須指定、版本相依組件齊全」四大原則，即可避開 90% 的初學者陷阱。建議新手先從簡單單表操作起步，逐步掌握映射技巧，再挑戰複雜關聯配置。