| [ Team LiB ] |
|
22.3 Collections Reference
Accesses the PropertyCollection object of the DataSet, which allows custom information about the DataSet to be stored. ExampleThe following example shows how to set and retrieve custom information for the DataSet using ExtendedProperties: // set
ds.ExtendedProperties.Add("MyKey", "MyCustomData");
// get
String customData = ds.ExtendedProperties["MyKey"].ToString();
NotesNonstring properties aren't persisted when the DataSet is written as XML. The commonly used public properties of the PropertyCollection are listed and described in Table 22-7.
The commonly used public methods of the PropertyCollection are listed and described in Table 22-8.
Accesses the DataRelationCollection contained in a DataSet that contains the child DataRelation objects belonging to the DataSet. These objects relate tables in the DataSet using their primary and foreign keys and allow navigation between parent and child tables in both directions. ExamplesThe DataRelationCollection has two methods that are used to add relations to the DataSet. The first is the Add( ) method, which in its simplest form takes a single DataRelation argument as shown in the following example: DataRelation dr = new DataRelation("MyDataRelation",
parentTable.Columns["PrimaryKeyField"],
childTable.Columns["ForeignKeyField"]);
ds.Relations.Add(dr);
The other overloaded versions of the Add( ) method allow a DataRelation object to be created and added to the DataSet in a single statement, as shown in the following example: DataTable dt1;
DataColumn col1, col2;
// ... code to define columns col1 and col2 and add them to the table dt1
DataTable dt2;
DataColumn col3, col4;
// ... code to define columns col3 and col4 and add them to the table dt2
DataSet ds = new DataSet();
ds.Tables.Add(dt1);
ds.Tables.Add(dt2);
// add a relation to the DataRelationCollection called MyRelation
// and create the ForeignKey constraint between parent col1 and child col3
ds.Relations.Add("MyRelation", col1, col3, true);
// add the relation between parent columns col1 and col2 and child columns
// col3 and col4. Do not create the ForeignKey constraint.
ds.Relations.Add("MyRelation", new DataColumn[] {col1, col2},
new DataColumn[] {col3, col4}, false);
More than one DataRelation can be added to a DataSet in a single statement using the AddRange( ) method. This method adds DataRelation objects from a DataRelation array to the end of the DataRelationCollection, as the following example illustrates: // code to create DataRelations dr1 and dr2
ds.Relations.AddRange(new DataRelation[] {dr1, dr2});
The IndexOf( ) method allows the index of an existing relation to be retrieved from the DataRelationCollection. This method has two overloads that allow the relation to be located using either the relation name or a reference to the relation, as shown in the following examples: Int32 index = ds.Relations.IndexOf("MyDataRelation");
Int32 index = ds.Relations.IndexOf(dr);
The value returned by the IndexOf( ) method is zero-based. A value of -1 is returned if the specified relation object doesn't exist within the collection. There are also two methods that can remove a relation from the DataRelationCollection. The Remove( ) method removes a relation matching the relation name argument. The RemoveAt( ) method removes the relation at a specified index from the DataRelationCollection. The following examples illustrate both methods: // remove the relation names MyDataRelation from the
// DataRelationCollection for the DataSet
ds.Relations.Remove("MyDataRelation");
// remove the first relation in the DataRelationCollection for the DataSet
ds.Relations.RemoveAt(0);
Finally, the Clear( ) method removes all the relations from the DataSet, as shown in the following example: ds.Relations.Clear(); NotesThe commonly used public properties of the DataRelationCollection are listed and described in Table 22-9.
The commonly used public methods of the DataRelationCollection are listed and described in Table 22-10.
Accesses the DataTableCollection contained by the DataSet that contains the DataTable objects belonging to the DataSet. ExampleThe DataTableCollection has two methods that can add a table to a DataSet. The Add( ) method takes an optional table name argument and is used to add tables to the DataTableCollection. If this argument isn't supplied, the tables are automatically named Table, Table1, Table2, and so on. The following example adds a table to a DataSet: DataSet ds = new DataSet("MyDataSet");
DataTable dt = new DataTable("MyTable");
// ... code to define the schema for the newly constructed DataTable
ds.Tables.Add(dt);
Alternatively, a DataTable can first be constructed within the DataTablesCollection and subsequently have its schema defined: DataSet ds = new DataSet("MyDataSet");
DataTable dt = ds.Tables.Add("MyTable");
// ... code to define the schema for newly constructed DataTable
A reference to the table that already exists within the DataSet can be retrieved. Most commonly, this is done using the table name or the table ordinal as shown in these examples: // using the table name
DataTable dt = ds.Tables("MyTable");
// using the table ordinal
DataTable dt = ds.Tables[0];
The Count property returns the number of tables in the DataSet, as shown here: Int32 tableCount = ds.Tables.Count; The Contains( ) method returns whether a specific DataTable exists within a DataSet, as shown next: bool tableExists = ds.Tables.Contains("MyTable");
Existing tables within the DataSet can be accessed by an indexer, which most commonly is passed the table name or the position of the table within the DataTableCollection as an argument as shown in these examples: // using the table name DataTable dt = ds.Tables["MyTable"]; // access the first table in the collection using the table ordinal DataTable dt = ds.Tables[0]; The IndexOf( ) method allows the index of the table within the collection to be retrieved using either a reference to the table object or the table name. The following example demonstrates both techniques: // get the index using the name of the table
Int32 tableIndex = ds.Tables.IndexOf("MyTable");
// get the index using a reference to a table
DataTable dt = ds.Tables.Add("MyTable");
// ... build the table and do some work
// get the index of the table based on the table reference
Int32 tableIndex = ds.Tables.IndexOf(dt);
The DataTableCollection provides a number of other useful methods and properties. The AddRange( ) method allows more than one table to be added to the DataSet at the same time. The method takes an array of DataTable objects as the argument as the following examples show: // create two new tables
DataTable dt1 = new DataTable();
DataTable dt2 = new DataTable();
// use the AddRange method to add them to the DataSet.
ds.Tables.AddRange(new DataTable[] {dt1, dt2});
There are also two methods that remove tables from a DataSet: the Remove( ) and RemoveAt( ) method. The Remove( ) method takes either the table name or a reference to the table to be removed as an argument as shown in the following example: DataTable dt = ds.Tables.Add("MyTable");
// remove by table reference
ds.Tables.Remove(dt);
// remove using the table name
ds.Tables.Remove("MyTable");
The RemoveAt( ) method removes the table using the index of the table in the DataSetCollection of the DataSet as shown in the following example: // removes the first table from the tables collection in the DataSet ds.Tables.RemoveAt(0); If you need to remove all tables from a DataSet, the Clear( ) method can be used. It takes no arguments and can be used as shown next: ds.Tables.Clear(); NotesThe commonly used public properties of the DataTableCollection are listed and described in Table 22-11.
The commonly used public methods of the DataTableCollection are listed and described in Table 22-12.  |
| [ Team LiB ] |
|