Resources
Data Access has been discontinued. Please refer to this page for more information.

Fluent Mapping

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 Fluent Mapping Code Generation functionality allows you to mix the Code Only with Database First and Model First approaches. It allows you to generate most of the necessary code automatically as it is done with the Visual Designer domain models. At the same time, since the generated code contains Fluent Mapping API, you can benefit from the capabilities this API offers you for modifying and extending the domain model.

Generally, there are three ways to enable the fluent code generation:

  • Using the Telerik Data Access Fluent Library project template. Read more
  • Using the Telerik Data Access Fluent Model item template. Read more
  • Using the Model Settings dialog in an existing domain model. Read more

Using the Telerik Data Access Fluent Library Project Template

The Telerik Data Access Fluent Library project template will add a new project to the solution and it will run the Create New Model Wizard. This template works in the same way as the Telerik Data Access Class Library project template. However, it will create a new model (from an existing database or an empty one) by using the fluent mapping code generation. Below is a sample output of the Telerik Data Access Fluent Library project template. The generated project will contain an OpenAccessContext implementation (this is the FluentModel class), a FluentMappingSource implementation (this is the FluentModelMetadataSource class), and model classes that correspond to the underlying database tables. For more information about the Fluent Mapping API, please refer to Code-Only Mapping.

Using the Telerik Data Access Fluent Model Item Template

Basically, the Telerik Data Access Fluent Model item template will add a new fluent model to an existing project. This template works in the same way as the Telerik Data Access Domain Model item template. It will run the Create New Model Wizard and it will create a new model from an existing database or an empty one. However the used code generation will be Fluent Mapping. The output is: an OpenAccessContext implementation (this is the FluentModel class), a FluentMappingSource implementation (this is the FluentModelMetadataSource class), and model classes that correspond to the underlying database tables.

Using the Model Settings Dialog in an Existing Domain Model

Once your model is generated, you are still able to change the mapping type. In order to do so, you need to go to the Code Generation Settings tab page in the Model Settings Dialog.

The "Fluent" type of code generation is intended to be used as a onetime code generation only. Unlike the "Xml" and "Attribute" types, where it is assumed you will be working with the Visual Designer, making updates and applying them to the model or the database through our wizards, the "Fluent" is supposed to just help you with the initial efforts in defining your Code Only data access layer.

In general, the Fluent Mapping API is provided as an alternative of the Visual Designer, so you would generally choose it if you prefer defining the mapping in a declarative manner through code. However, sometimes mapping a very large database can require a very long coding effort. The Fluent Code generation will do the hard and boring part of the mapping code and leave only the customization to you.

When you have fluent code generation and then try to use the Visual Designer (e.g. to perform updates from the database), you might get strange results as the fluent mapping is different and much more complex than the other two types of generated code.

Generating fluent mapping from RLINQ file is not recommended. You could lose any customizations made to the generated code if you save the RLINQ file. Consider the "one-time fluent mapping generation" approach by using either the Telerik Data Access Fluent Library project template or the Telerik Data Access Fluent Model item template.

When you use fluent code generation from the Model Settings Dialog, what we would recommend is to extract the auto-generated fluent code files and delete the .Rlinq file so that no code is generated automatically afterwards.
Let’s take a look at the following RLINQ file. By using the Model Settings Dialog, the Mapping Type is changed to Fluent.

Considering the previous recommendation you need to the extract the following files (see the selected files below) and after that delete the Rlinq file.

The generated persistent classes and fluent metadata source can be extracted automatically by using a code generation option in the Visual Designer. However, the generated OpenAccessContext (the EntitiesModel.cs file) should be extracted manually.

To extract the generated domain classes and FluentMetadataSource:

  1. Double-click the Rlinq file to open the Visual Designer.
  2. Open the Model Settings Dialog and navigate to the Code Generation tab page.

  3. Use the Project Folder option to specify a destination folder in the solution where all classes will be generated in.

  4. Click OK to close the dialog.

  5. Save your Rlinq file to regenerate (extract a copy of) the domain classes.

The second step is to extract the OpenAccessContext, i.e. the EntitiesModel.cs file.

To extract the OpenAccessContext:

  1. Open Windows Explorer and navigate to the folder containing your OpenAccessModel project.
  2. Copy the file containing the OpenAccessContext (e.g. EntitiesModel.cs).
  3. Paste it in the folder with the extracted domain classes (e.g. in the FluentModel folder).

  4. Go back in Visual Studio and include the extracted OpenAccessContext in the project structure.

  5. The only step left is to delete the Rlinq file.

There are several limitations of changing the code generation from XML/Attributes to Fluent. Most of them are brought by the differences between the XML mapping definition and the Fluent API:

  1. Constraint names are always different.

    1. In the Fluent Mapping API you can not specify a name for the constraints. Fluent API is creating constraints with default names. If the constraints are already defined in the XML, their names might be different.
    2. This issue could lead to Add/Drop Constraint statements in the Migration Script that would be generated.

  2. Foreign key associations that have multiple foreign keys can't be defined without a constraint between them.

    1. Such associations can only be defined with the HasConstraint fluent method, which always creates a constraint between the tables.
    2. Associations without a constraint can be defined with the ToColumn fluent method. The ToColumn method specifies the column name that the current navigation property is mapped to. Or in other words, the ToColumn method specifies the foreign key column.

  3. Join table columns can't be configured via the Fluent Mapping API. Their Length, Scale, SqlType and IsNullable properties can't be explicitly set by the user. Instead, they are always calculated by the runtime.

  4. You cannot specify Stored Procedures for Create, Update and Delete operations with the Fluent Mapping API.
  5. You cannot configure Stored Procedures with the Fluent Mapping API at all. However the code for them is generated in the OpenAccessContext. So, normal stored procedures can be used with the Fluent Code Generation as well.

Next Steps

For more information about the Fluent Mapping API, check out the Code-Only Mapping section.