Extended Properties

for RuBoard

As you might have noticed, each of the DataSet , DataTable , DataColumn , and DataRelation classes exposes a PropertyCollection object through its ExtendedProperties property. The PropertyCollection class is found in the System.Data namespace and is derived from System.Collections.Hashtable . As a result, a PropertyCollection stores a set of key and value pairs that are stored based on the hash value of the key.

You typically use the extended properties collection to store metadata for the object. As an example, for a DataSet , you might store the date and time the data was retrieved from the data store, or calculate a time at which the data should be refreshed. For a DataTable , you might store the criteria that were used when retrieving the data, or the connection string used to connect to the data store. For a DataColumn , you might store comments or a description of what data is stored in the column. These values can then be used both for display to a user of the application and for diagnostic purposes in the event of an exception. For example, Listing 4.6 demonstrates the creation of several properties for a DataSet used to cache data from the Orders and OrderDetails tables.

Listing 4.6 Populating extended properties. This method populates the dsOrders DataSet and populates several extended properties.

 Public Function GetOrders(ByVal custID As Guid) As DataSet   Dim con As New SqlConnection(Me.ConnectString)   Dim da As New SqlDataAdapter("usp_GetOrders", con)   Dim orders As New DataSet("Orders")   da.SelectCommand.CommandType = CommandType.StoredProcedure   da.SelectCommand.Parameters.Add(New SqlParameter("@CustomerID", custID))   da.Fill(orders)   orders.Tables(0).TableName = "Orders"   orders.Tables(1).TableName = "OrderDetails"   With orders     .ExtendedProperties.Add("TimeRetrieved", Now)     .ExtendedProperties.Add("CustomerID", custID)     .ExtendedProperties.Add("ConnectString", con.ConnectionString)     .ExtendedProperties.Add("CommandText", da.SelectCommand.CommandText)   End With   Return orders End Function 

The properties can then be either accessed individually by passing the key value to the ExtendedProperties collection, or traversed using an enumerator as shown in the following code snippet:

 Try   ' Attempt to update the DataSet   da.Update(orders.GetChanges()) Catch e As Exception   ' Log the error   Dim props As IDictionaryEnumerator = orders.ExtendedProperties.GetEnumerator()   While props.MoveNext     Trace.WriteLine(props.Key.ToString() & " = " & props.Value.ToString())   End While   ' Other error handling here End Try 

In the previous snippet, the code is attempting to update the data store with changed rows from the dOrders DataSet . If an exception occurs, the Catch block is used to first write all the extended properties to the Trace object for logging. To traverse the properties, the GetEnumerator method of the PropertyCollection object is called to return an enumerator that implements the IDictionaryEnumerator interface. This interface exposes a MoveNext method that is then used to traverse the collection in a loop. Because the collection is positioned before the first element, the MoveNext property can be called at the top of the loop as shown here.

Note

In addition to the properties shown, the IDictionaryInterface exposes the Current and Entry properties and the Reset method. The properties are used to represent the key and value pair the enumerator current points to, whereas the Reset method moves the pointer back before the first element in the collection.

The only downside to using extended properties is that they aren't represented when the DataSet is serialized to XML using the WriteXml method or returned through an XML Web Service. However, they are included when the DataSet is transported using .NET Remoting.

for RuBoard