| [ Team LiB ] |
|
22.4 Methods Reference
Commits all changes made to the DataSet since the last time it was loaded or since the last time AcceptChanges( ) was called. ParametersNone. ExampleThe 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
NotesCalling 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.
Removes all data rows from the DataSet. ParametersNone. ExampleThe 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.
Creates a new DataSet with the same schema as the current DataSet but which contains none of the data. Parameter
ExampleThe 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();
Creates a new DataSet having the same schema and containing the same data as the original DataSet. Parameter
ExampleThe 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();
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
ExampleThe 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); NotesParent 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.
Returns a string that is the XML representation of the data stored in the DataSet, without the XSD schema information. Parameter
ExampleThe 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(); NoteThis method returns the same result as the WriteXml( ) method with the XmlWriteMode set to IgnoreSchema.
Returns a string that is the XSD schema for the XML representation of the data stored in the DataSet. Parameter
ExampleThe 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(); NoteThis method returns the same result as the WriteXmlSchema( ) method except that only the primary schema is written.
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
ExampleThe following example shows how to determine if any rows have been deleted from the DataSet: bool hasDeleted = ds.HasChanges(DataRowState.Deleted); NoteTo maximize application performance, call this method to determine whether it is necessary to call the GetChanges( ) method.
Infers a schema from the specified XML source into the DataSet. Parameters
ExampleThe 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);
NoteThe 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.
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
ExampleThe following example demonstrates how to merge a source DataSet into a target DataSet: // Merge DataSet mergeDs into DataSet ds ds.Merge(mergeDs); NotesThe 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.
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.
Reads XML schema information and data from the specified source into the DataSet. Parameters
ExampleThe 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); NoteThe ReadXml( ) method can read the XML representation of the DataSet previously written using the WriteXml( ) method into a DataSet.
Reads a XSD schema from the specified XML source into the DataSet schema. Parameter
ExampleThe 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(); NoteThe ReadXmlSchema( ) method can read the XSD schema of a DataSet previously written using the WriteXmlSchema( ) method back to a DataSet.
Rejects all changes made to the DataSet since the last time it was loaded or since the last time AcceptChanges( ) was called. ParametersNone. ExampleThe 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.
NotesCalling 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.
Discards the contents of the DataSet, resetting it to an uninitialized state. ParametersNone. ExampleThe following example shows how reset a DataSet to its original state: ds.Reset(); NoteCalling Reset( ) on an existing DataSet is more efficient than instantiating a new DataSet.
Writes the data, and optionally the schema, from the DataSet to a specified destination. Parameters
ExampleSee the Example for the ReadXml( ) method in this chapter. NoteThe ReadXml( ) method can load the DataSet with the contents of XML previously written using the WriteXml( ) method.
Writes the XSD schema from the DataSet to a specified destination. Parameter
ExampleSee the Example for the ReadXmlSchema method in this chapter. NoteThe XSD schema written by the WriteXmlSchema( ) method can later be loaded back to a DataSet using the ReadXmlSchema( ) method.  |
| [ Team LiB ] |
|