22.3 Collections Reference

ExtendedProperties

PropertyCollection ep = DataSet.ExtendedProperties;
DataSet.ExtendedProperties = ep;

Accesses the PropertyCollection object of the DataSet, which allows custom information about the DataSet to be stored.

Example

The 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();

Notes

Nonstring 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.

Table 22-7. PropertyCollection public properties

Property

Description

Count

Gets the number of items in the property collection.

Item

Gets an object containing the value for the specified key from the PropertyCollection. If the value isn't found, attempting to get it returns null. Attempting to set a value either creates a new key-value pair if the specified key isn't found or replaces the existing value for the key. In C#, the Item property is the indexer for the class.

The commonly used public methods of the PropertyCollection are listed and described in Table 22-8.

Table 22-8. PropertyCollection public methods

Method

Description

Add(  )

Adds an item to the PropertyCollection with the specified key and value.

Clear(  )

Removes all items from the PropertyCollection.

Clone(  )

Creates a shallow copy of the PropertyCollection.

Contains(  )

Returns a Boolean value indicating whether a specified key exists in the PropertyCollection.

ContainsKey(  )

Returns a Boolean value indicating whether a specified key exists in the PropertyCollection.

CopyTo(  )

Copies the items in the PropertyCollection to a one-dimensional array, starting at a specified index.

GetEnumerator(  )

Returns an IDictionaryEnumerator that can be used to iterate through the PropertyCollection.

Remove(  )

Removes the item with the specified key from the PropertyCollection.

Relations

DataRelationCollection drc = DataSet.Relations;

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.

Examples

The 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();

Notes

The commonly used public properties of the DataRelationCollection are listed and described in Table 22-9.

Table 22-9. DataRelationCollection public properties

Property

Description

Count

Gets the number of items in the DataRelationCollection.

Item

Gets the specified DataRelation from the DataRelationCollection. In C#, the Item property is the indexer for the class.

The commonly used public methods of the DataRelationCollection are listed and described in Table 22-10.

Table 22-10. DataRelationCollection public methods

Method

Description

Add(  )

Adds a DataRelation object to the collection.

AddRange(  )

Adds the objects in the array of DataRelation objects to the end of the collection.

CanRemove(  )

Returns a Boolean value indicating whether a specific item can be removed from the collection.

Clear(  )

Removes all items from the collection.

Contains(  )

Returns a Boolean value indicating whether a DataRelation with the specified name exists in the collection.

IndexOf(  )

Returns the index of the specified DataRelation. A value of -1 is returned if the DataRelation doesn't exist in the collection.

Remove(  )

Removes the specified DataRelation from the collection. An ArgumentException is generated if the specified DataRelation doesn't exist in the collection.

RemoveAt(  )

Removes the DataRelation at the specified index from the collection. An ArgumentException is raised if the collection doesn't have a DataRelation at the specified index.

Tables

DataTableCollection dtc = DataSet.Tables;

Accesses the DataTableCollection contained by the DataSet that contains the DataTable objects belonging to the DataSet.

Example

The 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();

Notes

The commonly used public properties of the DataTableCollection are listed and described in Table 22-11.

Table 22-11. DataTableCollection public properties

Property

Description

Count

Gets the number of table objects in the DataTableCollection.

Item

Gets the specified DataTable object from the DataTableCollection. In C#, the Item property is the indexer for the class.

The commonly used public methods of the DataTableCollection are listed and described in Table 22-12.

Table 22-12. DataTableCollection public methods

Method

Description

Add(  )

Adds a DataTable object to the collection.

AddRange(  )

Adds the objects in the array of DataTable objects to the end of the collection.

CanRemove(  )

Returns a Boolean value indicating whether a specific table can be removed from the collection.

Clear(  )

Removes all tables from the collection.

Contains(  )

Returns a Boolean value indicating whether a DataTable with the specified name exists in the collection.

IndexOf(  )

Returns the zero-based index of the specified DataTable. The value -1 is returned if the DataTable doesn't exist in the collection.

Remove(  )

Removes the specified DataTable from the collection. An ArgumentException is generated if the specified DataTable doesn't exist in the collection.

RemoveAt(  )

Removes the DataTable at the specified index from the collection. An ArgumentException is raised if the collection doesn't have a DataTable at the specified index.



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