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.
None.
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
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.
None.
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.
Returns the new DataSet with the same schema as the original but none of the data.
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.
Returns the new DataSet with the same schema and data as the original.
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.
Returns the DataSet with all changes made to the original since it was last loaded or AcceptChanges( ) was last called.
A DataRowState enumeration value as described in Table 22-13 specifying the row state of the DataRow objects to return.
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. |
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);
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.
A string containing an XML representation of the data stored in the DataSet.
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();
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.
A string that is the XSD schema for the XML representation of the data in the DataSet.
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();
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.
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.
One of the values from the DataRowState enumeration. See Table 22-13.
The following example shows how to determine if any rows have been deleted from the DataSet:
bool hasDeleted = ds.HasChanges(DataRowState.Deleted);
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.
The Stream, filename, TextReader, or XmlReader containing the XML from which to infer the schema.
An array of namespace URI strings to be excluded from the inferred schema.
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);
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.
The array of DataRow objects, the DataSet, or the DataTable to be merged into the DataSet.
Indicates whether changes that have already been made to the target DataSet should be maintained when merging.
One of the values from the MissingSchemaAction enumeration described in Table 22-14.
The following example demonstrates how to merge a source DataSet into a target DataSet:
// Merge DataSet mergeDs into DataSet ds ds.Merge(mergeDs);
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.
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.
A Stream, filename, TextReader, or XmlReader containing the XML to read the schema and data from.
One of the XmlReadMode enumeration values described in Table 22-15.
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. |
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);
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.
A Stream, filename, TextReader, or XmlReader containing the XML to read the schema and data from.
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();
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.
None.
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.
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.
None.
The following example shows how reset a DataSet to its original state:
ds.Reset();
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.
The Stream, filename, TextReader, or XmlReader into which to write the XML representation of the DataSet.
One of the values from the XmlWriteMode enumeration. See Table 22-16 for common XmlWriteMode enumeration values.
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. |
See the Example for the ReadXml( ) method in this chapter.
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.
The Stream, filename, TextReader, or XmlReader into which to write the XSD schema of the DataSet.
See the Example for the ReadXmlSchema method in this chapter.
The XSD schema written by the WriteXmlSchema( ) method can later be loaded back to a DataSet using the ReadXmlSchema( ) method.