Marcin On ASP.NET : metadata

Dynamic Data samples: Custom metadata providers

marcind — Fri, 23 May 2008 02:35:00 GMT

6/25 Update: This sample has become part of the Dynamic Data Futures project on codeplex. You can still use this code but you should check out the Futures project as it contains a lot more. The key conecpts are the same, though some names or APIs might have changed.

Note: This post is part of a series, see the list of other Dynamic Data samples.

A while back I posted some sample code for adding custom metadata providers. Since then much has changed in the Dynamic Data runtime and it is time to post an updated version. This sample illustrates how to write a custom metadata provider that allows you to programmatically add metadata attributes to an in-memory store before you register your model with the Dynamic Data runtime in Global.asax.

This sample should work with the latest preview release of Dynamic Data.

Running the sample

Download the metadata provider sample solution, extract to your preferred location, and open in Visual Studio 2008 SP1. The solution contains two projects: a sample website and a small library project that contains the metadata provider code.

Run the included website and go the Products list page. Once there hit Edit on any of the rows. You will be taken to a details view for the row you are editing. Change the UnitsInStock field to a negative value and move out of the field: a range validation error appears. Go back to the same field, clear it, and move out again: a required validation error appears.

How it works

The website scaffolds a small subset of the Northwind sample database. The UnitsInStock column on the Product table is decorated with two attributes: RequiredAttribute and RangeAttribute. However, the unique thing here is that each attribute is coming from a different source.

The RequiredAttribute is declared in the default Dynamic Data way using a metadata proxy class:

[MetadataType(typeof(Product_MD))]
public partial class Product {

    private class Product_MD {
        [Required(ErrorMessage="This field is required [from MetadataType]")]
        public object UnitsInStock { get; set; }
    }
}

The RangeAttribute is added to the InMemoryMetadataManager class in Global.asax:

InMemoryMetadataManager.AddColumnAttributes<Product>(p => p.UnitsInStock,
    new RangeAttribute(0, 1000) { 
        ErrorMessage = "This field must be between {1} and {2} [from InMemeroyMetadataManager]." }
);

The AddColumnAttributes function shown here has a way to strongly type the property references (as opposed to writing something like AddColumnAttributes("UnitsInStock", ...)) using a simple lambda expression. This provides for some nice IntelliSense support that would not be available if you were referring to properties using simple strings.

In order to have the Dynamic Data runtime pick up the metadata attributes added to InMemoryMetadataManager you need to modify your model registration call in Global.asax:

model.RegisterContext(typeof(NorthwindDataContext), new ContextConfiguration() {
    ScaffoldAllTables = true,
    MetadataProviderFactory =
        (type => new InMemoryMetadataTypeDescriptionProvider(type, new AssociatedMetadataTypeTypeDescriptionProvider(type)))
});

The MetadataProviderFactory property of ContextConfiguration lets you specify a metadata provider factory method that is used by the Dynamic Data runtime to obtain an instance of a TypeDescriptionProvider that acts as the source of metadata attributes for a given table (type). The sample above also illustrates TypeDescriptionProvider chaining, which is what supports the fact that the table receives metadata from two sources: the InMemory provider adds its metadata to the results returned by the AssociatedMetadataType provider and returns a combined collection.

Truly dynamic metadata

At this point it is tempting to consider a dynamic metadata provider that would let you add, remove, and modify attributes throughout the lifetime of the application and not just during the application's startup phase. For example, you could imagine having some sort of administrative interface that would let you turn on and off whether a field is required or modify its description, even after the model has already been registered.

While it would seem that such a scenario would require minimal changes to the InMemoryMetadataManager class there is one detail about Dynamic Data that makes this a lot more complicated: the current Dynamic Data runtime fetches the metadata upon model registration and then caches it inernally for the lifetime of the app domain. This means that any changes that you make to the metadata through InMemoryMetadataManager after the model has been registered will be ignored.

This is a limitation of Dynamic Data that we will address in future versions. For the time being the only way to get around this would be to unload the app domain. However, this is means that you will need to find a place (such as a database) to store the new metadata while the app restarts.

What about the XML metadata?

My old custom metadata provider sample had an implementation of an XML-based metadata provider but the current one does not. The reason for this is that since the December CTP we have added support for even more attributes and some of the attributes have become a lot more complex. Because much of the old sample had to do with deserializing CLR attributes from an XML representation instead of anything specific to Dynamic Data I decided not to develop the old XML provider any further. However, if somebody ever wrote the appropriate XML parsing code it could easily be used to populate the InMemoryMetadataManager with the right values, essentially resulting in an XML metadata provider. Just remember about the domain unloading mentioned earlier.

Adding custom metadata providers in ASP.NET 3.5 Extensions Preview

marcind — Tue, 11 Dec 2007 04:30:00 GMT

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:

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

Explicit: using an attribute on the model partial class that points to the type of the buddy class
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