Name

Merge

Synopsis

DataSet.Merge(DataRow[] dataSource);

DataSet.Merge(DataSet dataSource);

DataSet.Merge(DataTable dataSource);

DataSet.Merge(DataSet dataSource, Boolean preserveChanges);

DataSet.Merge(DataRow[] dataSource, Boolean preserveChanges,

    MissingSchemaAction msa);

DataSet.Merge(DataSet dataSource, Boolean preserveChanges,

    MissingSchemaAction msa);

DataSet.Merge(DataTable dataSource, Boolean preserveChanges,

    MissingSchemaAction msa);

The Merge( ) method combines the data and structure of a second, or source, DataSet, DataTable, or DataRow object array into a specified target DataSet with a similar structure.

Parameters

dataSource

The array of DataRow objects, the DataSet, or the DataTable to be merged into the DataSet.

preserveChanges

Indicates whether changes that have already been made to the target DataSet should be maintained when merging.

msa

One of the values from the MissingSchemaAction enumeration described in Table 22-14.

Example

The following example demonstrates how to merge a source DataSet into a target DataSet:

// Merge DataSet mergeDs into DataSet ds

ds.Merge(mergeDs);

Notes

The Merge( ) method is typically used in a client application to update a DataSet with the latest changes to the underlying data in the data source.

When the Merge( ) method is called, the schemas of the source and target DataSet are compared. If there are schema differences, the MissingSchemaAction argument determines whether the target schema will be updated to include the missing schema and data. Table 22-14 describes the effect of the MissingSchemaAction values.

Table 22-14. MissingSchemaAction enumeration

Value	Description
Add	Adds information for new columns to the target DataSet and populates these columns with values from the source DataSet.
AddWithKey	Adds new schema and primary key information to the target DataSet and populates these columns with values from the source DataSet.
Error	Generates a SystemException when mismatched schemas are encountered.
Ignore	Ignores new schema information in the source DataSet.

During the merge operation, source rows with a RowState of Unchanged, Modified, or Deleted are matched to rows in the target DataSet with the same Current primary key values. Source rows with RowState of New are created in the target DataSet with the same primary key values as the Current value in the source, because the Original version doesn’t exist in the source.

If the optional PreserveChanges argument is set to true, incoming values from the source don’t overwrite Current values in the target DataSet rows. Data in the target Original row version is overwritten with the Original row version of the source row, and the target RowState is set to Modified. There are two exceptions. If the target RowState is Deleted, it remains deleted and isn’t set to Modified. If the source RowState is Added, the target existing row isn’t overwritten because it doesn’t exist.

If PreserveChanges is false, both the Current and Original rows of the target are overwritten with the source data, and the RowState of the target row is set to the RowState of the source row. Again, there are two exceptions. If the source RowState is Unchanged, and the target RowState is Unchanged, Modified, Added, or Deleted, the RowState of the target row is set to Modified. If the source RowState is Added, the Original version of the target isn’t overwritten because it doesn’t exist.

During the merge operation, constraints are disabled. If constraints can’t be enabled after the merge, the EnforceContraints property of the DataSet is set to false, and all invalid rows are marked as having errors.