The next generation of the Teknik Services. Written in ASP.NET.
https://www.teknik.io/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
321 lines
13 KiB
321 lines
13 KiB
<docs> |
|
<class> |
|
<summary> |
|
Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database. This class cannot be inherited. |
|
</summary> |
|
<remarks> |
|
<para> |
|
The <see cref="MySqlDataAdapter"/> does not automatically generate the SQL statements required to |
|
reconcile changes made to a <see cref="System.Data.DataSet">DataSet</see> with the associated instance of MySQL. |
|
However, you can create a <B>MySqlCommandBuilder</B> object to automatically generate SQL statements for |
|
single-table updates if you set the <see cref="MySqlDataAdapter.SelectCommand">SelectCommand</see> property |
|
of the <B>MySqlDataAdapter</B>. Then, any additional SQL statements that you do not set are generated by the |
|
<B>MySqlCommandBuilder</B>. |
|
</para> |
|
|
|
<para> |
|
The <B>MySqlCommandBuilder</B> registers itself as a listener for <see cref="MySqlDataAdapter.OnRowUpdating">RowUpdating</see> |
|
events whenever you set the <see cref="DataAdapter"/> property. You can only associate one |
|
<B>MySqlDataAdapter</B> or <B>MySqlCommandBuilder</B> object with each other at one time. |
|
</para> |
|
|
|
<para> |
|
To generate INSERT, UPDATE, or DELETE statements, the <B>MySqlCommandBuilder</B> uses the |
|
<B>SelectCommand</B> property to retrieve a required set of metadata automatically. If you change |
|
the <B>SelectCommand</B> after the metadata has is retrieved (for example, after the first update), you |
|
should call the <see cref="RefreshSchema"/> method to update the metadata. |
|
</para> |
|
|
|
<para> |
|
The <B>SelectCommand</B> must also return at least one primary key or unique |
|
column. If none are present, an <I>InvalidOperation</I> exception is generated, |
|
and the commands are not generated. |
|
</para> |
|
|
|
<para> |
|
The <B>MySqlCommandBuilder</B> also uses the <see cref="MySqlCommand.Connection">Connection</see>, |
|
<see cref="MySqlCommand.CommandTimeout">CommandTimeout</see>, and <see cref="MySqlCommand.Transaction">Transaction</see> |
|
properties referenced by the <B>SelectCommand</B>. The user should call |
|
<B>RefreshSchema</B> if any of these properties are modified, or if the |
|
<B>SelectCommand</B> itself is replaced. Otherwise the <see cref="MySqlDataAdapter.InsertCommand">InsertCommand</see>, |
|
<see cref="MySqlDataAdapter.UpdateCommand">UpdateCommand</see>, and |
|
<see cref="MySqlDataAdapter.DeleteCommand">DeleteCommand</see> properties retain |
|
their previous values. |
|
</para> |
|
|
|
<para> |
|
If you call <i>Dispose</i>, the <B>MySqlCommandBuilder</B> is disassociated |
|
from the <B>MySqlDataAdapter</B>, and the generated commands are no longer used. |
|
</para> |
|
|
|
<note> |
|
Caution must be used when using MySqlCOmmandBuilder on MySql 4.0 systems. With MySql 4.0, |
|
database/schema information is not provided to the connector for a query. This means that |
|
a query that pulls columns from two identically named tables in two or more different databases |
|
will not cause an exception to be thrown but will not work correctly. Even more dangerous |
|
is the situation where your select statement references database X but is executed in |
|
database Y and both databases have tables with similar layouts. This situation can cause |
|
unwanted changes or deletes. |
|
This note does not apply to MySQL versions 4.1 and later. |
|
</note> |
|
|
|
</remarks> |
|
|
|
<example> |
|
The following example uses the <see cref="MySqlCommand"/>, along |
|
<see cref="MySqlDataAdapter"/> and <see cref="MySqlConnection"/>, to |
|
select rows from a data source. The example is passed an initialized |
|
<see cref="System.Data.DataSet"/>, a connection string, a |
|
query string that is a SQL SELECT statement, and a string that is the |
|
name of the database table. The example then creates a <B>MySqlCommandBuilder</B>. |
|
|
|
<code lang="vbnet"> |
|
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 |
|
</code> |
|
<code lang="C#"> |
|
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; |
|
} |
|
|
|
</code> |
|
</example> |
|
</class> |
|
|
|
<Ctor> |
|
<summary> |
|
Initializes a new instance of the <see cref="MySqlCommandBuilder"/> class. |
|
</summary> |
|
</Ctor> |
|
|
|
<Ctor2> |
|
<summary> |
|
Initializes a new instance of the <see cref="MySqlCommandBuilder"/> class |
|
with the associated <see cref="MySqlDataAdapter"/> object. |
|
</summary> |
|
<param name="adapter"> |
|
The <see cref="MySqlDataAdapter"/> to use. |
|
</param> |
|
<remarks> |
|
<para> |
|
The <see cref="MySqlCommandBuilder"/> registers itself as a listener for |
|
<see cref="MySqlDataAdapter.RowUpdating"/> events that are generated by the |
|
<see cref="MySqlDataAdapter"/> specified in this property. |
|
</para> |
|
<para> |
|
When you create a new instance <B>MySqlCommandBuilder</B>, any existing |
|
<B>MySqlCommandBuilder</B> associated with this <B>MySqlDataAdapter</B> |
|
is released. |
|
</para> |
|
</remarks> |
|
</Ctor2> |
|
|
|
|
|
<DataAdapter> |
|
<summary> |
|
Gets or sets a <see cref="MySqlDataAdapter"/> object for which SQL statements are automatically generated. |
|
</summary> |
|
<value> |
|
A <see cref="MySqlDataAdapter"/> object. |
|
</value> |
|
<remarks> |
|
<para> |
|
The <see cref="MySqlCommandBuilder"/> registers itself as a listener for |
|
<see cref="MySqlDataAdapter.RowUpdating"/> events that are generated by the |
|
<see cref="MySqlDataAdapter"/> specified in this property. |
|
</para> |
|
<para> |
|
When you create a new instance <B>MySqlCommandBuilder</B>, any existing |
|
<B>MySqlCommandBuilder</B> associated with this <B>MySqlDataAdapter</B> |
|
is released. |
|
</para> |
|
</remarks> |
|
</DataAdapter> |
|
|
|
<QuotePrefix> |
|
<summary> |
|
Gets or sets the beginning character or characters to use when specifying MySQL |
|
database objects (for example, tables or columns) whose names contain |
|
characters such as spaces or reserved tokens. |
|
</summary> |
|
<value> |
|
The beginning character or characters to use. The default value is `. |
|
</value> |
|
<remarks> |
|
Database objects in MySQL can contain special characters such as spaces that would |
|
make normal SQL strings impossible to correctly parse. Use of the <b>QuotePrefix</b> |
|
and the <see cref="QuoteSuffix"/> properties allows the <see cref="MySqlCommandBuilder"/> |
|
to build SQL commands that handle this situation. |
|
</remarks> |
|
</QuotePrefix> |
|
|
|
<QuoteSuffix> |
|
<summary> |
|
Gets or sets the beginning character or characters to use when specifying MySQL |
|
database objects (for example, tables or columns) whose names contain |
|
characters such as spaces or reserved tokens. |
|
</summary> |
|
<value> |
|
The beginning character or characters to use. The default value is `. |
|
</value> |
|
<remarks> |
|
Database objects in MySQL can contain special characters such as spaces that would |
|
make normal SQL strings impossible to correctly parse. Use of the <see cref="QuotePrefix"/> |
|
and the <b>QuoteSuffix</b> properties allows the <see cref="MySqlCommandBuilder"/> |
|
to build SQL commands that handle this situation. |
|
</remarks> |
|
</QuoteSuffix> |
|
|
|
<DeriveParameters> |
|
<summary> |
|
|
|
</summary> |
|
<remarks> |
|
</remarks> |
|
</DeriveParameters> |
|
|
|
<GetDeleteCommand> |
|
<summary> |
|
Gets the automatically generated <see cref="MySqlCommand"/> object |
|
required to perform deletions on the database. |
|
</summary> |
|
<returns> |
|
The <see cref="MySqlCommand"/> object generated to handle delete operations. |
|
</returns> |
|
<remarks> |
|
<para> |
|
An application can use the <B>GetDeleteCommand</B> method for informational |
|
or troubleshooting purposes because it returns the <see cref="MySqlCommand"/> |
|
object to be executed. |
|
</para> |
|
<para> |
|
You can also use <B>GetDeleteCommand</B> as the basis of a modified command. |
|
For example, you might call <B>GetDeleteCommand</B> and modify the |
|
<see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the |
|
<see cref="MySqlDataAdapter"/>. |
|
</para> |
|
<para> |
|
After the SQL statement is first generated, the application must explicitly |
|
call <see cref="RefreshSchema"/> if it changes the statement in any way. |
|
Otherwise, the <B>GetDeleteCommand</B> will be still be using information |
|
from the previous statement, which might not be correct. The SQL statements |
|
are first generated either when the application calls |
|
<see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetDeleteCommand</B>. |
|
</para> |
|
</remarks> |
|
</GetDeleteCommand> |
|
|
|
<GetInsertCommand> |
|
<summary> |
|
Gets the automatically generated <see cref="MySqlCommand"/> object |
|
required to perform insertions on the database. |
|
</summary> |
|
<returns> |
|
The <see cref="MySqlCommand"/> object generated to handle insert operations. |
|
</returns> |
|
<remarks> |
|
<para> |
|
An application can use the <B>GetInsertCommand</B> method for informational |
|
or troubleshooting purposes because it returns the <see cref="MySqlCommand"/> |
|
object to be executed. |
|
</para> |
|
<para> |
|
You can also use the <B>GetInsertCommand</B> as the basis of a modified command. |
|
For example, you might call <B>GetInsertCommand</B> and modify the |
|
<see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the |
|
<see cref="MySqlDataAdapter"/>. |
|
</para> |
|
<para> |
|
After the SQL statement is first generated, the application must explicitly |
|
call <see cref="RefreshSchema"/> if it changes the statement in any way. |
|
Otherwise, the <B>GetInsertCommand</B> will be still be using information |
|
from the previous statement, which might not be correct. The SQL statements |
|
are first generated either when the application calls |
|
<see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetInsertCommand</B>. |
|
</para> |
|
</remarks> |
|
</GetInsertCommand> |
|
|
|
<GetUpdateCommand> |
|
<summary> |
|
Gets the automatically generated <see cref="MySqlCommand"/> object |
|
required to perform updates on the database. |
|
</summary> |
|
<returns> |
|
The <see cref="MySqlCommand"/> object generated to handle update operations. |
|
</returns> |
|
<remarks> |
|
<para> |
|
An application can use the <B>GetUpdateCommand</B> method for informational |
|
or troubleshooting purposes because it returns the <see cref="MySqlCommand"/> |
|
object to be executed. |
|
</para> |
|
<para> |
|
You can also use <B>GetUpdateCommand</B> as the basis of a modified command. |
|
For example, you might call <B>GetUpdateCommand</B> and modify the |
|
<see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the |
|
<see cref="MySqlDataAdapter"/>. |
|
</para> |
|
<para> |
|
After the SQL statement is first generated, the application must explicitly |
|
call <see cref="RefreshSchema"/> if it changes the statement in any way. |
|
Otherwise, the <B>GetUpdateCommand</B> will be still be using information |
|
from the previous statement, which might not be correct. The SQL statements |
|
are first generated either when the application calls |
|
<see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetUpdateCommand</B>. |
|
</para> |
|
</remarks> |
|
</GetUpdateCommand> |
|
|
|
<RefreshSchema> |
|
<summary> |
|
Refreshes the database schema information used to generate INSERT, UPDATE, or |
|
DELETE statements. |
|
</summary> |
|
<remarks> |
|
<para> |
|
An application should call <B>RefreshSchema</B> whenever the SELECT statement |
|
associated with the <see cref="MySqlCommandBuilder"/> changes. |
|
</para> |
|
<para> |
|
An application should call <B>RefreshSchema</B> whenever the |
|
<see cref="MySqlDataAdapter.SelectCommand"/> value of the <see cref="MySqlDataAdapter"/> changes. |
|
</para> |
|
</remarks> |
|
</RefreshSchema> |
|
|
|
</docs> |