Using Fluent Mapping API

This article is relevant to entity models that utilize the deprecated Visual Studio integration of Telerik Data Access. The current documentation of the Data Access framework is available here.

The Visual Designer allows point-and-click modification of your data (domain) classes. However, many developers view their code as their model. Ideally these developers just want to write some class and without even touching a designer or a piece of XML to be able to use those classes with Telerik Data Access. Basically they want to write "Code Only". Fortunately, Telerik Data Access provides a Fluent Mapping API, which is perfect for these scenarios.

Fluent Mapping API is the second approach you can choose to migrate your NHibernate data model. Ideally, the only thing you have to do is to translate the NHibernate XML configurations to C#/VB code.

Pros and Cons

Undoubtedly, the biggest advantage of this approach is that you will be able to re-use your currently existing data classes. On the other hand, integrating Fluent Mapping API in your project will require some additional configurations that have to be done manually.

Integrating Fluent Mapping API

Telerik Data Access provides you the Telerik Data Access Fluent Library template in Visual Studio. It will add a new project to the solution, the project will contain an OpenAccessContext implementation, a FluentMappingSource class, and a sample model object. The FluentMappingSource class provides an example mapping to help developers come up to speed quickly when using the Fluent Mapping API. This template will automatically integrate Fluent Mapping API in your application. The disadvantage of using the template is that you will have to move your classes into this project.

If you want to migrate your NHibernate project with minimum structural changes, you will have to integrate the Fluent Mapping API manually. To do this, you will need to perform the following steps (for more information see the links at the end of the topic):

1. Add references to Telerik.OpenAccess.dll and Telerik.OpenAccess.35.Extensions.dll.
2. Integrate with the Telerik Data Access Enhancer in the project that contains the data classes.
3. Create a new class that derives from FluentMetadataSource. This class will hold the entire configuration for your classes.
4. Create a Custom Context. When you use Fluent Mapping API, your classes have no knowledge at all about the Telerik Data Access. This is a good thing, as it is the desired effect. However, you need to let Telerik Data Access be aware of the classes. The Telerik Data Access Create Model Wizard does not only create the entity classes, but also creates a class that inherits from OpenAccessContext. By default, in your Fluent Mapping project you don't have a custom OpenAccessContext class. That's why one of the most important steps is to create your own class that inherits from OpenAccessContext and let it know about your custom classes. Once you have done this, the OpenAccessContext will do its job of querying and managing the custom classes.

References

• Code-Only Mapping - this chapter is entirely dedicated to the Telerik Data Access Fluent Mapping API.
• Consuming a Model - Configuration - demonstrates how to create a new Telerik Data Access Domain Model, capsulate it in a separate project (assembly), and then reuse the model in different applications. Note that in this topic the Database First Scenario is used. However the same rules apply to projects using Fluent Mapping API.
• Consuming a Model - CRUD - shows how to utilize your Telerik Data Access Domain Model for your Create, Retrieve, Update and Delete operations. Note that in this topic the Database First Scenario is used. However the same rules apply to projects using Fluent Mapping API.