4. .NET Data Provider 驱动介绍与应用程序结构说明
4.1. .NET 驱动介绍
本章节介绍KingbaseES的 .NET 驱动提供的几个基本功能类。
4.1.1. KdbndpConnection 类
KdbndpConnection 类用于与 KingbaseES 数据库服务器之间的连接,相当于 ADO Connection 类,它起到渠道的作用。其他的类实体对象,比如 KdbndpDataAdapter 和 KdbndpCommand,通过 KdbndpConnection 与 KingbaseES 数据库服务器通信,以提交查询并获取查询结果。
KdbndpConnection 类使用连接字符串 “ConnectionString” 与 KingbaseES 数据库服务器建立连接。最简单的连接形式参见 KdbndpConnection示例 。
ConnectionString 可以指定大量参数,以指定该连接与数据库连接时的行为。ConnectionString 中可以指定的选项如下:
Server 或 Host
KingbaseES 数据库服务器的地址,IP 地址支持 IPv4 与 IPv6。两个参数的意义相同,这两个参数必须指定一个。
Port
与服务器连接的端口。默认为 54321。
Protocol
指定与服务器连接使用的协议号。默认为 3。
Database
指定要连接的数据库名。该参数必须指定。
User Id
数据库用户名
Password
与数据库用户名对应的密码。
SSL
指定是否使用 SSL 连接。可取值为 True 和 False。默认为 False。
Pooling
指定是否使用连接池。可取值为 True 和 False。默认为 True。
MinPoolSize
连接池中最少连接数。默认为 1。
MaxPoolSize
连接池中最大连接数,超过该数字则新建连接失败。默认为 20。
Encoding
总是使用 “UTF8” ,并且忽略对该选项设置的新值。
Timeout
连接等待的最大时间值,该时间内未连接成功则出错返回。单位为秒,默认为 15。
CommandTimeout
命令执行的最大时间,超时则抛异常。单位为秒,默认为 20。
SSLmode
SSL 连接的模式,下列几种模式之一,默认为 Disable。
Prefer:如果能用 SSL 建立连接,则使用 SSL 连接。
Require:如果 SSL 不能建立连接,则抛异常返回。
Allow:目前不支持,使用一般连接代替。
Disable:不使用 SSL 连接。
ConnectionLifeTime
超出该时间,连接池中不再使用的连接会被取消。单位为秒,默认为 15。
SyncNotification
指示驱动是否使用同步通知。可取值为 True 和 False。默认为 False。
SearchPath
指定默认搜索位置。默认为 PUBLIC。
Preload Reader
是否在执行 ExecuteReader 之前返回结果。可取值为 True 和 False。默认为 False。
该类还提供了其它一些与连接有关的方法。比如,支持事务操作(BeginTransaction())支持连接状态检查(Conn.State),支持连接克隆(Clone()方法),支持更换数据库(ChangeDatabase()方法),支持查询服务器版本信息(KingbaseESVersion()方法)等。
4.1.2. KdbndpCommand 类
KdbndpCommand 类可以支持对 KingbaseES 数据库服务器的查询、对存储过程的调用、要求返回特定表内容的直接请求。
KdbndpCommand 类支持多种不同类型的查询。使用 KdbndpCommand 类非常简单,先创建 KdbndpConnection 对象,再创建 KdbndpCommand 对象,并设置 KdbndpCommand 对象的 Connection 属性为 KdbndpConnection 对象,然后在 CommandText 属性中指定查询文本即可。
KdbndpCommand 类还提供表,视图,用户自定义函数和存储过程的确切名字,并使用 KdbndpCommand 类的 CommandType 属性设置需要执行的查询类型。
KdbndpCommand 类还提供了多种不同的 SQL 命令执行方式。主要分为以下几种:
ExecuteNonQuery() 方法
如果 KdbndpCommand 中的 SQL 命令不需要返回结果,则使用该方法执行这样的SQL命令。
ExecuteScalar() 方法
执行查询,并返回查询返回的结果集中第一行的第一列。 额外的列或行将被忽略。如果结果集为空,则为返回空引用。
ExecuteReader() 方法
KdbndpCommand 中的 SQL 命令返回多条记录,则需要调用该方法,用户可以使用 while() 之类的循环逐条处理返回结果。通常情况下,可以将某一查询与内存中的 DataSet 类建立映射表,从而用户可以批量对内存中的数据进行处理或更新,最后再批量更新至数据库中,从而提高效率。但这种处理方法有一个缺陷,就是取回数据后,应用程序就与数据库服务器断开连接,在将更新写回数据库前可能有其它应用程序更新了原始数据,即提高并发度的同时增加了数据库的潜在的不一致性。所以,通常 DataSet 应用于更新较少但处理的数据量较大的场合。
KdbndpCommand 类支持用户自定义函数和存储过程的调用,支持集合类型的返回值,支持 SQL 语句中的用户自定义的参数,支持查询预处理。
4.1.3. KdbndpParameter 类
开发者在开发中,一般都倾向于使用参数化的查询,因为参数化的查询有助于简化编程,并生成更有效的代码。使用参数化的 Command 对象,先要为查询中的每一个参数创建一个 Parameter 对象,并设置合适的类型,赋予正确的值,最后再加到 Command 对象的 Parameters 集合中。要使用那些通过输出参数 (out,inout) 返回数据的存储过程和函数,可通过 ParameterDirection 枚举将 Parameter 对象的 Direction 属性设置为相应的值。
KdbndpParameter 类提供了相当丰富的构造函数,以方便用户添加不同类型的参数。
当使用 KdbndpDbType 时,需要添加对 KdbndpTypes 命名空间的引用。
public KdbndpParameter()
public KdbndpParameter(String , object )
public KdbndpParameter(String , KdbndpDbType )
public KdbndpParameter(String , DbType )
public KdbndpParameter(String , KdbndpDbType , Int32 )
public KdbndpParameter(String , DbType , Int32 )
public KdbndpParameter(String , KdbndpDbType , Int32 , String )
public KdbndpParameter(String , DbType , Int32 , String )
public KdbndpParameter(String , KdbndpDbType , Int32 , String , ParameterDirection , bool , byte , byte , DataRowVersion , object )
public KdbndpParameter(String , DbType , Int32 , String , ParameterDirection , bool , byte , byte , DataRowVersion , object )
KdbndpCommand 对象中 SQL 命令的参数以 “:” 和 “@” KdbndpParameter 对象根据用户指定的数据类型,对 SQL 命令中对应参数执行替换操作,并根据需要决定是否使用强制类型转换。
使用示例请参见 KdbndpParameter示例 。
4.1.4. KdbndpDataReader 类
KdbndpDataReader 类用于以最快的速度检索并检查查询所返回的行。可使用 KdbndpDataReader 对象来检查查询返回的结果,一次查询一行。当移向下一行时,前一行的内容就会丢弃。 KdbndpDataReader 对象不支持更新操作,由它所返回的数据是只读的。由于 KdbndpDataReader 支持最小特性集,所以它的速度非常快,而且是轻量级的。
KdbndpDataReader 的使用参见 KdbndpDataReader示例 。
4.1.5. KdbndpDataAdapter 类
KingbaseES .NET Data Provider 提供了与 KingbaseES 数据库服务器进行连接的类库,System.Data 命名空间中的 DataSet 类则提供了非连接查询的属性和操作集合。
KdbndpDataAdapter 类提供了 KingbaseES .NET Data Provider 类库与 DataSet 类之间进行交互的功能。KdbndpDataAdapter 对象充当 KingbaseES 数据库服务器与 ADO.NET 对象模型中的非连接对象 DataSet 对象之间的桥梁。
KdbndpDataAdapter 对象的 Fill 方法提供了将查询结果导入 DataSet 或 DataTable 的有效机制,从而使得应用程序可以脱机处理数据。同时,应用程序还可以通过 KdbndpDataAdapter 对象向 KingbaseES 数据库服务器提交存储在 DataSet 对象中的更改。
KdbndpDataAdapter 对象的 SelectCommand 属性实际上表明了要从数据库中导入到 DataSet 中的数据行,即 SelectCommand 中 "select SQL" 命令执行返回的结果。
KdbndpDataAdapter 对象包括 UpdateCommand,InsertCommand 和 DeleteCommand 属性,分别与应用程序用来向 KingbaseES 数据库服务器提交修改的数据行,新建数据行和删除数据行的 KdbndpCommand 对象相对应。
KdbndpDataAdapter 对象会填充 DataSet 对象中的表,而且也能读取缓存在 DataSet 中的更改,并提交给数据库。 KdbndpDataAdapter 有一些支持属性可跟踪在什么位置发生了什么操作。
KdbndpDataAdapter 的使用参见 KdbndpDataAdapter示例 。
4.1.6. KdbndpTransaction 类
KdbndpTransaction 对象可以将一系列的 SQL 操作定义为一个事务,从而保证该事务内部的所有操作要么都成功执行,要么都不执行,保证数据的一致性和原子性。
KdbndpTransaction 用来创建 Transaction 对象。该对象可用来在 Transaction 对象的生存期提交或取消对数据库所做的更改。
KdbndpTransaction 的使用参见 KdbndpTransaction示例 。
4.2. .NET 应用程序结构说明
使用 KingbaseES .NET Data Provider 连接 KingbaseES 数据库的应用程序,一般可分为以下几个部分:
-
KdbndpConnection.Open()
-
KdbndpCommand 或 KdbndpCommandBuilder
-
KdbndpParameter
-
KdbndpCommand.Execute(xxx)([xxx])
-
KdbndpDataReader 或 KdbndpDataAdapter
-
KdbndpConnection.Close
具体说明如下:
-
创建一个与 KingbaseES 数据库进行连接的 KdbndpConnection 对象,可以根据需要通过设置不同的 ConnectionString 来设置连接类型。 连接参数信息具体参考 KdbndpConnection示例 。
-
打开刚建立的连接。
-
创建一个 KdbndpCommand 对象,设置其 Connection 属性为刚建立的连接。
-
KdbndpCommand 对象的 CommandText 属性可以指定各种用户查询。如果要在 KdbndpCommand 对象中指定参数,则需要在 CommandText 中标记参数,并为每个参数新建一个 Parameter 对象,同时指定 Parameter 对象的各种属性。
-
SQL 命令的执行按其命令的不同形式,及用户期望的返回结果,可以调用不同的命令执行方式。
-
对于返回值为结果集类型的,可创建一个 KdbndpDataReader 对象进行逐行读取。
-
对于希望对数据进行脱机处理的,可创建一个 KdbndpDataAdapter 对象进行 KdbndpConnection 连接对象与 DataSet 之间的通信。
-
-
处理完所有操作后需要关闭与 KingbaseES 数据库服务器的连接。