Migrating a v2.x .lgp project to v5

LLBLGen Pro v5 uses the same project file format as v3 and v4: it's in XML, easy to read and is stored in files with a different extension (.llblgenproj) than in v2.x. To convert an LLBLGen Pro v2.x project, stored in a file with the extension .lgp, you have to use a conversion template using the v2.x designer.

The v2.x designer can load the .lgp project and with the v2.x migration template it can generate a v5 llblgenproj project file. The conversion procedure is described below. It's highly recommended to use the latest v2.6 designer build from the LLBLGen Pro Website to convert the project, even if you're using v2.5 or earlier. The latest v2.6 designer build is free for all v2.x licensees.

Conversion process

Before you start the LLBLGen Pro v2.x designer, please unpack the v2xMigrationTemplates_date.zip** file found in the folder V2xMigration in the LLBLGen Pro installation folder (or download the latest build of this migration template package from the customer area) into the v2.x designer installation folder. It will install a new templategroups.config file in the AdditionalTemplates folder. If you get a prompt to overwrite this file, you already have such a file in that folder, you should click 'No' to not overwrite that file. Instead, open the templategroups.config file in the AdditionalTemplates folder and add:

<templateGroup name="LLBLGen Pro v5" 
  description="Template group which contains templates for converting v2 projects to v5 project files."/>

Conversion template Usage

Start the LLBLGen Pro v2.x designer and load the project to convert. Press F7 to bring up the code generation dialog. For 'Template group' you select 'LLBLGen Pro v5'. Choose a .NET version and select as target language C#. Specify the destination root folder you want the .llblgenproj file to be created in.

Click Start generator. The project is now generated as a .llblgenproj file. In the destination folder you have chosen, a file called ConvertedProjectv50Format.llblgenproj has been created. This is your v5 version of the .lgp project. Rename the file to your liking, e.g. after the project name.

Start the v5 designer and load your converted project file. If you get an error, like a type couldn't be loaded, make sure that if the type is typeconverter related, you have placed your type converter in the v5 TypeConverters folder or a folder which is reachable by the v5 designer.

After you've loaded the project, it might be v5 designer finds errors. This is likely caused by more strict rules implemented in v4 designer. Manually fix the errors reported, if the designer reports any. After that, sync the relational model data. The project should now validate and is ready to use. After you've successfully converted the project, first check the new preferences and project properties and adjust them to your liking before proceeding.

Conversion details

The template emits XML, using the .lpt mechanism, however it doesn't sort the elements in the right order. It's not really a problem as loading the generated llblgenproj file and saving it again will save it in the right order. You have to take this into account however when you check-in the initial generated file into source-control and after that you try to update that file with a saved version: it will show a lot of changes which likely aren't changes. This is a one-time thing.

Relationships are always specified as FK-PK. This is a convention to get rid of the duplicate relationships which are present in v2's projects (in v2.x, a m:1 relationship is also present as 1:n in the PK side), now the FK-PK relationship is stored both in the pk and the fk side.

Custom Relationships

In v5 the concept of custom relationships has been changed into model only relationships. It can be the user has created multiple custom relations in v2, where the FK side has a custom relation to both A and B and both A and B are mapped onto the same table. These relations aren't filtered out but could lead to crashes or non compilable code. This edge case has to be corrected manually in the designer.

Relationship conversion

All normal relationships which have their start entity as the FK side are emitted into the output, unless they're marked hidden, or used for hierarchies. If the relationship doesn't have an opposite, the relation is emitted, if the FK side is the start entity, otherwise the relation is ignored, as it's not a concept that's known in v5. Instead, in v2.x, the user should unhide the relation and hide the field mapped onto the relation. Custom relations which are present in just one side are seen as normal relations