22.4 Methods Reference

AcceptChanges

 DataSet.AcceptChanges();

Commits all changes made to the DataSet since the last time it was loaded or since the last time AcceptChanges( ) was called.

Parameters

None.

Example

The following example demonstrates how to call the AcceptChanges( ) method of the DataSet :

 DataSet ds = new DataSet(); // create a table with a single column DataTable dt = ds.Tables.Add(); dt.Columns.Add("MyColumn", typeof(System.Int32)); DataRow row; row = dt.NewRow(); row["MyColumn"] = 1; dt.Rows.Add(row);       // RowState = Added ds.AcceptChanges();     // RowState = Unchanged row["MyColumn"] = 2;    // RowState = Modified ds.AcceptChanges();     // RowState = Unchanged row.Delete();           // RowState = Deleted ds.AcceptChanges();     // Row is removed from the DataSet

Notes

Calling AcceptChanges( ) sets the RowState property of Added and Modified rows to Unchanged ; the original values in the DataRow are set to the current values. Deleted rows are removed from the DataSet .

Calling the AcceptChanges( ) method on the DataSet causes AcceptChanges to be called on each DataTable belonging to the DataSet .

EndEdit( ) is implicitly called on any DataRow objects that are in edit mode as a result of calling the BeginEdit( ) method of the DataRow( ) .

Calling AcceptChanges( ) clears all RowError information and sets the HasErrors property of the row to false .

Clear

 DataSet.Clear();

Removes all data rows from the DataSet .

Parameters

None.

Example

The following example demonstrates the Clear( ) method of the DataSet :

 DataSet ds = new DataSet(); DataTable dt1 = ds.Tables.Add("MyTable1"); DataTable dt2 = ds.Tables.Add("MyTable2"); // ... define the schema for the DataTables dt1 and dt2 // ... add some rows to each of the DataTables dt1 and dt2 ds.Clear();    // all rows removed from DataTables dt1 and dt2.

Clone

 DataSet   ds   = DataSet.Clone();

Creates a new DataSet with the same schema as the current DataSet but which contains none of the data.

Parameter

ds: Returns the new DataSet with the same schema as the original but none of the data.

Example

The following example shows how to create a new empty DataSet with the same schema as an existing DataSet :

 DataSet ds1 = new DataSet(); DataTable dt1 = ds1.Tables.Add("MyTable1"); DataTable dt2 = ds1.Tables.Add("MyTable2"); // ... define the schema for the DataTables dt1 and dt2 // ... add some rows to each of the DataTables dt1 and dt2 // Create DataSet ds2 with the same schema, but without any of the  // data in DataSet ds1. DataSet ds2 = ds1.Clone();

Copy

 DataSet   ds   = DataSet.Copy();

Creates a new DataSet having the same schema and containing the same data as the original DataSet .

Parameter

ds: Returns the new DataSet with the same schema and data as the original.

Example

The following example shows how to create a new DataSet with the same schema and data as an existing DataSet :

 DataSet ds1 = new DataSet(); DataTable dt1 = ds1.Tables.Add("MyTable1"); DataTable dt2 = ds1.Tables.Add("MyTable2"); // ... define the schema for the DataTables dt1 and dt2 // ... add some rows to each of the DataTables dt1 and dt2 // Create DataSet ds2 with the same schema and data as DataSet ds1. DataSet ds2 = ds1.Copy();

GetChanges

 DataSet   ds   = DataSet.GetChanges(); DataSet   ds   = DataSet.GetChanges(DataRowState   drs   );

Returns a DataSet with the same schema as the original DataSet but which contains only the rows that have been modified since the last time the DataSet was loaded or since AcceptChanges( ) was last called. This overloaded method allows the changes to be filtered by the RowState of the DataRow objects.

Parameters

ds: Returns the DataSet with all changes made to the original since it was last loaded or AcceptChanges( ) was last called.
drs: A DataRowState enumeration value as described in Table 22-13 specifying the row state of the DataRow objects to return.

Table 22-13. DataRowState enumeration

Value	Description
Added	The row has been added to the `DataRowCollection` for the table, and `AcceptChanges( )` has not been called.
Deleted	The row has been deleted from the `DataRowCollection` , and `AcceptChanges( )` has not been called.
Detached	The row isn't part of a `DataRowCollection` .
Modified	The row has been modified, and `AcceptChanges( )` has not been called.
Unchanged	The row has not been changed since `AcceptChanges( )` was last called.

Example

The following example shows how to create a DataSet containing all changed rows and a DataSet containing all deleted rows from the original DataSet :

 // return a DataSet containing all changed rows DataSet dsChanges = dsOriginal.GetChanges(); // return a DataSet containing all deleted rows DataSet dsDeleted = dsOriginal.GetChanges(DataRowState.Deleted);

Notes

Parent rows marked unchanged may be included in the rows returned if they are required because of relationship constraints.

The GetChanges( ) method can isolate the rows that have been changed so that the entire DataSet doesn't have to be passed to a method that reconciles DataSet changes with the data source.

A null reference is returned if there are no rows matching the specified criteria.

GetXml

 String   xmlString   = DataSet.GetXml();

Returns a string that is the XML representation of the data stored in the DataSet , without the XSD schema information.

Parameter

xmlString: A string containing an XML representation of the data stored in the DataSet .

Example

The following example shows how to use the GetXml( ) method to store the XML representation of a DataSet to a string:

 DataSet ds = new DataSet(); // ... fill the DataSet String xml = ds.GetXml();

Note

This method returns the same result as the WriteXml( ) method with the XmlWriteMode set to IgnoreSchema .

GetXmlSchema

 String   xmlSchemaString   = DataSet.GetXmlSchema();

Returns a string that is the XSD schema for the XML representation of the data stored in the DataSet .

Parameter

xmlSchemaString: A string that is the XSD schema for the XML representation of the data in the DataSet .

Example

The following example shows how to use the GetXml( ) method to store the XML representation of a DataSet schema to a string:

 DataSet ds = new DataSet(); // ... fill the DataSet String xmlSchema = ds.GetXmlSchema();

Note

This method returns the same result as the WriteXmlSchema( ) method except that only the primary schema is written.

HasChanges

 Boolean   hc   = DataSet.HasChanges(); Boolean   hc   = DataSet.HasChanges(DataRowState   drs   );

Returns a value indicating whether data in the DataSet has been modified, inserted, or deleted since it was last loaded or since AcceptChanges( ) was last called. An optional DataRowState argument can be used to filter the results.

Parameters

hc: Returns a Boolean value indicating whether data in the DataSet has been modified, inserted, or deleted since it was last loaded or since AcceptChanges( ) was last called.
drs: One of the values from the DataRowState enumeration. See Table 22-13.

Example

The following example shows how to determine if any rows have been deleted from the DataSet :

 bool hasDeleted = ds.HasChanges(DataRowState.Deleted);

Note

To maximize application performance, call this method to determine whether it is necessary to call the GetChanges( ) method.

InferXmlSchema

 DataSet.InferXmlSchema(Stream   xmlSource   , String[]   nsArray   ); DataSet.InferXmlSchema(String   xmlSource   , String[]   nsArray   ); DataSet.InferXmlSchema(TextReader   xmlSource   , String[]   nsArray   ); DataSet.InferXmlSchema(XmlReader   xmlSource   , String[]   nsArray   );

Infers a schema from the specified XML source into the DataSet .

Parameters

xmlSource: The Stream , filename, TextReader , or XmlReader containing the XML from which to infer the schema.
nsArray: An array of namespace URI strings to be excluded from the inferred schema.

Example

The following example infers the schema from the XML representation of the DataSet :

 DataSet ds1 = new DataSet(); // ... fill the DataSet // write the XML representation of DataSet ds1 to a file, without schema. String fileName = @"c:\MyFile.xml"; ds1.WriteXml(fileName, XmlWriteMode.IgnoreSchema); // infer the schema and load the XML file into DataSet ds2, excluding a // single namespace DataSet ds2 = new DataSet(); ds1.InferXmlSchema(fileName, new String[] {"urn:my-schema:excludeddata"}); ds2.ReadXml(fileName);

Note

The InferXmlSchema( ) method functions the same as both the ReadXml( ) method with the XmlReadMode argument set to InferSchema and the ReadXmlSchema( ) method with an XML document containing only schema information without data. The InferXmlSchema( ) method, however, optionally allows namespaces to be excluded from the inference process.

Merge

 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.

ReadXml

 DataSet.ReadXml(Stream   xmlSource   ); DataSet.ReadXml(String   xmlSource   ); DataSet.ReadXml(TextReader   xmlSource   ); DataSet.ReadXml(XmlReader   xmlSource   ); DataSet.ReadXml(Stream   xmlSource   , XmlReadMode   xrm   ); DataSet.ReadXml(String   xmlSource   , XmlReadMode   xrm   ); DataSet.ReadXml(TextReader   xmlSource   , XmlReadMode   xrm   ); DataSet.ReadXml(XmlReader   xmlSource   , XmlReadMode   xrm   );

Reads XML schema information and data from the specified source into the DataSet .

Parameters

xmlSource: A Stream , filename, TextReader , or XmlReader containing the XML to read the schema and data from.
xrm: One of the XmlReadMode enumeration values described in Table 22-15.

Table 22-15. XmlReadMode enumeration

Value	Description
Auto	Sets the `XmlReadMode` based on the data contained in the source. If the data is a `Diffgram` , the `XmlReadMode` is set to `Diffgram` . If either the `DataSet` has a schema defined or the XML document contains an inline XSD schema, the `XmlReadMode` is set to `ReadSchema` . If the `DataSet` doesn't have a schema and the XML document doesn't contain an inline XSD schema, the `XmlReadMode` is set to `InferSchema` . This is the default value.
Diffgram	Applies the changes specified by the `Diffgram` to the `DataSet` . The `Diffgram` for the source `DataSet` should be generated using the `WriteXml()` method specifying `XmlWriteMode` of `Diffgram` . An exception is thrown if the `DataSet` doesn't have the same schema as `DataSet` for which the `DiffGram` was generated.
Fragment	Reads an XML document using the default namespace as the inline schema.
IgnoreSchema	Reads the XML into the `DataSet` schema, ignoring any inline schema that might be present.
InferSchema	Reads the XML into the `DataSet` , inferring a schema and ignoring any inline schema that might be present. If the `DataSet` contains a schema that conflicts with the inferred schema, an exception is thrown.
ReadSchema	Reads the inline schema and loads data into the `DataSet` . If the `DataSet` contains a schema for tables defined in the inline schema, an exception is thrown.

Example

The following example shows how to use the ReadXml( ) and WriteXml( ) methods to read and write the XML representation of a DataSet along with the DataSet schema:

 DataSet ds1 = new DataSet(); // ... fill the DataSet // write the XML representation of DataSet ds1 to a file, with schema. String fileName = @"c:\MyFile.xml"; ds1.WriteXml(fileName, XmlWriteMode.WriteSchema); // load the XML file into DataSet ds2, with schema. DataSet ds2 = new DataSet(); ds2.ReadXml(fileName, XmlReadMode.ReadSchema);

Note

The ReadXml( ) method can read the XML representation of the DataSet previously written using the WriteXml( ) method into a DataSet .

ReadXmlSchema

 DataSet.ReadXmlSchema(Stream   xmlSchemaSource   ); DataSet.ReadXmlSchema(String   xmlSchemaSource   ); DataSet.ReadXmlSchema(TextReader   xmlSchemaSource   ); DataSet.ReadXmlSchema(XmlReader   xmlSchemaSource   );

Reads a XSD schema from the specified XML source into the DataSet schema.

Parameter

xmlSchemaSource: A Stream , filename, TextReader , or XmlReader containing the XML to read the schema and data from.

Example

The following example shows how to use the ReadXmlSchema( ) and WriteXmlSchema( ) methods to read and write the XML representation of the schema of a DataSet :

 DataSet ds1 = new DataSet(); // ... fill the DataSet String fileName = @"c:\MyFile.xml"; // create a FileStream and XmlTextWriter System.IO.StreamWriter fsWrite = new System.IO.StreamWriter(fileName); System.Xml.XmlTextWriter xw = new System.Xml.XmlTextWriter(fsWrite); // write the XML schema of DataSet ds1 and close the XmlTextWriter. ds1.WriteXmlSchema(xw); xw.Close(); // create a FileStream and XmlTextReader System.IO.StreamReader fsRead = new System.IO.StreamReader(fileName); System.Xml.XmlTextReader xr = new System.Xml.XmlTextReader(fsRead); // load the schema into DataSet ds2 and close the XmlTextReader. DataSet ds2 = new DataSet(); ds2.ReadXmlSchema(xr); xr.Close();

Note

The ReadXmlSchema( ) method can read the XSD schema of a DataSet previously written using the WriteXmlSchema( ) method back to a DataSet .

RejectChanges

 DataSet.RejectChanges();

Rejects all changes made to the DataSet since the last time it was loaded or since the last time AcceptChanges( ) was called.

Parameters

None.

Example

The following example demonstrates how to call the RejectChanges( ) method of the DataSet and the effect of calling the RejectChanges( ) method on the row state:

 DataSet ds = new DataSet(); // create a table with a single column DataTable dt = ds.Tables.Add(); dt.Columns.Add("MyColumn", typeof(System.Int32)); DataRow row; row = dt.NewRow(); row["MyColumn"] = 1; dt.Rows.Add(row);      // RowState = Added ds.AcceptChanges();    // RowState = Unchanged row["MyColumn"] = 2;   // RowState = Modified ds.RejectChanges();    // RowState = Unchanged, row["MyColumn"] = 1 row.Delete();          // RowState = Deleted ds.RejectChanges();    // RowState = Unchanged                        // The row isn't removed from the DataTable.

Notes

Calling RejectChanges( ) sets the RowState property of Deleted and Modified rows to Unchanged ; the current values in the DataRow are set to the original values. Added rows are removed.

Calling the RejectChanges( ) method on the DataSet causes RejectChanges( ) to be called on each DataTable belonging to the DataSet .

When the RejectChanges( ) method is called, any rows in edit mode, as a result of calling BeginEdit( ) , cancel their edits.

Calling RejectChanges( ) clears all RowError information and sets the HasErrors properties to false .

Reset

 DataSet.Reset()

Discards the contents of the DataSet , resetting it to an uninitialized state.

Parameters

None.

Example

The following example shows how reset a DataSet to its original state:

 ds.Reset();

Note

Calling Reset( ) on an existing DataSet is more efficient than instantiating a new DataSet .

WriteXml

 DataSet.WriteXml(Stream   xmlDest   ); DataSet.WriteXml(String   xmlDest   ); DataSet.WriteXml(TextWriter   xmlDest   ); DataSet.WriteXml(XmlWriter   xmlDest   ); DataSet.WriteXml(Stream   xmlDest   , XmlWriteMode   xwm   ); DataSet.WriteXml(String   xmlDest   , XmlWriteMode   xwm   ); DataSet.WriteXml(TextWriter   xmlDest   , XmlWriteMode   xwm   ); DataSet.WriteXml(XmlWriter   xmlDest   , XmlWriteMode   xwm   );

Writes the data, and optionally the schema, from the DataSet to a specified destination.

Parameters

xmldest: The Stream , filename, TextReader , or XmlReader into which to write the XML representation of the DataSet .
xwm: One of the values from the XmlWriteMode enumeration. See Table 22-16 for common XmlWriteMode enumeration values.

Table 22-16. XmlWriteMode enumeration

Value	Description
Diffgram	The entire `DataSet` is written as a `DiffGram` , including both original and current values for the data rows.
IgnoreSchema	An XML representation of the data in the `DataSet` is written without an XSD schema.
WriteSchema	An XML representation of the data in the `DataSet` is written together with its relational structure as an inline XSD schema. This is the default value.

Example

See the Example for the ReadXml( ) method in this chapter.

Note

The ReadXml( ) method can load the DataSet with the contents of XML previously written using the WriteXml( ) method.

WriteXmlSchema

 DataSet.WriteXmlSchema(Stream xmlSchemaDest); DataSet.WriteXmlSchema(String xmlSchemaDest); DataSet.WriteXmlSchema(TextWrite xmlSchemaDest); DataSet.WriteXmlSchema(XmlWriter xmlSchemaDest);

Writes the XSD schema from the DataSet to a specified destination.

Parameter

xmlSchemaDest: The Stream , filename, TextReader , or XmlReader into which to write the XSD schema of the DataSet .

Example

See the Example for the ReadXmlSchema method in this chapter.

Note

The XSD schema written by the WriteXmlSchema( ) method can later be loaded back to a DataSet using the ReadXmlSchema( ) method.