System.Data.Common.DbCommandBuilder Class

Automatically generates single-table commands used to reconcile changes made to a System.Data.DataSet with the associated database. This is an abstract class that can only be inherited.

See Also: DbCommandBuilder Members


public abstract class DbCommandBuilder : System.ComponentModel.Component


The System.Data.Common.DbCommandBuilder class is provided for the convenience of provider writers creating their own command builders. By inheriting from this class, developers can implement provider specific behavior in their own code.

The System.Data.Common.DbDataAdapter does not automatically generate the SQL statements required to reconcile changes made to a System.Data.DataSet with the associated data source. However, you can create a System.Data.Common.DbCommandBuilder object to automatically generate SQL statements for single-table updates if you set the DbDataAdapter.SelectCommand property of the System.Data.Common.DbDataAdapter. Then, any additional SQL statements that you do not set are generated by the System.Data.Common.DbCommandBuilder.

The System.Data.Common.DbCommandBuilder registers itself as a listener for System.Data.OleDb.OleDbDataAdapter.RowUpdating events whenever you set the DbCommandBuilder.DataAdapter property. You can only associate one System.Data.Common.DbDataAdapter or System.Data.Common.DbCommandBuilder object with each other at one time.

To generate INSERT, UPDATE, or DELETE statements, the System.Data.Common.DbCommandBuilder uses the DbDataAdapter.SelectCommand property to retrieve a required set of metadata automatically. If you change the DbDataAdapter.SelectCommand after the metadata has been retrieved (for example, after the first update), you should call the DbCommandBuilder.RefreshSchema method to update the metadata.

The SelectCommand must also return at least one primary key or unique column. If none exist, an InvalidOperationException exception is generated, and the commands are not generated.

The System.Data.Common.DbCommandBuilder also uses the DbCommand.Connection, DbCommand.CommandTimeout, and DbCommand.Transaction properties referenced by the DbDataAdapter.SelectCommand. The user should call DbCommandBuilder.RefreshSchema if any of these properties are modified, or if the DbDataAdapter.SelectCommand itself is replaced. Otherwise the DbDataAdapter.InsertCommand, DbDataAdapter.UpdateCommand, and DbDataAdapter.DeleteCommand properties retain their previous values.

If you call System.ComponentModel.Component.Dispose, the System.Data.Common.DbCommandBuilder is disassociated from the System.Data.Common.DbDataAdapter, and the generated commands are no longer used.


Namespace: System.Data.Common
Assembly: System.Data (in System.Data.dll)
Assembly Versions:
Since: .NET 2.0