As you might or might not know for some time now we have been working on a tool that would make migrating from Linq2Sql to Telerik OpenAccess a breeze. Yesterday (the 13th of October) we released an internal build including a beta version of the new Telerik OpenAccess Linq to SQL converter.
In a few simple steps I would like to explain both how to use the tool and the capabilities and important considerations you should know about. First of all for the purpose of demonstrating the converter, we will use this simple LINQ to SQL model :
The model contains the following items from the Northwind database:
- Two tables – dbo.Employee and dbo.Category
- One view - dbo.Invoice
- Three stored procedures – dbo.AddCategory, dbo.CustOrderHist and dbo.CustOrderDetail. The AddCategory function is used as an insert procedure for the Category entity, it was created manually, as it is not a part of the Northwind database.
Before we start converting the L2SModel to Telerik OpenAcces Domain Model, we should get familiar with the following important notes:
- Only buildable projects will be converted – before starting the wizard, a build process of the target project will be performed. If the project build fails, the wizard won’t start and you will be prompted to fix the compilation errors first.
- If the project is under source control, it will be checked out automatically during the conversion. Be sure that the source control plug-in is active and no files are exclusively checked out by another user.
- Invalid dbml files won’t be converted. If your dbml file is invalid and contains invalid data it will not be processed by the wizard.
- Before starting the conversion, a backup of the project’s original state will be created.
- NOTE: Once the project is converted it may be no longer buildable. The reason is that the original dbml file will not be deleted (removed from the project) after the conversion. There are situations where two classes with the same name and namespace may occur.
In order the start the L2SConversion wizard, select the target dbml file in Solution Explorer, right-click and select the Convert from L2S Model to Domain Model.
The start page of the wizard will appear:
Read the notes and press Next to proceed.
The second page is the place where you need to specify the settings for the conversion.
- Project Name – displays the name of the target project.
- LINQ to SQL Model – drop down containing all available dbml files in the current project. Note that it is allowed to have more than one dbml files in the project and they will be listed in the “LINQ to SQL Model” drop down. If you start the wizard by using the context menu command, the target dbml file will be the default selected item in the combo box control. If you start wizard by using the Telerik menu command, then the first item in the drop down will be selected by default.
- Domain Model Namespace – here you need to specify the namespace for the newly generated entities. The default value of this setting is the default namespace for the project. For example, the default namespace for the current project is “DemoL2SConverter”, that’s why the default value for the domain model namespace will be “DemoL2SConverter” too. If you use the default value for the Domain Model Namespace, your project may be no longer buildable after the conversion. The reason is that the L2S entities and the OpenAccess Domain Model entities will be generated in the same namespace. It is recommended to change that setting, or to delete the Dbml file manually after the conversion. For that demo the Domain Model Namespace is changed to “DemoL2SConverter_New”.
- RLINQ File Name – name for the generated RLINQ file.
- Location For RLINQ File – a directory path where the RLINQ file will be saved. The default value for that setting is the directory where the target dbml file is located. You can change the output directory by pressing the Browse button. This will open a new dialog box with the structure of your project.
- Location for Backup – location for the backup of your project. At the current version of the wizard you cannot change the backup location. The backup will be created in a folder named ProjectName_Backup, located in the directory where your project (.csproj) file resides.
- GridView with all entities – by default in LINQ to SQL there is no difference between tables and views (tables and views are treated in the same way). That means it is not possible for the conversion wizard to recognize which entity is a view and which entity is a table. That’s why you need to select explicitly which entities in your model are views. By default all entities without a specified primary key are treated as views.
When all settings are specified, click Next to proceed to the last page of the wizard.
Again several important remarks are pointed out here. Be sure to read them and click Finish to begin the conversion.
Here are some clarifications about the conversion process: once you click the Finish button, the LINQ to SQL model is converted to a Telerik OpenAccess ORM Meta Model.
If the conversion has completed successfully the wizard creates a backup of the original state of your project.
Next, the converted domain model is saved as a RLINQ file to the specified directory, it is then included in your project. The wizard will update the project references and add references to the necessary assemblies.
Last but not least, the required connection string will be added to the project configuration file. As soon as these actions are executed, a new dialog will appear prompting you that the conversion has completed successfully (or has failed).
You have the option to review the conversion log when the wizard is closed. The last step is to open the generated RLINQ file and to press the Ctrl+S (File -> Save) command to generate the entities.
During the conversion each important action is written in a log file. Once the conversion has completed you have the option to open the log file. Of course, you can do that on a later stage. The log file is saved in the root directory of your project with name “L2SConversionLog.xml”. Be sure that you open the report file with Internet Explorer.
In the basic LINQ to SQL model used in this example, the AddCategory stored procedure is used as an insert procedure for the Category table. Due to the specific naming conventions used in Telerik OpenAccess Domain Model, the AddCategory function cannot be used as an insert procedure in the converted domain model. For that reason the L2SConverter will create an additional stored procedure named oa_CategoryInsert_sp and will add it in the domain model.
Note that the original AddCategory stored procedure will be converted, too. However, in the converted domain model, sp_CategoryInsert_oa will be used as an insert procedure for the Category object. At this point the sp_CategoryInsert_oa exists in the domain model, however, it does not exist in the database. The last step you need to perform in order to use the converted domain model at run time, is to create the corresponding procedure at the server. You can do that manually, or you can use the Update Database from Model wizard.
The beta version of the Telerik OpenAccess LINQ to SQL Converter does not support the following scenarios:
- Inheritance hierarchies in the original L2S Model are not converted.
Specific cases:
- Converting many-to-many relationships – in LINQ to SQL the many-to-many relationships are represented with three tables – or in other words three entities are created. While in Telerik OpenAccess Domain Model, the join table is not represented in the Visual Designer and an entity for that table is not created. In order to keep compatibility between the models, the L2S converter will convert the relationship as it is. That means, three tables will be added in the converted domain model.
In conclusion, I would like to mention that while it is in a working state this is a beta version of the converter. We are looking forward to any feedback or suggestions you might have on the tool. Also stay tuned for the tomorrow's blog post – Fluent mapping improvements.