Annotating a Typed DataSet

Annotating a Typed DataSet

When you create a typed DataSet, the XSD tool that generates the C# class provides default names for all of the members, including properties, methods for obtaining child rows, table class names, and row class names. For example, if you were to create a table called Customers, the default class name for a customer would be CustomersRow, not Customer. To access the customer's order history, you would have to use the GetOrderHistoryRows() method rather than something more appropriate like GetOrderHistory().

You can solve this problem by annotating your DataSet. In previous versions of Visual Studio, you could access the XSD text for a typed DataSet directly from within the IDE. For some unknown (and highly aggravating) reason, that feature is no longer present in Visual Studio 2005 by default. To get at the XML view of an XSD file, right-click it in the Solution Explorer and choose Open With and then select the XML Editor option.

When you look at the inside of the XSD file, you will notice that there are a lot of attributes that begin with msprop:Generator_. These are all customizable annotation attributes. By changing these attributes, you can directly control the names of the classes, members, and methods created when the DataSet class is built.

Table 20.1 shows the various annotation attributes and what effect they have on the typed DataSet.

Table 20.1. Annotation Attributes (All Prefixed by msprop:Generator_ Unless Otherwise Specified)

Attribute	Effect
DataSetName	Controls the name of the typed DataSet class.
TableClassName	The name of the class produced for a given table, for example, CustomerTable.
RowChangedName	Name of the RowChanged event fired for row changes on the given table, for example, CustomerChanged.
RowClassName	The name of the class generated to encapsulate one row of the table. By default, this has a Row postfix, such as CustomersRow. This is often one of the first attributes changed when annotating.
RowChangingName	The name of the RowChanging event.
RowEvArgName	The name of the RowChanged event argument class.
RowEvHandlerName	Name of the RowChanged event handler.
TablePropName	Name of the property representing this table within the DataSet, for example, "Customers" or "Orders".
TableVarName	Name of the variable that holds the table inside the class.
ColumnPropNameInRow	Name of the property that represents the given column on a row.
ColumnVarNameInTable	Name of the variable that provides access to the column from within the table class.
ColumnPropNameInTable	The name of the column property in the table. Typically has a "Column" postfix.
rel_Generator_ParentPropName	The name of the parent when accessed from the parent; defaults to the class name of the row. Can be set to things like "Customer" or "Order".
rel_Generator_ChildPropName	The name of the method used to obtain child rows from a parent row. Defaults to Get(childtable)Rows. Often set to names like "GetOrderItems" or "GetChildItems", and so on.

With several of the preceding annotations applied to a typed DataSet containing customer data with a Customers table and an OrderHistory table, you can write code that looks much cleaner and is far more readable than code generated with no annotations:

using System; using System.Collections.Generic; using System.Text; namespace AnnotateDS { class Program { static void Main(string[] args) {     CustomerDataSet custData = new CustomerDataSet();     // populate data from some location...     foreach (CustomerDataSet.Customer cust in custData.Customers)     {         Console.WriteLine("Customer {0} {1}", cust.FirstName, cust.LastName);         Console.WriteLine("Order History:");         foreach (CustomerDataSet.OrderHistoryItem histItem in cust.GetOrderHistory())         {             Console.WriteLine("\t{0} - ${1:00.00}", histItem.OrderID,                 histItem.TotalPrice);         }     } } } } 

Because the contents of an XSD file can get fairly bloated, I will only show you the annotated "Customers" element from the preceding typed DataSet:

<xs:element name="Customers"   msprop:Generator_UserTableName="Customers"   msprop:Generator_RowDeletedName="CustomerDeleted"               msprop:Generator_TableClassName="CustomerTable"   msprop:Generator_RowChangedName="CustomerChanged"           msprop:Generator_RowClassName="Customer"               msprop:Generator_RowChangingName="CustomerChanging"               msprop:Generator_RowEvArgName="CustomerChangeEvent"     msprop:Generator_RowEvHandlerName="CustomerChangeEventHandler"     msprop:Generator_TablePropName="Customers"     msprop:Generator_TableVarName="tableCustomers"     msprop:Generator_RowDeletingName="CustomerDeleting">     <xs:complexType>       <xs:sequence>         <xs:element name="ID" msdata:AutoIncrement="true" msprop:Generator_UserColumnName="ID" msprop:Generator_ColumnPropNameInRow="ID" msprop:Generator_ColumnVarNameInTable="columnID"  msprop:Generator_ColumnPropNameInTable="IDColumn" type="xs:int" />         <xs:element name="FirstName" msprop:Generator_ UserColumnName="FirstName" msprop:Generator_ColumnPropNameInRow="FirstName" msprop:Generator_ColumnVarNameInTable="columnFirstName" msprop:Generator_ColumnPropNameInTable="FirstNameColumn" type="xs:string" minOccurs="0" />         <xs:element name="LastName" msprop:Generator_UserColumnName="LastName"  msprop:Generator_ColumnPropNameInRow="LastName" msprop:Generator_ColumnVarNameInTable="columnLastName" msprop:Generator_ColumnPropNameInTable="LastNameColumn" type="xs:string" minOccurs="0" />       </xs:sequence>     </xs:complexType>   </xs:element>