[原]iBatis.Net（C#）系列一：简介及运行环境

转载请注明http://www.cnblogs.com/13590/archive/2013/02/27/2934580.html

摘要：介绍iBatis.Net的基本情况和运行原理，运行环境中各参数的配置情况，并通过一个实例项目，详细讲解通过VS2012建立的C#项目中如何使用iBatis.Net。

关键词：iBatis.Net；C#语言；运行环境；实例

1 iBatis.Net简介

iBatis一词来源于"internet"和"abates"的组合，是一个由Clinton Begin在2001年发起的开放源代码项目，现已成为以SQL为中心的持久化层框架。IBatis.Net是从iBatis的Java版本移植过来的.NET版本。目前项目地址为：http://code.google.com/p/mybatisnet/，可以通过项目网站下载其源代码。

iBatis提供的持久层框架包括SQL Maps和Data Access Objects（DAO），其中最主要的是SQL Maps。和其它对象关系映射ORM，如Hibernate和Spring等"一站式"对象关系映射解决方案而言，iBatis则是一种"半自动化"的对象关系映射实现，它允许程序员自己控制SQL语句，为系统设计提供了更大的自由空间。

(1)SQL Maps

SQL Maps是这个框架中最重要的部分，它是整个iBATIS Database Layer的核心价值所在。通过使用SQL Maps你可以显著的节约数据库操作的代码量。SQL Maps使用一个简单的XML文件来实现从实体到SQL语句的映射。跟其它的框架或者对象关系映射工具相比，SQL Maps最大的优势就是简单。同时它需要学习的东西很少，在连接表或复杂查询时也不需要复杂的模式，使用SQL Maps，你可以自由的使用SQL语句。这种独特的数据映射模式（即Data Mapper），使用SQL映射的方式将对象持久化至关系型数据库。简单的理解就是它将我们在数据访问层实现的C#逻辑代码，变为通过关系数据库与对象的映射来实现，并将SQL逻辑放到外部的XML配置文件中，以方便以后的维护。

(2)Data Access Objects (DAO)

Data Access Objects允许你通过一个简单接口的来操作数据，从而隐藏了实现的细节。使用DAO，你可以动态配置你的应用程序来访问不同的实体存储机制。实际上DAO通过一个通用的API层把具体操作数据的细节封装了起来，使我们不再关心操作数据的细节，而把中心放在业务逻辑上，避免了ADO.NET的复杂性。如果你有一个复杂的应用需要用到几个不同的数据库，DAO可以让你建立一个一致的API，让系统的其他部分来调用。实现了应用系统的数据库无关性，是不是有点工厂模式的味道。

2 SQL Maps原理

提到SQL Maps原理，不得不提到官方帮助文档给出的一副图，如图1：

图1 iBatis的数据映射工作流程图

该图清晰的反映了iBatis的数据映射工作流程。左边是输入参数，中间为记录在sqlMap.xml文件里面的SQL映射语句被SQL Maps组件通过SqlMap.config配置文件读入，通过组件内封装的ADO.NET和数据库进行交互。输出右边的结果对象。

整个开发的重点就在XML描述的编写上，其他的工作由SQL Maps组件来完成，基本的步骤如下：

(1) 程序输入一个参数，无论是对象还是一个原生类型。参数将被用于设置SQL语句或存储过程的运行时的值

(2) 通过传送参数和在XML描述中的声明名字或者存储过程来执行映射。这一步将是关键的步骤。iBatis框架将会准备SQL语句声明或者存储过程，用参数设置运行时数据值，即带入运行数据值，执行SQL语句或者存储过程，返回结果。

(3) 和ADO.NET一样，当数据更新的时候，更新的行数将会被返回。当数据查询的时候，返回的将是一个对象或者对象的集合。结果对象或者对象的集合，可以是一个普通对象或者原生类型，通过XML描述中的参数来指定。

3 运行环境

iBatis基本的运行环境配置主要由两个文件组成，分别是SqlMap.config和providers.config。它们是必需的两个配置文件，基中SqlMap.config的功能类似于应用程序的web.config或者app.config，是iBatis核心的配置文件，靠他把XML描述文件载入给iBatis框架。默认情况下，需要把该文件放在应用程序的运行目录下并且保留它的文件名称。如果改变名称或者存放在其他目录，需要在程序里面额外手工指定。

providers.config是一个数据驱动提供类的配置文件，提供了如常见的Oracle、Sql Server、OleDb、Odbc、MySql和Informix等数据库的数据驱动，其他数据库可以通过增加相应的配置来添加。

SqlMap.config的结构如图2，包括以下一些主要的配置节，根据需要，有的配置节并不是必须的：

图2 SqlMap.config内容

(1) settings：包括有三个配置段：
<setting useStatementNamespaces="false"/> 
<setting cacheModelsEnabled="true"/>
<setting validateSqlMap="false"/>
useStatementNamespaces：是否使用语句命名空间，这里的命名空间指的是映射文件中sqlMap节点的namespace属性。即如果该参数设为"true", 语句调用时需追加命名空间，如：mapper.Update("TestApp.UpdatePost",post)；否则直接通过语句名称调用即可，如mapper.Update("UpdatePost",post)。但这时一定要注意，此时需要保证所有映射文件中语句定义没有重名。可以通过变量来指定该参数设置，如：<setting useStatementNamespaces="${useStatementNamespaces}"/>，参数通过properties属性来指定，该值默认为"false"。

cacheModelsEnabled：配置是否启用iBatis的缓存机制，默认是"true"。

validateSqlMap：配置是否启用SqlMapConfig.xsd schema验证映射文件，默认是"false"。

(2) providers ：配置数据驱动提供类配置文件的路径和文件名。可以通过resource（或url、embedded，它们分别是引用url和编译在程序中的资源文件）属性引用进来。如：<providers resource="providers.config"/>，这三种载入方法说明如下：

参数	描述
resource	指定数据驱动配置文件从项目的根目录进行加载，如resource="providers.config"
url	指定数据驱动配置文件从文件的绝对路径进行加载，如url="c:\IBatis\Resources\providers.config" -或者- url="file://c:\IBatis\Resources\providers.config"
embedded	指定数据驱动配置文件可以作为程序集的资源文件进行加载，如embedded="Resources.providers.config, MyApp.Data"

凡涉及到引用外部文件的都可以通过以上resource，url，embedded 三种方式实现。

(3) database ：数据库的信息，包括使用哪些数据库驱动和数据库连接字符串的配置。provider参数定义数据库访问所使用的provider.config文件定义的provider；dataSource参数定义特定的数据库连接字符串。

(4) sqlMaps ：指定XML映射文件的位置，配置中可以出现多个sqlMap节点，以指定项目内所包含的所有映射文件。如通过embedded方式指定<sqlMap embedded="sqlFile.xml, ConsoleApplication1" />。

(5) properties ：配置一些常量属性，如：<property key="useStatementNamespaces" value="false"/>。如果这些属性有很多的话可以单独写一个文件里面，再通过resource（或url, embedded分别是引用url和编译在程序中的资源文件）属性引用进来

(6) alias ： 类型别名的配置，为了使用更方便的使用类（类名更短），就需在这里进行别名的配置。如<alias><typeAlias alias="YesNoBool" type="IBatisNet.Test.Domain.YesNoBoolTypeHandlerCallback, IBatisNet.Test"/></alias>

(7) typeHandlers ：定义数据库类型到dotnet数据类型的处理，不同的数据库都有一些特殊的数据库字段类型需要特殊处理，就可以通过这个功能实现。通过它为该类型取一个名字，并且指定对应的.NET类型来处理它。如 <typeHandlers> <typeHandler type="bool" dbType="Varchar" callback="YesNoBool"/> </typeHandlers>

以上就是Sqlmap.config的基本内容了。Provider.config文件的配置信息相对就很简单，IBatis.Net使用的是插件式结构来使用这些数据库提供程序，每一个Provider对应于providers.config文件中定义的一个provider项。提供程序要求安装相关类库，每一个provider元素都有"enabled"属性来控制是否启用这个providers。

4 日志处理

IBatis框架具有和Apache Log4Net一样的内部日志机制，记录了与数据库的交互情况。可以使用框架内置的三个记录器（NoOpLogger, ConsoleOutLogger, TraceLogger) ，或者使用像Apache Log4Net一样的外置记录包。为了让IBatis记录器工作, 必须在配置文件里 (App.Config 或者 Web.Config)配置一些节点：

注册IBatis日志处理节点和log4net节点

<configSections>

<sectionGroup name="iBATIS">

<section name="logging" type="IBatisNet.Common.Logging.ConfigurationSectionHandler, IBatisNet.Common" />

</sectionGroup>

<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />

</configSections>

配置IBatis节点

<iBATIS>

<logging>

<logFactoryAdapter type="IBatisNet.Common.Logging.Impl.Log4NetLoggerFA, IBatisNet.Common.Logging.Log4Net">

<arg key="configType" value="inline"/>

</logFactoryAdapter>

</logging>

</iBATIS>

注意"<arg key="configType" value="inline" />",其Value值可以有以下几个选项：

inline ：log4net 节点在App.Config或者Web.Config 文件中配置。

file：使用外置配置文件，需要configFile参数配合使用，<arg key="configFile" value="外部配置文件"。

file-watch: 与"file"一样，只是多了一个监视外部配置文件的变动功能，如果有变动则重新加载配置。

external：IBatis将不会尝试配置Log4Net。

需要特别注意一下,如果采用file-watch 外部文件配置的方式时，configFile 必须用绝对路径，不能使用相对路径。

以采用inline方式为例，我们只需要在App.config或者Web.Config中配置log4net节点，如下：

<log4net>

<appender name="FileAppender" type="log4net.Appender.FileAppender">

<file value="log.txt" />

<appendToFile value="true" />

<layout type="log4net.Layout.SimpleLayout" />

</appender>

<root>

<level value="ALL" />

<appender-ref ref="FileAppender" />

</root>
</log4net>

5 例子程序

官网上新加了一个例子程序ConsoleApplication1，可以下载来学习。为了使大家一步一步更明白项目建立过程，我们新建立一个例子程序。该例子程序功能为：通过网页输入查询参数，程序通过iBatis查询Oracle数据库信息，并把结果返回显示在页面上。

(1)建立项目

打开Visual Studio 2012，新建立一个ASP.NET Empty Web Application项目iBatisTest，Framework框架选4.0。

(2)添加引用

通过官方网站下载"IBatis.DataMapper.1.6.2.bin.zip"并解压，在项目中添加下面dll的引用：IBatisNet.Common.dll和IBatisNet.DataMapper.dll。因为要访问Oracle数据库，还需要在项目中引入System.Data.OracleClient.dll。

(3)添加IBatis环境配置文件

把解压目录下的providers.config和sample.SqlMap.config拷贝到项目根目录，并把sample.SqlMap.config改名为SqlMap.config，把两个文件加入项目。本例子程序采用"System.Data.OracleClient"连接Oracle数据库，打开providers.config，找到名称为"oracleClient1.0"，修改enabled参数为"true"启用该数据库驱动配置。

(4) 建立表

在Oracle数据库中建立xxzx.post表，脚本如下：

CREATE TABLE XXZX.POST

(

ID NUMBER(10,0),

USERNAME VARCHAR2(100),

POSTTIME DATE

);

插入测试数据，insert into XXZX.POST (id,username,posttime)values(10,'管理员',sysdate);

(5)添加XML映射描述文件

向项目新增XML文件Post.xml，修改XML文件内容，如图3所示

图3 XML映射文件

(6)编写调用程序

向项目新增Web Form文件default.aspx，在页面添加控件，如图4

图4 Web页面

在default.aspx.cs增加IBatisNet.DataMapper的using应用。增加查询按钮控件事件，代码如下：

protected void Button1_Click(object sender, EventArgs e)

{

ISqlMapper mapper = Mapper.Instance();//得到ISqlMapper实例

int para = Convert.ToInt32(TextBox1.Text);

string str = mapper.QueryForObject<string>("GetPostByID", para); //调用QueryForObject方法

Label1.Text = str;

}

编译项目，特别注意，因为是64位操作系统下，安装的Oracle客户端也是64位，需要修改调试环境，采用操作系统IIS来调试。具体操作为，打开项目属性栏，选择Web选项卡，去掉Use IIS Express选项。Project Url栏输入http://localhost/iBatisTest。

运行项目时还是会提示数据库驱动程序不对，这是因为安装的System.Data.OracleClient.dll版本和providers.config中记录的版本不一致，通过Assembly读取System.Data.OracleClient.dll文件FullName,并把该值填入providers.config文件oracleClient1.0驱动的assemblyName参数。读取代码如下：

Label2.Text = System.Reflection.Assembly.LoadFile(@"E:\IBatis.Net\文章\iBatisTest\iBatisTest\System.Data.OracleClient.dll").FullName;

运行程序，在ID值框里面输入"10"，点击查询按钮，就会返回正确的查询值，结果如图5：

图5 程序运行界面

(7)增加日志记录

加入IBatisNet.Common.Logging.Log4Net.dll引用，根据IBatis日志处理机制，在web.config文件里面注册IBatis日志处理节点和log4net节点，配置IBatis节点和log4net，注意注册IBatis日志处理节点和log4net节点需放在是根 <configuration> 元素的第一个子元素。

再次运行并执行程序，在根目录就会生成log.txt文件，文件里面记录的IBatis运行是的调试信息，内容如图6所示：

图6 日志内容

一个完成的例子程序就完成了，以上程序在Windows7(64位)+VS2012+Oracle 11g(64位)上测试通过。通过例子程序我们可以看出，只要配置好XML映射文件，程序调用时只需要简单的几行代码就可以实现对数据库的查询操作，大大的简化了对ADO.NET的操作。这也是IBatis给我们带来的便捷和高效。