13.7 Annotations

By default, strongly typed DataSet classes use names from the underlying tables and columns in the data source to generate the names of methods, properties, and events. Annotations allow the names of elements in the typed DataSet to be changed without modifying the underlying schema. The names can be made more meaningful, making the strongly typed DataSet easier to use and the code using it more readable.

To use annotations, the codegen namespace declaration must be added to the XSD file. This can be placed directly after the msdata namespace declaration at the beginning of the file:

<?xml version="1.0" standalone="yes"?>
<xs:schema id="NewDataSet" xmlns="" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"
    xmlns:codegen="urn:schemas-microsoft-com:xml-msprop">

Annotations can be used to change the names of elements in the strongly typed DataSet. Using the Categories table in Northwind as an example, the default schema results in a DataRow name of CategoriesRow and a DataRowCollection name of Categories in the strongly typed DataSet. Here's an excerpt from the default schema:

<xs:element name="Categories">

Specifying the typedName and the typedPlural in the schema element changes the name of the DataRow to Category and the name of the DataRowCollection to Categorys. Here's the new XSD schema:

<xs:element name="Categories"
    codegen:typedName="Category" codegen:typedPlural="Categorys">

Annotations can also change the names of methods that navigate relationships. Here's the automatically generated code relating Categories to Products:

<xs:keyref name="Categories_Products" refer="Constraint1">
    <xs:selector xpath=".//Products" />
    <xs:field xpath="CategoryID" />
</xs:keyref>

Adding the typedParent and typedChildren attributes to the relationship allows the method Category.Products( ) to be used instead of the default Category.GetProductsRows( ) to retrieve the child records for a product:

<xs:keyref name="Categories_Products" refer="Constraint1"
    codegen:typedParent="Categories" codegen:typedChildren="Products">
    <xs:selector xpath=".//Products" />
    <xs:field xpath="CategoryID" />
</xs:keyref>

Annotations can also control the way null values in the underlying data source are handled. The default schema element for the Description field of the Categories table in Northwind is a null value as shown here:

<xs:element name="Description" type="xs:string" minOccurs="0" />

By specifying a nullValue annotation, the default value for the Description field in the typed DataSet will be an empty string when the value for the Description is null in the underlying data source. Here's the annotated schema element for the field:

<xs:element name="Description" type="xs:string" minOccurs="0"
    codegen:nullValue="" />

This section introduced the use of annotations with strongly typed DataSet objects. Appendix B provides complete coverage of the available annotations in the codegen namespace.