System.Data.SqlClient.SqlCommandBuilder Class

Automatically generates single-table commands that are used to reconcile changes made to a System.Data.DataSet with the associated SQL Server database. This class cannot be inherited.

See Also: SqlCommandBuilder Members


public sealed class SqlCommandBuilder : System.Data.Common.DbCommandBuilder


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

The System.Data.SqlClient.SqlCommandBuilder registers itself as a listener for SqlDataAdapter.RowUpdating events whenever you set the SqlCommandBuilder.DataAdapter property. You can only associate one System.Data.SqlClient.SqlDataAdapter or System.Data.SqlClient.SqlCommandBuilder object with each other at one time.

To generate INSERT, UPDATE, or DELETE statements, the System.Data.SqlClient.SqlCommandBuilder uses the SqlDataAdapter.SelectCommand property to retrieve a required set of metadata automatically. If you change the SqlDataAdapter.SelectCommand after the metadata has been retrieved, such as after the first update, you should call the System.Data.Common.DbCommandBuilder.RefreshSchema method to update the metadata.

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

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

If you call System.ComponentModel.Component.Dispose, the System.Data.SqlClient.SqlCommandBuilder is disassociated from the System.Data.SqlClient.SqlDataAdapter, and the generated commands are no longer used.


Namespace: System.Data.SqlClient
Assembly: System.Data (in System.Data.dll)
Assembly Versions: 1.0.3300.0, 1.0.5000.0,