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.



    Part I: ADO.NET Tutorial
    Part II: ADO.NET Core Classes
    Part III: API Quick Reference