6.7 Merging Two DataSets

The Merge( ) method combines the data and structure of a second, or source, DataSet into a specified target DataSet with a similar structure. 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 is updated to include the missing schema and data or whether an exception is raised. If the MissingSchemaAction is specified as Add or AddWithKey, the schema is extended to accommodate the new data, and the primary key information added in the case of the later value. Specifying Ignore results in the data for the missing schema being ignored; specifying Error results in an exception being raised.

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. Figure 6-2 shows the result of merging two tables with similar schemas, accepting the default MissingSchemaAction value of Add.

Figure 6-2. Merging DataSet objects

If the optional PreserveChanges argument is set to true, incoming values from the source doesn'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.

The following example demonstrates the most complete form of the Merge( ) method:

Boolean preserveChanges = true;
Boolean missingSchemaAction = MissingSchemaAction.Add;

ds.Merge(mergeDs, preserveChanges, missingSchemaAction);