6.3 Adding and Removing Relations

Relations belonging to the DataSet are stored as DataRelation objects in a DataRelationCollection object and are accessed through the Relations property of the DataSet . Each DataRelation object represents the relationship between a parent and child table in the DataSet . This section examines some methods and properties of the DataRelationCollection .

Relations are added to the DataSet using the Add( ) method of the DataRelationCollection , as shown in the following example:

ds.Relations.Add("MyDataRelation", parentTable.Columns["PrimaryKeyField"],
    childTable.Columns["ForeignKeyField"]);

The Remove( ) method removes a relation matching the relation- name argument. The following example removes the relation added in the previous example:

ds.Relations.Remove("MyDataRelation");

The Contains( ) method can determine if a specific relation exists as shown in the following example:

Boolean exists = ds.Relations.Contains("MyRelation");

Relations and the DataRelationCollection are discussed in detail in Chapter 11.

6.4 Adding Custom Information

The DataSet contains a PropertyCollection that is exposed through the ExtendedProperties property. This collection allows a user to add custom information to the DataSet such as the date and time when the DataSet should be refreshed. The following example sets an extended property indicating that the DataSet should be refreshed in 20 minutes:

ds.ExtendedProperties.Add("RefreshDateTime",
    DateTime.Now.AddMinutes(20).ToString());

The following code can then check that value to see if the DataSet needs to be refreshed:

if(DateTime.Now>Convert.ToDateTime(
    ds.ExtendedProperties["RefreshDateTime"].ToString( ) ))
{
    // ... code to refresh the DataSet
}

Extended properties must be of type String , or else they will not persist when the DataSet is written as XML.

The DataTable , DataColumn , DataRelation , and Constraint objects also have a similar collection of extended properties.

6.5 Cloning the Schema

The Clone( ) method creates a new DataSet with the same structure, including table schemas and relations, as the original but containing none of the data in the original DataSet . The following example uses the Clone( ) method to create a new DataSet :

// create a DataSet object variable to receive the clone
DataSet cloneDs;
cloneDs = ds.Clone();

6.6 Copying the DataSet

The Copy( ) method of the DataSet creates a new DataSet with the same structure, including tables schemas and relations, and data as the original DataSet . The following example uses the Copy( ) method to create a new DataSet :

// create a DataSet object variable to receive the copy
DataSet copyDs;
copyDs = ds.Copy();

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);

Buy on amazon.com >>

Hamilton B., MacDonald M.

<< Previous page

Table of contents

Next page >>

Flylib.com

Category list

Similar pages

6.3 Adding and Removing Relations