http://nhibernate.sourceforge.net/quickstart.html
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 master
go
IF EXISTS (SELECT * FROM master.dbo.sysdatabases WHERE name = N'NHibernate')
DROP DATABASE "NHibernate"
GO
CREATE DATABASE "NHibernate"
GO
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从何处提取对象。在这个例子里我们从装配件(最后编译的DLL文件名称)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 去哪里连接数据库。最直接的办法是在你的应用程序的配置文件(App.config)里设置一个NHibernate配置节。配置如下:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="nhibernate" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.5000.0,Culture=neutral, PublicKeyToken=b77a5c561934e089" />
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net" />
</configSections>
<nhibernate>
<add key="hibernate.show_sql" value="true" />
<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=.;initial catalog=nhibernate;Integrated Security=SSPI" />
</nhibernate>
<!-- This section contains the log4net configuration settings -->
<log4net>
<!-- Define some output appenders -->
<appender name="rollingFile" type="log4net.Appender.RollingFileAppender,log4net">
<param name="File" value="log.txt" />
<param name="AppendToFile" value="true" />
<param name="RollingStyle" value="Date" />
<param name="DatePattern" value="yyyy.MM.dd" />
<param name="StaticLogFileName" value="true" />
<layout type="log4net.Layout.PatternLayout,log4net">
<param name="ConversionPattern" value="%d [%t] %-5p %c [%x] <%X{auth}> - %m%n" />
</layout>
</appender>
<!-- Setup the root category, add the appenders and set the default priority -->
<root>
<priority value="ALL" />
<appender-ref ref="rollingFile" />
</root>
</log4net>
</configuration>
上面的例子里用了SqlClient 驱动,在本地连接名称为NHibernate 的数据库,提供用户名和密码。那里有一堆属性你需要调整来确定如何让NHibernate来访问数据库。再次说明,你可以在文档里获取更多信息。
NHibernate使用log4net来记录内部发生的一切。在一个应用程序产品里,在你特定环境里,我推荐配置log4net,并为NHibernate设置一定的日志级别。
你还需要配置hibernate.cfg.xml文件:
<?xml version="1.0" encoding="utf-8" ?>
<hibernate-configuration xmlns="urn:nhibernate-configuration-2.0" >
<session-factory name="NHibernate.Test">
<!-- properties -->
<!--
<property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>
<property name="connection.driver_class">NHibernate.Driver.SqlClientDriver</property>
<property name="connection.connection_string">Server=.;initial catalog=nhibernate;Integrated Security=SSPI</property>
<property name="show_sql">false/property>æ
<property name="dialect">NHibernate.Dialect.MsSql2000Dialect</property>
<property name="use_outer_join">true</property>
<property name="query.substitutions">true 1, false 0, yes 'Y', no 'N'</property>
-->
<!-- mapping files -->
<mapping assembly="NHibernate.Examples" />
</session-factory>
</hibernate-configuration>
因为我还不明白被注释部分的作用,但是我尝试注释后一切正常,但是我保留原样。
第五步:开始展现NHibernate的魔力
所有艰苦的工作已经完成。你将有以下内容
User.cs ----你需要持久化的C#类
User.hbm.xml ----你的NHibernate映射文件(记得编译为嵌入的资源)
App.config ---对ADO.NET连接的配置信息(如果你愿意,你可以在代码中实现)。
你的数据库里有一张User表。
现在可以在你的代码中恰当简洁的使用NHibernate。简化的版本如下
1. 创建一个Configuration对象
2. 让Configuration知道你将存储何种类型的对象
3. 为你选择的数据库创建一个Session对象
4. Load,Save和Query你的对象
5. 通过Session的Flush()方法将对象提交给数据库。
为了让你更清晰,我们来看一些代码。我们使用Nunit来测试我们的代码。
using System;
using System.Collections;
using NHibernate.Cfg;
using NUnit.Framework;
namespace NHibernate.Examples.QuickStart {
[TestFixture]
public class UserFixture {
Configuration cfg;
ISessionFactory factory ;
readonly string userId="test_user";
//准备测试前的工作
[SetUp]
public void SetUp() {
//Configuration对象能够解析所有.Net对象和后台数据库中的映射关系。
cfg = new Configuration();
//Configuration对象会搜索装配件里的任何以hbm.xml 结尾的文件,前提是
//*.hbm.xml要编译为“嵌套的资源”
cfg.AddAssembly("NHibernate.Examples");
factory = cfg.BuildSessionFactory();
}
[TearDown]
public void TearDown() {
//清除一些操作中生成的临时数据
}
/// <summary>
/// 清除数据库中Users表中的所有数据,提供一个干净的测试数据环境
/// </summary>
[Test]
public void ClearData() {
//ISession对象提供一个到后台数据库的连接,参数由App.config指定
//ITransaction对象提供一个可以被NHibernate管理的事务。
ISession session = factory.OpenSession();
ITransaction transaction = session.BeginTransaction();
//使用查询删除所有数据
session.Delete("Select From User Where 1=1");
transaction.Commit();
session.Close();
}
/// <summary>
/// 测试往数据库中添加一个对象
/// </summary>
[Test]
public void AddTest() {
ISession session = factory.OpenSession();
ITransaction transaction = session.BeginTransaction();
User newUser = new User();
newUser.Id = userId;
newUser.UserName = "SkyDev";
newUser.Password = "abc123";
newUser.EmailAddress = "skydev@pyp.edu.cn";
newUser.LastLogon = DateTime.Now;
session.Save(newUser);
transaction.Commit();
session.Close();
}
/// <summary>
/// 更新数据库中的对象
/// </summary>
[Test]
public void UpdateTest() {
ISession session = factory.OpenSession();
ITransaction transaction = session.BeginTransaction();
User aUser;
try {
//当userId指定的数据在数据库中不存在时会抛出异常
aUser= (User)session.Load(typeof(User), userId);
// set Joe Cool's Last Login property
aUser.LastLogon = DateTime.Now;
// flush the changes from the Session to the Database
session.Flush();
transaction.Commit();
}
catch {
transaction.Rollback();
}
finally {
session.Close();
}
}
/// <summary>
/// 删除指定的对象
/// </summary>
[Test]
public void DeleteTest() {
ISession session = factory.OpenSession();
ITransaction transaction = session.BeginTransaction();
User aUser;
try {
//当userId指定的数据在数据库中不存在时会抛出异常
aUser = session.Load(typeof(User), userId) as User;
if (aUser!=null) {
session.Delete(aUser);
}
transaction.Commit();
}
catch {
transaction.Rollback();
}
finally {
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的拷贝)。
Enjoy! And Happy NHibernating!
Mike Doerfler
再次说明,所有的权利来自Glen Smith的A Hitchhiker's Guide to Hibernate
Translated by: Jason Xie
Published: 2005-02-24
本文当改编自http://nhibernate.sourceforge.net/quickstart.html的翻译稿,修正其中的一些不明确的地方,参考修改后的文档,你应该能真正的做到QuickStart,因为我也是今天第一次使用Nhibernate,虽然以前接触过Hibernate但是不是很熟悉,我花了一点点时间总结出来供大家参考。
最后修改:2005-8-5
曾青松
Email:QS1976@126.com