Adding custom metadata providers in ASP.NET 3.5 Extensions Preview

5/22/08 Note: this post talks about an outdated ASP.NET release. Please have a look at this updated dynamic metadata provider sample.

One of the most powerful elements of the new ASP.NET Dynamic Data feature we are working on is the ability to associate metadata (for example, range validation or formatting) with your data model. You can then query the model and use the provided information to customize the processing of your data. In the recently released ASP.NET 3.5 Extensions Preview this annotation is done by declaring special metadata attributes on the partial classes representing the entities in the model. The initial implementation is a bit limited, however, because the metadata association can only be done using CLR attributes and those attributes have to be declared on the class (even if they pertain to the class's properties):

[Range("Quantity", 0, 10000)] 
[Range("Price", 0, 20000)] 
partial class Product { 
}

A better approach

The MVC Toolkit (which incorporates a number of modifications to the Preview that will be included in later milestones – download here) contains an alternative implementation. This implementation has the following improvements:

• A pluggable metadata model based on providers.
• New metadata attributes that can be declared on the properties of a special metadata "buddy" class.
• An alternative reference provider implementation based on XML files.

The best way to familiarize yourself with the new model is to look at the samples included with the MVC toolkit. However, here are a few points to get you started:

1. The registration of a metadata handler is done on a DataContext type using the MetadataHandlerRegistration class. This needs to be done only once per application, for example in the Global.asax file:

   protected void Application_Start(object sender, EventArgs e) {
       MetadataHandlerRegistration.Register(
           typeof(MyDataContext), 
           MetadataHandlerRegistration.XmlMetadataProvider);
   }

   Note: Only Linq to SQL models are supported in this version. Future releases will support both Linq to SQL and ADO.NET Entities.
2. MetadataHandlerRegistration contains references to 2 different metadata providers: buddy class-based and XML file-based.

Buddy class metadata

Buddy class metadata is a model in which you associate a "buddy class" with your actual data model class and declare the metadata attributes on properties of the buddy class. "Why do I need to declare a parallel class?", you ask. The simple answer is that the current versions of C# and VB have no concept of partial properties.

This implementation supports two ways of associating the buddy class:

1. Explicit: using an attribute on the model partial class that points to the type of the buddy class
2. Implicit: using a name matching pattern (append "_Metadata" to the name of the model class and look for a class with that new name in the current namespace/assembly)

Using the explicit option looks like this:

[MetadataClass(typeof(Product_Metadata))]
partial class Product {
}

public class Product_Metadata {
    [Range(0, 10000)]
    public int Quantity { get; set; }
}

Comment out the MetadataClass attribute and you get the implicit option.

XML file metadata

An alternative metadata provider uses an XML file as the metadata store. Currently the file location is hard-coded to be ~/metadata.xml. A very basic metadata.xml file could look like this (a slightly bigger one is included in the sample blog project of the MVC Toolkit):

<metadata xmlns="http://tempuri.org/metadataFile"
    xmlns:m="http://tempuri.org/metadataElements"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://tempuri.org/metadataFile ../Schemas/MetadataFile.xsd
                        http://tempuri.org/metadataElements ../Schemas/MetadataElements.xsd">
  <metadataAttributes>
    <metadataAttribute tagPrefix="m" assembly="MVCToolkit" namespace="Microsoft.Web.DynamicData.Metadata"/>
  </metadataAttributes>
  <tables>
    <table name="Product">
      <columns>
        <column name="Quantity">
          <m:Range Minimum="0" Maximum="100000"/>
        </column>
      </columns>
    </table>
  </tables>
</metadata>

The metadataAttributes section defines metadata attribute mappings. These are used by the logic that creates a CLR attribute type instance from an XML element. For example, the m:Range element will be converted into the class Microsoft.Web.DynamicData.Metadata.RangeAttribute in the MVCToolkit assembly. The attributes on the element are automatically converted and set on the properties of the attribute type instance. You can add your own metadata attribute collection by defining a new metadataAttribute entry.

The tables section allows you to define metadata on all of the tables and their columns that make up your model.

As a final note, most of the attributes on the root metadata element are there to support IntelliSense in your XML editor. The relative URLs work in the sample Dynamic Data MVC blog project. You might have to change some of the paths if you decide to move the XSD files around or if you create a new project in a different location.

Implementation details

The underlying implementation uses the TypeDescriptor mechanism from System.ComponentModel. It is basically a pluggable layer on top of standard reflection. Have a look at the code to learn more.

Conclusion

This post discusses elements that will be incorporated in some way or another in future releases of ASP.NET Extensions. However, some of the implementation details might change. We will certainly have detailed documentation for the final release.

In the meantime feel free to explore the provided code and make sure you give back any feedback you might have on how these features can be improved. You can post your comments/questions at:

ASP.NET 3.5 Extensions Preview discussion
ASP.NET Dynamic Data discussion

Additional resources

Visit these blogs for additional tips on ASP.NET 3.5 Extensions and Dynamic Data:

David Ebbo's ASP.NET blog
Scott Hunter: ASP.NET and .NET Musings