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.

MySqlCommandBuilder.xml 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321
  1. <docs>
  2. <class>
  3. <summary>
  4. Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database. This class cannot be inherited.
  5. </summary>
  6. <remarks>
  7. <para>
  8. The <see cref="MySqlDataAdapter"/> does not automatically generate the SQL statements required to
  9. reconcile changes made to a <see cref="System.Data.DataSet">DataSet</see> with the associated instance of MySQL.
  10. However, you can create a <B>MySqlCommandBuilder</B> object to automatically generate SQL statements for
  11. single-table updates if you set the <see cref="MySqlDataAdapter.SelectCommand">SelectCommand</see> property
  12. of the <B>MySqlDataAdapter</B>. Then, any additional SQL statements that you do not set are generated by the
  13. <B>MySqlCommandBuilder</B>.
  14. </para>
  15. <para>
  16. The <B>MySqlCommandBuilder</B> registers itself as a listener for <see cref="MySqlDataAdapter.OnRowUpdating">RowUpdating</see>
  17. events whenever you set the <see cref="DataAdapter"/> property. You can only associate one
  18. <B>MySqlDataAdapter</B> or <B>MySqlCommandBuilder</B> object with each other at one time.
  19. </para>
  20. <para>
  21. To generate INSERT, UPDATE, or DELETE statements, the <B>MySqlCommandBuilder</B> uses the
  22. <B>SelectCommand</B> property to retrieve a required set of metadata automatically. If you change
  23. the <B>SelectCommand</B> after the metadata has is retrieved (for example, after the first update), you
  24. should call the <see cref="RefreshSchema"/> method to update the metadata.
  25. </para>
  26. <para>
  27. The <B>SelectCommand</B> must also return at least one primary key or unique
  28. column. If none are present, an <I>InvalidOperation</I> exception is generated,
  29. and the commands are not generated.
  30. </para>
  31. <para>
  32. The <B>MySqlCommandBuilder</B> also uses the <see cref="MySqlCommand.Connection">Connection</see>,
  33. <see cref="MySqlCommand.CommandTimeout">CommandTimeout</see>, and <see cref="MySqlCommand.Transaction">Transaction</see>
  34. properties referenced by the <B>SelectCommand</B>. The user should call
  35. <B>RefreshSchema</B> if any of these properties are modified, or if the
  36. <B>SelectCommand</B> itself is replaced. Otherwise the <see cref="MySqlDataAdapter.InsertCommand">InsertCommand</see>,
  37. <see cref="MySqlDataAdapter.UpdateCommand">UpdateCommand</see>, and
  38. <see cref="MySqlDataAdapter.DeleteCommand">DeleteCommand</see> properties retain
  39. their previous values.
  40. </para>
  41. <para>
  42. If you call <i>Dispose</i>, the <B>MySqlCommandBuilder</B> is disassociated
  43. from the <B>MySqlDataAdapter</B>, and the generated commands are no longer used.
  44. </para>
  45. <note>
  46. Caution must be used when using MySqlCOmmandBuilder on MySql 4.0 systems. With MySql 4.0,
  47. database/schema information is not provided to the connector for a query. This means that
  48. a query that pulls columns from two identically named tables in two or more different databases
  49. will not cause an exception to be thrown but will not work correctly. Even more dangerous
  50. is the situation where your select statement references database X but is executed in
  51. database Y and both databases have tables with similar layouts. This situation can cause
  52. unwanted changes or deletes.
  53. This note does not apply to MySQL versions 4.1 and later.
  54. </note>
  55. </remarks>
  56. <example>
  57. The following example uses the <see cref="MySqlCommand"/>, along
  58. <see cref="MySqlDataAdapter"/> and <see cref="MySqlConnection"/>, to
  59. select rows from a data source. The example is passed an initialized
  60. <see cref="System.Data.DataSet"/>, a connection string, a
  61. query string that is a SQL SELECT statement, and a string that is the
  62. name of the database table. The example then creates a <B>MySqlCommandBuilder</B>.
  63. <code lang="vbnet">
  64. Public Shared Function SelectRows(myConnection As String, mySelectQuery As String, myTableName As String) As DataSet
  65. Dim myConn As New MySqlConnection(myConnection)
  66. Dim myDataAdapter As New MySqlDataAdapter()
  67. myDataAdapter.SelectCommand = New MySqlCommand(mySelectQuery, myConn)
  68. Dim cb As SqlCommandBuilder = New MySqlCommandBuilder(myDataAdapter)
  69. myConn.Open()
  70. Dim ds As DataSet = New DataSet
  71. myDataAdapter.Fill(ds, myTableName)
  72. ' Code to modify data in DataSet here
  73. ' Without the MySqlCommandBuilder this line would fail.
  74. myDataAdapter.Update(ds, myTableName)
  75. myConn.Close()
  76. End Function 'SelectRows
  77. </code>
  78. <code lang="C#">
  79. public static DataSet SelectRows(string myConnection, string mySelectQuery, string myTableName)
  80. {
  81. MySqlConnection myConn = new MySqlConnection(myConnection);
  82. MySqlDataAdapter myDataAdapter = new MySqlDataAdapter();
  83. myDataAdapter.SelectCommand = new MySqlCommand(mySelectQuery, myConn);
  84. MySqlCommandBuilder cb = new MySqlCommandBuilder(myDataAdapter);
  85. myConn.Open();
  86. DataSet ds = new DataSet();
  87. myDataAdapter.Fill(ds, myTableName);
  88. //code to modify data in DataSet here
  89. //Without the MySqlCommandBuilder this line would fail
  90. myDataAdapter.Update(ds, myTableName);
  91. myConn.Close();
  92. return ds;
  93. }
  94. </code>
  95. </example>
  96. </class>
  97. <Ctor>
  98. <summary>
  99. Initializes a new instance of the <see cref="MySqlCommandBuilder"/> class.
  100. </summary>
  101. </Ctor>
  102. <Ctor2>
  103. <summary>
  104. Initializes a new instance of the <see cref="MySqlCommandBuilder"/> class
  105. with the associated <see cref="MySqlDataAdapter"/> object.
  106. </summary>
  107. <param name="adapter">
  108. The <see cref="MySqlDataAdapter"/> to use.
  109. </param>
  110. <remarks>
  111. <para>
  112. The <see cref="MySqlCommandBuilder"/> registers itself as a listener for
  113. <see cref="MySqlDataAdapter.RowUpdating"/> events that are generated by the
  114. <see cref="MySqlDataAdapter"/> specified in this property.
  115. </para>
  116. <para>
  117. When you create a new instance <B>MySqlCommandBuilder</B>, any existing
  118. <B>MySqlCommandBuilder</B> associated with this <B>MySqlDataAdapter</B>
  119. is released.
  120. </para>
  121. </remarks>
  122. </Ctor2>
  123. <DataAdapter>
  124. <summary>
  125. Gets or sets a <see cref="MySqlDataAdapter"/> object for which SQL statements are automatically generated.
  126. </summary>
  127. <value>
  128. A <see cref="MySqlDataAdapter"/> object.
  129. </value>
  130. <remarks>
  131. <para>
  132. The <see cref="MySqlCommandBuilder"/> registers itself as a listener for
  133. <see cref="MySqlDataAdapter.RowUpdating"/> events that are generated by the
  134. <see cref="MySqlDataAdapter"/> specified in this property.
  135. </para>
  136. <para>
  137. When you create a new instance <B>MySqlCommandBuilder</B>, any existing
  138. <B>MySqlCommandBuilder</B> associated with this <B>MySqlDataAdapter</B>
  139. is released.
  140. </para>
  141. </remarks>
  142. </DataAdapter>
  143. <QuotePrefix>
  144. <summary>
  145. Gets or sets the beginning character or characters to use when specifying MySQL
  146. database objects (for example, tables or columns) whose names contain
  147. characters such as spaces or reserved tokens.
  148. </summary>
  149. <value>
  150. The beginning character or characters to use. The default value is `.
  151. </value>
  152. <remarks>
  153. Database objects in MySQL can contain special characters such as spaces that would
  154. make normal SQL strings impossible to correctly parse. Use of the <b>QuotePrefix</b>
  155. and the <see cref="QuoteSuffix"/> properties allows the <see cref="MySqlCommandBuilder"/>
  156. to build SQL commands that handle this situation.
  157. </remarks>
  158. </QuotePrefix>
  159. <QuoteSuffix>
  160. <summary>
  161. Gets or sets the beginning character or characters to use when specifying MySQL
  162. database objects (for example, tables or columns) whose names contain
  163. characters such as spaces or reserved tokens.
  164. </summary>
  165. <value>
  166. The beginning character or characters to use. The default value is `.
  167. </value>
  168. <remarks>
  169. Database objects in MySQL can contain special characters such as spaces that would
  170. make normal SQL strings impossible to correctly parse. Use of the <see cref="QuotePrefix"/>
  171. and the <b>QuoteSuffix</b> properties allows the <see cref="MySqlCommandBuilder"/>
  172. to build SQL commands that handle this situation.
  173. </remarks>
  174. </QuoteSuffix>
  175. <DeriveParameters>
  176. <summary>
  177. </summary>
  178. <remarks>
  179. </remarks>
  180. </DeriveParameters>
  181. <GetDeleteCommand>
  182. <summary>
  183. Gets the automatically generated <see cref="MySqlCommand"/> object
  184. required to perform deletions on the database.
  185. </summary>
  186. <returns>
  187. The <see cref="MySqlCommand"/> object generated to handle delete operations.
  188. </returns>
  189. <remarks>
  190. <para>
  191. An application can use the <B>GetDeleteCommand</B> method for informational
  192. or troubleshooting purposes because it returns the <see cref="MySqlCommand"/>
  193. object to be executed.
  194. </para>
  195. <para>
  196. You can also use <B>GetDeleteCommand</B> as the basis of a modified command.
  197. For example, you might call <B>GetDeleteCommand</B> and modify the
  198. <see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the
  199. <see cref="MySqlDataAdapter"/>.
  200. </para>
  201. <para>
  202. After the SQL statement is first generated, the application must explicitly
  203. call <see cref="RefreshSchema"/> if it changes the statement in any way.
  204. Otherwise, the <B>GetDeleteCommand</B> will be still be using information
  205. from the previous statement, which might not be correct. The SQL statements
  206. are first generated either when the application calls
  207. <see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetDeleteCommand</B>.
  208. </para>
  209. </remarks>
  210. </GetDeleteCommand>
  211. <GetInsertCommand>
  212. <summary>
  213. Gets the automatically generated <see cref="MySqlCommand"/> object
  214. required to perform insertions on the database.
  215. </summary>
  216. <returns>
  217. The <see cref="MySqlCommand"/> object generated to handle insert operations.
  218. </returns>
  219. <remarks>
  220. <para>
  221. An application can use the <B>GetInsertCommand</B> method for informational
  222. or troubleshooting purposes because it returns the <see cref="MySqlCommand"/>
  223. object to be executed.
  224. </para>
  225. <para>
  226. You can also use the <B>GetInsertCommand</B> as the basis of a modified command.
  227. For example, you might call <B>GetInsertCommand</B> and modify the
  228. <see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the
  229. <see cref="MySqlDataAdapter"/>.
  230. </para>
  231. <para>
  232. After the SQL statement is first generated, the application must explicitly
  233. call <see cref="RefreshSchema"/> if it changes the statement in any way.
  234. Otherwise, the <B>GetInsertCommand</B> will be still be using information
  235. from the previous statement, which might not be correct. The SQL statements
  236. are first generated either when the application calls
  237. <see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetInsertCommand</B>.
  238. </para>
  239. </remarks>
  240. </GetInsertCommand>
  241. <GetUpdateCommand>
  242. <summary>
  243. Gets the automatically generated <see cref="MySqlCommand"/> object
  244. required to perform updates on the database.
  245. </summary>
  246. <returns>
  247. The <see cref="MySqlCommand"/> object generated to handle update operations.
  248. </returns>
  249. <remarks>
  250. <para>
  251. An application can use the <B>GetUpdateCommand</B> method for informational
  252. or troubleshooting purposes because it returns the <see cref="MySqlCommand"/>
  253. object to be executed.
  254. </para>
  255. <para>
  256. You can also use <B>GetUpdateCommand</B> as the basis of a modified command.
  257. For example, you might call <B>GetUpdateCommand</B> and modify the
  258. <see cref="MySqlCommand.CommandTimeout"/> value, and then explicitly set that on the
  259. <see cref="MySqlDataAdapter"/>.
  260. </para>
  261. <para>
  262. After the SQL statement is first generated, the application must explicitly
  263. call <see cref="RefreshSchema"/> if it changes the statement in any way.
  264. Otherwise, the <B>GetUpdateCommand</B> will be still be using information
  265. from the previous statement, which might not be correct. The SQL statements
  266. are first generated either when the application calls
  267. <see cref="System.Data.Common.DataAdapter.Update"/> or <B>GetUpdateCommand</B>.
  268. </para>
  269. </remarks>
  270. </GetUpdateCommand>
  271. <RefreshSchema>
  272. <summary>
  273. Refreshes the database schema information used to generate INSERT, UPDATE, or
  274. DELETE statements.
  275. </summary>
  276. <remarks>
  277. <para>
  278. An application should call <B>RefreshSchema</B> whenever the SELECT statement
  279. associated with the <see cref="MySqlCommandBuilder"/> changes.
  280. </para>
  281. <para>
  282. An application should call <B>RefreshSchema</B> whenever the
  283. <see cref="MySqlDataAdapter.SelectCommand"/> value of the <see cref="MySqlDataAdapter"/> changes.
  284. </para>
  285. </remarks>
  286. </RefreshSchema>
  287. </docs>