MySQL Connector/NET包括对下述事宜的完整支持:
· MySQL 5.0特性(存储程序等)。
· MySQL 4.1特性(服务器端的精制语句、Unicode、以及共享内存访问等)。
· 大信息包支持,可发送和接收高达2GB的行和BLOB。
· 协议压缩,允许压缩客户端和服务器之间的数据流。
· 支持使用CP/IP套接字、命名管道、以及Windows共享内存的连接。
· 支持使用CP/IP套接字、或Unix套接字的连接。
· 支持由Novell开发的开放源码Mono框架。
· 可完全管理,不利用MySQL客户端库。
MySQL Connector/NET的开发人员高度尊重用户在软件开发过程中提供的帮助。如果你发现MySQL Connector/NET缺少对你来说很重要的某些特性,或者如果你发现了缺陷,请使用我们的MySQL缺陷系统请求该特性或通报问题。
通过http://forums.mysql.com上的论坛以及http://lists.mysql.com上的邮件列表,可找到针对MySQL Connector/NET的社区支持信息。MySQL AB公司提供付费支持,更多信息请参见http://www.mysql.com/support/。
本文档的目的是作为MySQL Connector/NET的用户指南,而不是语法参考。如果你打算了解详细的语法信息,请阅读MySQL Connector/NET分发版中提供的Documentation.chm文件。
26.2.2. 下载并安装MySQL Connector/NET
MySQL Connector/NET能够运行在任何支持.NET框架的平台上。.NET框架主要被最近的Microsoft Windows版本支持,通过由Novell开发的Mono框架,在Linux上也支持它(请参见http://www.mono-project.com)。
MySQL Connector/NET可通过使用Windows Installer (.msi)安装软件包进行安装,使用该软件包,可在任何Windows操作系统上安装MySQL Connector/NET。MSI软件包包含在名为mysql-connector-net-version.zip的压缩文件中,其中,“version”(版本)指明了MySQL Connector/NET的版本。
可从下述网站下载MySQL Connector/NET:http://dev.mysql.com/downloads/connector/net/1.0.html。
随着Windows XP的发布,Windows Installer(安装器)引擎也予以了更新,对于使用旧版本的用户,可参阅该Microsoft知识库文章以了解升级至最新版本的更多信息。
要想安装MySQL Connector/NET,请右击MSI文件并选择“安装”。在安装器提示你完成安装参数选择后,安装将自动开始。对于大多数用户,建议采用典型安装。
如果在运行安装器时遇到问题,可下载不带安装器的ZIP文件。该文件名为mysql-connector-net-version-noinstall.zip。使用ZIP程序,将其解压至你所选择的目录。
除非作了其他选择,否则MySQL Connector/NET将被安装到“C:\Program Files\MySQL\MySQL Connector Net X.X.X”,其中,“X.X.X”是你所安装的MySQL Connector/NET的版本号。新安装不会覆盖已有的MySQL Connector/NET版本。
下面介绍了MySQL Connector/NET的主要类:
· MySqlCommand:代表对MySQL数据库进行执行操作的SQL语句。
· MySqlCommandBuilder:自动生成单个表的命令,用于协调对DataSet所作的更改和相关的MySQL数据库。
· MySqlConnection:代表与MySQL服务器数据库的开放式连接。
· MySqlDataAdapter:代表一组数据命令和数据库连接,用于填充数据库和更新MySQL数据库。
· MySqlDataReader:提供了从MySQL数据库读取行的“仅正向”流的一种方式。
· MySqlException:当MySQL返回错误时抛出的异常。
· MySqlHelper:助手类,能使工作变的更简单。
· MySqlTransaction:代表将在MySQL数据库中进行的SQL事务。
在后续段落中,将分别介绍这些对象。这些章节的目的是概要介绍MySQL Connector/NET的主要类,而不是语法参考。如果你打算了解详细的语法信息,请阅读MySQL Connector/NET分发版中提供的Documentation.chm文件。
26.2.3.1. MySqlCommand类
MySqlCommand类代表对MySQL数据库进行执行操作的SQL语句。
注释:在以前的版本中,采用符号“@”来标识SQL中的参数。它与MySQL用户变量不兼容,因此,现采用符号“?”来定位SQL中的参数。为了支持早期代码,也可以在连接字符串中设置“old syntax=yes”。如果进行了这类设置,请注意,如果无法定义希望在SQL中使用的参数(定义失败),不会给出异常提示。
· CommandText:获取或设置将在数据源上执行的SQL语句。
· CommandTimeout:获取或设置中止执行命令并生成错误之前应等待的时间。
· CommandType:获取或设置值,该值指明了解释CommandText的方式。可能的值包括StoredProcedure、TableDirect和Text。
· Connection:获取或设置该MySqlCommand实例使用的MySqlConnection。
· IsPrepared:如果该命令已准备好,为“真”,否则为“假”。
· Parameters:获取MySqlParameterCollection。
· Transaction:获取或设置MySqlTransaction,MySqlCommand将在其中执行。
· UpdatedRowSource:当DbDataAdapter的Update方法使用它时,用于获取或设置命令结果作用在DataRow上的方式。
26.2.3.1.2. 方法
· Cancel:尝试取消MySqlCommand的执行。不支持该操作。
· Clone:创建该MySqlCommand对象的克隆对象。包括CommandText、Connection和Transaction属性,以及整个参数列表。
· CreateParameter:创建MySqlParameter对象的新实例。
· Dispose:处理该MySqlCommand实例。
· ExecuteNonQuery:根据连接情况执行SQL语句,并返回受影响的行数。
· ExecuteReader:将CommandText发送给Connection,并创建MySqlDataReader。
· ExecuteScalar:执行查询,并返回查询操作所返回的结果集中第1行的第1列。多余的列或行将被忽略。
· Prepare:在MySQL服务器的1个实例上创建命令的预制版本。
26.2.3.1.3. 用法
在下例中,介绍了在VB.NET中使用MySqlCommand类的方法:
Public Sub InsertRow(myConnectionString As String) ' If the connection string is null, use a default. If myConnectionString = "" Then myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass" End If Dim myConnection As New MySqlConnection(myConnectionString) Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)" Dim myCommand As New MySqlCommand(myInsertQuery) myCommand.Connection = myConnection myConnection.Open() myCommand.ExecuteNonQuery() myCommand.Connection.Close() End Sub
在下例中,介绍了在C#中使用MySqlCommand类的方法:
public void InsertRow(string myConnectionString) { // If the connection string is null, use a default. if(myConnectionString == "") { myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"; } MySqlConnection myConnection = new MySqlConnection(myConnectionString); string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"; MySqlCommand myCommand = new MySqlCommand(myInsertQuery); myCommand.Connection = myConnection; myConnection.Open(); myCommand.ExecuteNonQuery(); myCommand.Connection.Close(); }
MySqlDataAdapter不会自动生成所需的SQL语句(用于协调对DataSet所作的更改和相关的MySQL实例)。但是,如果设置了MySqlDataAdapter的SelectCommand属性,可以创建MySqlCommandBuilder对象来自动生成针对单个表更新的SQL语句。随后,MySqlCommandBuilder将生成你未设置的任何附加的SQL语句。
一旦你设置了DataAdapter属性,MySqlCommandBuilder会将自己注册为针对OnRowUpdating事件的监听程序。一次只能将1个MySqlDataAdapter或MySqlCommandBuilder对象关联起来。
为了生成INSERT、UPDATE或DELETE语句,MySqlCommandBuilder使用了SelectCommand属性来自动检索所需的元数据集合。如果在检索完元数据后更改了SelectCommand(例如首次更新后),应调用RefreshSchema方法来更新元数据。
SelectCommand也必须返回至少1个主键或唯一列。如果未显示任何返回信息,将生成InvalidOperation异常,而且不会生成命令。
MySqlCommandBuilder还会使用SelectCommand引用的Connection、CommandTimeout和Transaction属性。如果更改了这些属性中的任何1个,或者,如果替换了SelectCommand本身,用户应调用RefreshSchema。如不然,InsertCommand、UpdateCommand和DeleteCommand属性将保持它们以前的值。
如果调用了Dispose,MySqlCommandBuilder将解除与MySqlDataAdapter的关联,已生成的命令将不再使用。
可用属性如下:
· DataAdapter:MySqlCommandBuilder将自己注册为针对RowUpdating事件的监听程序,RowUpdating事件是由在该属性中指定的MySqlDataAdapter生成的。创建了新的MySqlCommandBuilder实例时,将释放任何已有的与MySqlDataAdapter关联的MySqlCommandBuilder。
· QuotePrefix, QuoteSuffix:MySQL中的数据库对象能够包含特殊字符,如空格等,这会使得正常的SQL字符串无法解析。使用QuotePrefix和QuoteSuffix属性,MySqlCommandBuilder能够创建处理该问题的SQL命令。
可用方法如下:
· DeriveParameters:从MySqlCommand指定的存储程序中检索参数信息,并填充所指定MySqlCommand对象的参数集。目前不支持该方法,这是因为MySQL中未提供存储程序。
· GetDeleteCommand:获取用于在数据库上执行删除操作所需的、自动生成的MySqlCommand对象。
· GetInsertCommand:获取用于在数据库上执行插入操作所需的、自动生成的MySqlCommand对象。
· GetUpdateCommand:获取用于在数据库上执行更新操作所需的、自动生成的MySqlCommand对象。
· RefreshSchema:刷新用于生成INSERT、UPDATE或DELETE语句的数据库方案信息。
在下例中,介绍了在VB.NET中使用MySqlCommandBuilder类的方法:
Public Shared Function SelectRows(myConnection As String, mySelectQuery As String, myTableName As String) As DataSet Dim myConn As New MySqlConnection(myConnection) Dim myDataAdapter As New MySqlDataAdapter() myDataAdapter.SelectCommand = New MySqlCommand(mySelectQuery, myConn) Dim cb As SqlCommandBuilder = New MySqlCommandBuilder(myDataAdapter) myConn.Open() Dim ds As DataSet = New DataSet myDataAdapter.Fill(ds, myTableName) ' Code to modify data in DataSet here ' Without the MySqlCommandBuilder this line would fail. myDataAdapter.Update(ds, myTableName) myConn.Close() End Function 'SelectRows
在下例中,介绍了在C#中使用MySqlCommandBuilder类的方法:
public static DataSet SelectRows(string myConnection, string mySelectQuery, string myTableName) { MySqlConnection myConn = new MySqlConnection(myConnection); MySqlDataAdapter myDataAdapter = new MySqlDataAdapter(); myDataAdapter.SelectCommand = new MySqlCommand(mySelectQuery, myConn); MySqlCommandBuilder cb = new MySqlCommandBuilder(myDataAdapter); myConn.Open(); DataSet ds = new DataSet(); myDataAdapter.Fill(ds, myTableName); //code to modify data in DataSet here //Without the MySqlCommandBuilder this line would fail myDataAdapter.Update(ds, myTableName); myConn.Close(); return ds; }
MySqlConnection对象代表与MySQL服务器数据源的会话。创建MySqlConnection实例时,所有属性均将被设置为它们的初始值。关于这些值的列表,请参见MySqlConnection构造函数。
如果MySqlConnection超出范围,不会被关闭。因此,必须通过调用Close或Dispose明确地关闭连接。
· ConnectionString:设置或获取用于连接至MySQL服务器数据库的字符串。
· ConnectionTimeout:获取在中止尝试并生成错误之前为建立连接所需的等待时间。
· Database:获取当前数据库的名称或打开连接后将使用的数据库的名称。
· DataSource:获取将要连接的MySQL服务器的名称。
· ServerThread:返回该连接所使用的服务器线程的ID。
· ServerVersion:获取包含客户端与之相连的MySQL服务器版本的字符串。
· State:获取连接的当前连接的状态。
· UseConnection:与服务器进行通信时,指明该连接是否将使用压缩特性。
26.2.3.3.2. 方法
在下例中,介绍了在VB.NET中使用MySqlConnection类的方法:
Public Sub InsertRow(myConnectionString As String) ' If the connection string is null, use a default. If myConnectionString = "" Then myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass" End If Dim myConnection As New MySqlConnection(myConnectionString) Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)" Dim myCommand As New MySqlCommand(myInsertQuery) myCommand.Connection = myConnection myConnection.Open() myCommand.ExecuteNonQuery() myCommand.Connection.Close() End Sub
在下例中,介绍了在C#中使用MySqlConnection类的方法:
public void InsertRow(string myConnectionString) { // If the connection string is null, use a default. if(myConnectionString == "") { myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"; } MySqlConnection myConnection = new MySqlConnection(myConnectionString); string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"; MySqlCommand myCommand = new MySqlCommand(myInsertQuery); myCommand.Connection = myConnection; myConnection.Open(); myCommand.ExecuteNonQuery(); myCommand.Connection.Close(); }
当MySQLDataAdapter填充DataSet时,如果表或列不存在,它将为返回的数据创建必要的表和列。但是,在隐式创建的方案中不包括主键信息,除非将MissingSchemaAction属性设为AddWithKey。在使用FillSchema用数据填充它之前,也能让MySQLDataAdapter创建DataSet方案,包含主键信息。
MySQLDataAdapter用于MySqlConnection和MySqlCommand的连接,用以提升连接至MySQL数据库时的性能。
MySQLDataAdapter还包括SelectCommand、InsertCommand、DeleteCommand、UpdateCommand和TableMappings属性,用于简化数据的加载和更新操作。
26.2.3.4.1. 属性
可用属性如下:
· AcceptChangesDuringFill:获取或设置值,该值指明了在任何填充操作过程中,在将DataRow添加到DataTable后,是否要在DataRow上调用AcceptChanges。
· ContinueUpdateOnError:获取或设置值,该值指定了在行更新过程中出现错误时是否要生成异常项。
· DeleteCommand:获取或设置用于将记录从数据集中删除的SQL语句或存储程序。
· InsertCommand:获取或设置用于在数据集中插入记录的SQL语句或存储程序。
· MissingMappingAction:确定当进入的数据不含匹配表或列时需要采取的动作。
· MissingSchemaAction:确定当已有的DataSet方案与进入数据不匹配时需要采取的动作。
· SelectCommand:获取或设置用于在数据源中选择记录的SQL语句或存储程序。
· TableMappings:获取提供了源表和DataTable之间主映射的集合。
· UpdateCommand:获取或设置用于在数据源中更新记录的SQL语句或存储程序。
在下例中,介绍了在VB.NET中使用MySqlDataAdapter类的方法:
Public Function SelectRows(dataSet As DataSet, connection As String, query As String) As DataSet Dim conn As New MySqlConnection(connection) Dim adapter As New MySqlDataAdapter() adapter.SelectCommand = new MySqlCommand(query, conn) adapter.Fill(dataset) Return dataset End Function
在下例中,介绍了在C#中使用MySqlDataAdapter类的方法:
public DataSet SelectRows(DataSet dataset,string connection,string query) { MySqlConnection conn = new MySqlConnection(connection); MySqlDataAdapter adapter = new MySqlDataAdapter(); adapter.SelectCommand = new MySqlCommand(query, conn); adapter.Fill(dataset); return dataset; }
要想创建MySQLDataReader,必须调用MySqlCommand对象的ExecuteReader方法,而不是直接使用构造函数。
使用MySqlDataReader的同时,相关的MySqlConnection将忙于MySqlDataReader。除了关闭它之外,不能在MySqlConnection上执行任何操作。该情况将一直持续到调用了MySqlDataReader的“Close”方法为止。
关闭了MySqlDataReader后,你只能调用IsClosed和RecordsAffected属性。尽管在MySqlDataReader存在同时能够访问RecordsAffected属性,但在返回RecordsAffected的值之前总应调用“Close”,以确保准确的返回值。
为了获得最佳性能,MySqlDataReader将避免创建不必要的对象或执行不必要的数据拷贝。其结果是,对诸如GetValue等方法的多个调用会返回对相同对象的引用。如果你准备更改由诸如GetValue等方法返回的对象的基本值,请仔细小心。
26.2.3.5.1. 属性
· Close:关闭MySqlDataReader对象。
· GetBoolean:获取指定列的布尔值。
· GetByte:以字节形式获取指定列的值。
· GetBytes:读取从指定列偏移至缓冲的字节流,数组从给定的缓冲偏移位置开始。
· GetChar:以单字符形式获取指定列的值。
· GetChars:读取从指定列偏移至缓冲的字符流,数组从给定的缓冲偏移位置开始。
· GetDataTypeName:获取源数据类型的名称。
· GetDateTime:以DateTime对象形式获取指定列的值。
· GetDecimal:以DateTime对象形式获取指定列的值。
· GetDouble:以双精度浮点数的形式获取指定列的值。
· GetFieldType:获取作为对象数据类型的类型。
· GetFloat:以单精度浮点数的形式获取指定列的值。
· GetGuid:以GUID的形式获取指定列的值。
· GetInt16:以16位带符号整数的形式获取指定列的值。
· GetInt32:以32位带符号整数的形式获取指定列的值。
· GetInt64:以64位带符号整数的形式获取指定列的值。
· GetMySqlDateTime:以MySqlDateTime对象的形式获取指定列的值。
· GetName:获取指定列的名称。
· GetOrdinal:给定列名,获取列的顺序。
· GetSchemaTable:返回描述了MySqlDataReader的列元数据的DataTable。
· GetString:以String对象的形式获取指定列的值。
· GetTimeSpan:以TimeSpan对象的形式获取指定列的值。
· GetUInt16:以16位无符号整数的形式获取指定列的值。
· GetUInt32:以32位无符号整数的形式获取指定列的值。
· GetUInt64:以64位无符号整数的形式获取指定列的值。
· GetValue:以固有格式获取指定列的值。
· GetValues:获取当前行集合中的所有属性列。
· IsDBNull:获取值,该值指明了列中是否包含不存在或丢失的值。
· NextResult:读取批SQL语句的结果时,使数据阅读器跳到下一个结果。
· Read:使MySqlDataReader跳到下一条记录。
26.2.3.5.3. 用法
在下例中,介绍了在VB.NET中使用MySqlDataReader类的方法:
Public Sub ReadMyData(myConnString As String) Dim mySelectQuery As String = "SELECT OrderID, CustomerID FROM Orders" Dim myConnection As New MySqlConnection(myConnString) Dim myCommand As New MySqlCommand(mySelectQuery, myConnection) myConnection.Open() Dim myReader As MySqlDataReader myReader = myCommand.ExecuteReader() ' Always call Read before accessing data. While myReader.Read() Console.WriteLine((myReader.GetInt32(0) & ", " & myReader.GetString(1))) End While ' always call Close when done reading. myReader.Close() ' Close the connection when done with it. myConnection.Close() End Sub 'ReadMyData
在下例中,介绍了在C#中使用MySqlDataReader类的方法:
public void ReadMyData(string myConnString) { string mySelectQuery = "SELECT OrderID, CustomerID FROM Orders"; MySqlConnection myConnection = new MySqlConnection(myConnString); MySqlCommand myCommand = new MySqlCommand(mySelectQuery,myConnection); myConnection.Open(); MySqlDataReader myReader; myReader = myCommand.ExecuteReader(); // Always call Read before accessing data. while (myReader.Read()) { Console.WriteLine(myReader.GetInt32(0) + ", " + myReader.GetString(1)); } // always call Close when done reading. myReader.Close(); // Close the connection when done with it. myConnection.Close(); }
该示例介绍在VB.NET下使用MySqlException类的方法。
Public Sub ShowException() Dim mySelectQuery As String = "SELECT column1 FROM table1" Dim myConnection As New MySqlConnection ("Data Source=localhost;Database=Sample;") Dim myCommand As New MySqlCommand(mySelectQuery, myConnection) Try myCommand.Connection.Open() Catch e As MySqlException MessageBox.Show( e.Message ) End Try End Sub
该示例介绍在C#下使用MySqlException类的方法。
public void ShowException() { string mySelectQuery = "SELECT column1 FROM table1"; MySqlConnection myConnection = new MySqlConnection("Data Source=localhost;Database=Sample;"); MySqlCommand myCommand = new MySqlCommand(mySelectQuery,myConnection); try { myCommand.Connection.Open(); } catch (MySqlException e) { MessageBox.Show( e.Message ); } }
· ExecuteDataRow:执行单个SQL语句并返回结果集的第1行。在该方法的执行过程中,将创建、打开并关闭1个新的MySqlConnection对象。
· ExecuteDataset:执行单个SQL命令并返回DataSet中的结果集。在该方法的执行过程中,将创建、打开并关闭1个新的MySqlConnection对象。
· ExecuteNonQuery:在MySQL数据库上执行单个命令。调用该方法时,将认为MySqlConnection已打开,方法执行完后,MySqlConnection仍保持打开状态。
· ExecuteReader:Overloaded:在MySQL数据库上执行单个命令。
· ExecuteScalar:在MySQL数据库上执行单个命令。
· UpdateDataSet:用来自给定DataSet的数据更新给定表。
26.2.3.8. MySqlTransaction类
在下例中,介绍了在VB.NET中使用MySqlTransaction类的方法:
Public Sub RunTransaction(myConnString As String) Dim myConnection As New MySqlConnection(myConnString) myConnection.Open() Dim myCommand As MySqlCommand = myConnection.CreateCommand() Dim myTrans As MySqlTransaction ' Start a local transaction myTrans = myConnection.BeginTransaction() ' Must assign both transaction object and connection ' to Command object for a pending local transaction myCommand.Connection = myConnection myCommand.Transaction = myTrans Try myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')" myCommand.ExecuteNonQuery() myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')" myCommand.ExecuteNonQuery() myTrans.Commit() Console.WriteLine("Both records are written to database.") Catch e As Exception Try myTrans.Rollback() Catch ex As MySqlException If Not myTrans.Connection Is Nothing Then Console.WriteLine("An exception of type " & ex.GetType().ToString() & _ " was encountered while attempting to roll back the transaction.") End If End Try Console.WriteLine("An exception of type " & e.GetType().ToString() & _ "was encountered while inserting the data.") Console.WriteLine("Neither record was written to database.") Finally myConnection.Close() End Try End Sub 'RunTransaction
在下例中,介绍了在C#中使用MySqlTransaction类的方法:
public void RunTransaction(string myConnString) { MySqlConnection myConnection = new MySqlConnection(myConnString); myConnection.Open(); MySqlCommand myCommand = myConnection.CreateCommand(); MySqlTransaction myTrans; // Start a local transaction myTrans = myConnection.BeginTransaction(); // Must assign both transaction object and connection // to Command object for a pending local transaction myCommand.Connection = myConnection; myCommand.Transaction = myTrans; try { myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"; myCommand.ExecuteNonQuery(); myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"; myCommand.ExecuteNonQuery(); myTrans.Commit(); Console.WriteLine("Both records are written to database."); } catch(Exception e) { try { myTrans.Rollback(); } catch (MySqlException ex) { if (myTrans.Connection != null) { Console.WriteLine("An exception of type " + ex.GetType() + " was encountered while attempting to roll back the transaction."); } } Console.WriteLine("An exception of type " + e.GetType() + " was encountered while inserting the data."); Console.WriteLine("Neither record was written to database."); } finally { myConnection.Close(); } }