Telerik OpenAccess ORM and the XML Metadata Source

We all know that Telerik OpenAccess ORM has a completely new face with the Q1 2010 release so it is about time to start blogging about some of the features and improvements that the new Visual Designer brought along.  Today I will talk about one of the most notable changes in the new version of OpenAccess ORM and that is the “XML – only” mapping. You all know that so far with the previous versions of the product the mapping information was defined by a mix of XML configuration files and CLR attributes. After a lot of customer feedback and thorough thought we decided to make the XML and the attributes as two separate and self-contained sources of metadata information about your model. You can choose one based on your personal preferences.

I will start with a brief overview over the new XML mapping definition. Unlike previous versions, where all the XML mapping information was spread between the app.config and the reversemapping.config files, it is now embedded in the [YourModelName].rlinq file that is being generated by the Visual Designer.
So if you open the .rilnq file with an XML editor, there is a lot of XML in it, but the mapping information for your model that is eventually used by the OpenAccess runtime is held inside the <orm> node of that file.  Here is an example of how a class node in the new looks like:

We did our best to make the mapping schema as intuitive as it can be – that way it should be human readable/editable. There is still a possibility for one to manually alter the settings but I strongly recommend you to leave this job to the Visual Designer.

How can you use the XML definition as a metadata source?

When you chose to use XML as metadata source(this is the default option in the Model Settings Dialog), OpenAccess executes an MSBuild task that extracts the mapping information and embeds it as a resource to your model assembly.

Here is an example of how the model metadata can be obtained using XmlMetadataSource:

If you execute this code in another assembly – for example in a web application that references your model assembly, you should also specify the assembly where the .rlinq file is placed.

The XmlMetadataSource class is the class that takes care of reading and delivering the metadata information about a model to the OpenAccess runtime. It allows creation of a model using different initialization methods that give you flexibility with the source of the xml metadata. For example it can obtain the model from a resource embedded in an assembly as the example show but it can also get it from a FileStream, direct XML passed in the form of string or just an XML file somewhere on your hard drive. So you are not obliged to even have an .rlinq file at all!
From here on you can use this API to work with the new OpenAccessContext class that is generated with the persistent classes(you can make one on your own as well by just deriving a class from the OpenAccessContext base class)as well as the known IObjectScope API(especially useful for older projects that are based on the IObjectScope functionality).

Here is an example:

 

So, to recap, the XML metadata source is just one of the approaches you could use to represent OpenAccess mapping metadata and it is really easy to use with the new Visual Designer. It could be the best choice for most of the scenarios where you do not need to alter any mapping information. For manually producing/manipulation of the mapping, the Attributes Metadata Source might just be your choice. It will be a topic that we will discuss in few days, so stay tuned.