NHibernate使用簡介

NHibernate使用簡介
NHibernate快速指南

什麼是NHibernate

NHibernate 是一個基於.Net 的針對關係型資料庫的對象持久化類庫。Nhibernate 來源於非常優秀的基於Java的Hibernate 關係型持久化工具。

NHibernate 從資料庫底層來持久化你的.Net 對象到關係型資料庫。NHibernate 為你處理這些，遠勝於你不得不寫SQL去從資料庫存取對象。你的代碼僅僅和對象關聯，NHibernat 自動產生SQL語句，並確保對象提交到正確的表和欄位中去。

為什麼寫這個指南

任何熟悉Hibernate的人會發現這篇指南和Glen Smith 的A Hitchhiker's Guide to Hibernate非常相近。這裡的內容正是基於他的指南，因此所有的感謝都應該給與他。

NHibernate的文檔並非每處都和Hibernate的文檔一致。然而，項目的相似應該能使讀者通過讀Hibernate的文檔來很好的理解NHibernate如何工作。

這篇文檔意在讓你儘可能快的開始使用NHibernate。它將介紹如何持久化一個簡單的對象到一張表裡。想得到更多的複雜的例子，可以參考NUnit測試及附帶代碼。

開發的過程

Nhibernate未來將會提供一些工具協助你自動產生schema檔案（現在還是基於代碼）或是通過對應檔產生類（在籌措階段）或是更新 schema(來自於一個新開發人員的建議)。然而，這裡我們的例子是假定一切來自於完全手寫，包括設定表和.Net類的編寫。我們將進行以下步驟。

1．建立一個將要持久化.Net對象的表

2．構建一個需要被持久化的.Net類

3．構建一個可以讓NHibernate知道如何持久化對象屬性的對應檔

4．構建一個讓NHibernate知道如何串連資料庫的設定檔]

5．使用NHibernate的API

第一步：寫構建表的SQL

這裡我們將使用的是一個非常簡單的例子。假設你正在為你的網站開發一個基本的使用者管理子系統。我們將使用如下的一張User表（假定你已經設定好一個資料庫—在的例子裡我稱它為NHibernate）。

use NHibernate
go
CREATE TABLE users (
LogonID nvarchar(20) NOT NULL default '0',
Name nvarchar(40) default NULL,
Password nvarchar(20) default NULL,
EmailAddress nvarchar(40) default NULL,
LastLogon datetime default NULL,
PRIMARY KEY (LogonID)
)
go
我使用的是MS Sql Server 2000, 但也可以使用任何資料庫，只要你有關於它們的基於.Net資料提供驅動程式。我們將得到一個含有LogonID,Name, Password, Email 和LastLogon的表. 經過以上標準步驟，我們下一步是寫一個.Net類處理一個給定的User對象。

第二步:產生一個.Net 類檔案

當記憶體中有一堆User對象的時候，我們需要某種對象去儲存它們。NHibernate通過對象屬性的反射來工作，因此我們需要添加我們希望持久化的對象屬性。一個可以被NHibernate持久化的類應該看起來象下面的樣子：

using System;
namespace NHibernate.Demo.QuickStart
{
        public class User
        {
               private string id;
               private string userName;
               private string password;
               private string emailAddress;
               private DateTime lastLogon;
               public User()
               {
               }
               public string Id
               {
                       get { return id; }
                       set { id = value; }
               }
               public string UserName
               {
                       get { return userName; }
                       set { userName = value; }
               }
               public string Password
               {
                       get { return password; }
                       set { password = value; }
               }
               public string EmailAddress
               {
                       get { return emailAddress; }
                       set { emailAddress = value; }
               }
               public DateTime LastLogon
               {
                       get { return lastLogon; }
                       set { lastLogon = value; }
               }
        }
}
在上面的例子裡，我們的屬性和構建函數是public，但這個對NHibernate不是必要的.它可以使用public, protected, internal或者甚至是用private來持久化資料。

第三步：寫對應檔

現在我們有資料表和需要去映射它的.Net類。我們需要一種方式去讓NHibernate知道如何從一個映射到另一個。這個任務依賴於對應檔來完成。最易於管理的辦法是為每一個類寫一個對應檔，如果你命名它是YourObject.hbm.xml 並且把它放在和類的同一個目錄裡，NHiberante將會使得事情簡單起來。下面是一個User.hbm.xml的例子：

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.0">
        <class name="NHibernate.Examples.QuickStart.User, NHibernate.Examples" table="users">
               <id name="Id" column="LogonId" type="String" length="20">
                       <generator class="assigned" />
               </id>
               <property name="UserName" column= "Name" type="String" length="40"/>
               <property name="Password" type="String" length="20"/>
               <property name="EmailAddress" type="String" length="40"/>
               <property name="LastLogon" type="DateTime"/>
        </class>
</hibernate-mapping>
讓我們來看看這個檔案中讓我們感興趣的某些行。第一個有趣的標籤是class。這裡我們將映射類型名稱(類名和裝配件)到我們資料庫中的User表，這裡和 Hibernate有一點點的不同。你將不得不告訴NHibernate從何處提取對象。在這個例子裡我們從裝配件 NHibernate.Examples裝載類NHibernate.Examples.QuickStart.User 。NHibernate 遵循和.Net Framework同樣的規則來載入類型。因此如果你在如何指定類型的方面有些混淆，請參看.Net Framework SDK。

讓我們先跳過id標籤，來討論property標籤。簡要看一下，你將發現NHibernate所要做的工作。name屬性的值正是我們.Net 類的屬性，column屬性值將是我們資料庫裡的欄位。type屬性是可選的（如果你不標明，NHibernate將利用反射進行最佳的推測）。

好了，讓我們回到標籤id, 你可以猜測到這個標籤將是映射資料庫表的主鍵，的確如此，id標籤的組成和我們剛才看的property標籤是相似的。我們映射屬性到目標資料庫的欄位。

內嵌的generator 標籤告訴NHibernate 如何產生主鍵（它將恰當的為你產生主鍵，不管你指定何種類型，但你必須告訴它）。在我們的例子裡，我們設定為assigned,意味著我們對象將自己產生主鍵（畢竟User對象常常需要一個UserID）。如果你執意要NHiberante為你產生主鍵，你感興趣於設定uuid.hex和 uuid.string（從文檔中擷取更多資訊）

提示：如果你使用Visual Studio.Net 去編譯的話，請將user.hbm.xml的Build Action屬性設定為Embedded Resource。對應檔將成為裝配件的一部分。更詳細的細節重點將在後面展示。

提示：如果你僅僅是改變對應檔，你不能使用build 而應該Rebuild項目。Visual Studio.Net 不會重新編譯有改變的對應檔。

第四步：為你的資料庫產生一個設定檔

我們至今還沒有告訴NHibernate 去哪裡串連資料庫。最直接的辦法是在你的應用程式的設定檔裡設定一個NHibernate配置節。這和在Hibernate裡使用屬性檔案是等價的。如下配置：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
        <configSections>
               <section name="nhibernate" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0,Culture=neutral, PublicKeyToken=b77a5c561934e089" />
        </configSections>
        <nhibernate>
               <add
                       key="hibernate.connection.provider"         
                       value="NHibernate.Connection.DriverConnectionProvider"
               />
               <add
                       key="hibernate.dialect"                     
                       value="NHibernate.Dialect.MsSql2000Dialect"
               />
               <add
                       key="hibernate.connection.driver_class"         
                       value="NHibernate.Driver.SqlClientDriver"
               />
               <add
                       key="hibernate.connection.connection_string"
                       value="Server=localhost;initial catalog=nhibernate;Integrated Security=SSPI"
               />
        </nhibernate>
</configuration>
上面的例子裡用了SqlClient 驅動，在本地串連名稱為NHibernate 的資料庫，提供使用者名稱和密碼。那裡有一堆屬性你需要調整來確定如何讓NHibernate來訪問資料庫。再次說明，你可以在文檔裡擷取更多資訊。

請注意以上的配置裡並沒有涉及到log4net的配置資訊。NHibernate使用log4net來記錄內部發生的一切。在一個應用程式產品裡，在你特定環境裡，我推薦配置log4net，並為NHibernate設定一定的記錄層級。

第五步：開始展現NHibernate的魔力

所有艱苦的工作已經完成。你將有以下內容

User.cs ----你需要持久化的C#類

User.hbm.xml ----你的NHibernate對應檔

App.config ---對ADO.NET串連的配置資訊（如果你願意，你可以在代碼中實現）。

你的資料庫裡有一張User表。

現在可以在你的代碼中恰當簡潔的使用NHibernate。簡化的版本如下

建立一個Configuration對象
讓Configuration知道你將儲存何種類型的對象
為你選擇的資料庫建立一個Session對象
Load，Save和Query你的對象
通過Session的Flush()方法將對象提交給資料庫。
為了讓你更清晰，我們來看一些代碼。

首先，建立一個Configuration對象

Configuration對象能夠解析所有.Net對象和後台資料庫中的映射關係。

        Configuration cfg = new Configuration();
        cfg.AddAssembly("NHibernate.Examples");
Configuration對象會搜尋裝配件裡的任何以hbm.xml 結尾的檔案。還有其他方法載入對應檔，但這種方式是最簡單的。

下一步，建立一個Session對象

ISession對象提供一個到後台資料庫的串連，ITransaction對象提供一個可以被NHibernate管理的事務。

        ISessionFactory factory = cfg.BuildSessionFactory();
        ISession session = factory.OpenSession();
        ITransaction transaction = session.BeginTransaction();
接著來Load, Save和Query你的對象

現在你可以用使用傳統的.Net方法來操縱對象。你想儲存一個新對象到資料庫嗎？嘗試下面的方法：

        User newUser = new User();
        newUser.Id = "joe_cool";
        newUser.UserName = "Joseph Cool";
        newUser.Password = "abc123";
        newUser.EmailAddress = "joe@cool.com";
        newUser.LastLogon = DateTime.Now;
        // Tell NHibernate that this object should be saved
        session.Save(newUser);
        // commit all of the changes to the DB and close the ISession
        transaction.Commit();
        session.Close();
正如你所看到的，關於NHiberante重要的事情是如此簡單。繼續並且查詢你的資料庫，驗證一下User表裡的新記錄。現在重要的事情就是你去操心業務對象並在進行處理的時候告訴NHibernate就可以了。

讓我們來告訴你，當你有一個UserID的時候如何擷取對象（舉例說，登陸你的網站的時候）。僅僅一句話就可以開啟Session，傳入key就可以了

        // open another session to retrieve the just inserted user
        session = factory.OpenSession();
        User joeCool = (User)session.Load(typeof(User), "joe_cool");
你所擷取的User對象還在生存周期內！改變它的屬性，並通過Flush()持久化到資料庫。

        // set Joe Cool's Last Login property
        joeCool.LastLogon = DateTime.Now;
        // flush the changes from the Session to the Database
        session.Flush();
你所要做的就是通過NHibernate來進行你需要的改變，並調用Session的Flush()方法提交。驗證一下資料庫，查查使用者ID為”joe_cool”的記錄中”LastLogon”的更改。

還有更好的，你可以以System.Collections.IList的方式來擷取從表中的對象。如下

        IList userList = session.CreateCriteria(typeof(User)).List();
        foreach(User user in userList)
        {
               System.Diagnostics.Debug.WriteLine(user.Id + " last logged in at " + user.LastLogon);
        }
這個查詢將會返回所有表記錄。往往你需要做更多的控制，比如說擷取從March 14, 2004 10:00 PM　以後登陸的使用者，如下：
        IList recentUsers = session.CreateCriteria(typeof(User))
                                      .Add(Expression.Expression.Gt("LastLogon", new DateTime(2004, 03, 14, 20, 0, 0)))
                                      .List();
        foreach(User user in recentUsers)
        {
               System.Diagnostics.Debug.WriteLine(user.Id + " last logged in at " + user.LastLogon);
        }
文檔裡還有一堆健壯的查詢方式讓你調用，這裡僅僅讓你對NHibernate所提供的強有力的工具有一定的瞭解。
最後調用Session對象的Close()方法，釋放NHibernate所使用的ADO.Net串連資源
        // tell NHibernate to close this Session
        session.Close();
更確切地說…

你已經完成建立對象，持久化並通過條件查詢或索引值查詢來返回它。相信你已經從中獲得快樂。

現在你對NHibernate有了大致的瞭解，如果你能仔細閱讀大量來自Hibernate 2.0.3文檔,你將獲得協助（NHibernate文檔還在早期階段，現在還僅僅是對Hibernate的拷貝）。

-----------------
在庫檔案中要有

Iesi.Collections.dll

HashCodeProvider.dll

這兩個檔案。不用引用到程式。但nhibernate會使用到。

將他們放在nhibernate相同的目錄下就可以了，系統會尋找後拷貝到bin\debug\下面。當然直接放進去也可以。

另外在設定檔中，主鍵要寫成

<generator class="assigned" />

否則主鍵會加不進去