The LLBLGen Pro designer offers a flexible import system to import project meta data like entity definitions, mappings and relational model data but also derived models from an external source. The import system uses plug-ins to connect to an external source and to obtain the information in that source. This section describes in detail how to import data, which data can be imported and which importer plug-ins are available to you.
The import system lets you build general entity model repositories in LLBLGen Pro projects, from which you can quickly build new models using parts imported from these model repository projects. For example, start with an empty project and import from different LLBLGen Pro projects the parts you likely will re-use, e.g. a group of customer, order, and related entities.
Also add other elements from other projects. Save the project, this is your repository project. Later, when you want to create a new model, you can quickly build your model by importing for example the customer, order and related entities from the repository project. This saves time as you otherwise had to create everything from scratch again.
The import system is disabled when the designer is used from within Visual Studio, because the importer requires a separate AppDomain to run the importer code and creating one from within a Visual Studio extension turned out to be impossible. If you want to import data into an LLBLGen Pro project, please use the stand-alone designer.
To import meta-data into a project, you have to complete the following steps
The Import Wizard dialog
- Load the project you want to import data into into the designer.
- Click Import... in the File menu or select Import... in the context menu when right-clicking the project node in the Project Explorer. This will bring up the Import Data Retrieval Wizard.
- The first step in the wizard is to select the importer to use. Each source type requires its own importer as the importer is in charge of obtaining the data and converting it to a format which can be consumed by the designer.
- After you've selected the importer, fill in the information which points the importer plug-in to the source of the data, e.g. the LLBLGen Pro project file you want to import entity definitions from. After you've defined the source to import from, click Next.
- The importer is asked to obtain the element names and their types from the source and this information is displayed in the UI of this step. Here you select which elements to import from the source, assign group names to them if you'd like, and specify whether mappings and / or super-types automatically should be imported as well. There are two tabs, Entity Model and Derived Models. After you've made your selections by checking the checkboxes in front of the elements you want to import, click Next. After that click Finish.
- The import system will now obtain for the elements you selected to import the actual import data (see below). If you have set the designer preference CreateBackupBeforeImport to true (default), the designer will create a backup of your project first. After the backup has been created successfully, the import system will merge the imported data with the project and will show a log of the actions taken.
Importing data is not an action you can undo in the designer, so it's recommended to leave CreateBackupBeforeImport set to true.
The import system works in similar ways as the driver system does: every import plug-in converts data from the source it understands to a common format the designer understands. This means that what is importable is restricted to what data the designer can consume. The following list shows what can be imported:
- Entity definitions, their fields and their specifics
- Value Type definitions, their fields and their specifics
- Inheritance hierarchies of type TargetPerEntity (TPE) and TargetPerEntityHierarchy (TPEH). This means which entity is subtype of which entity using which inheritance hierarchy.
- Relationships. All references/relationships between the elements to import are imported. Everything else is ignored.
- Group information
- Typed Lists, their fields and their specifics
- Typed Views, their fields and their specifics
- Stored procedure calls, their parameters and their specifics
- Table valued function calls, their parameters and their specifics.
- Derived Models.
- Root Derived Elements in a Derived Model.
- Table definitions and their fields and specifics
- FK Constraints
- UC constraints
- Entity mappings
- Typed View mappings
- Stored Procedure call mappings
- Table Valued Function call mappings
- Type shortcuts
The import system uses a set of rules to make sure you can import the data with as little manual labor as possible. The following rules are applied to the data to import and they can help you make decisions what to do when importing data into a project. An importer plug-in can have its own rules as well. See further down in this section what the rules are for the included importer plug-ins.
If an element is imported with the same name as an existing element,
it's renamed. So if you have an entity
Customeralready in your project and you import another entity
Customer, it's renamed to
- If a typed list is imported and in the imported data not all entities and/or relationships in that typed list are specified as well, the typed list is skipped.
- All relationships between the entities to import are imported.
- If an entity to import is defined as being in an inheritance hierarchy and the sub-types arent imported, the entity is added as a normal entity to the project
- If mappings are imported, so are the mapped meta-data elements.
- Custom properties are not imported for meta-data elements.
- Settings and custom properties arent imported for the model elements.
- Return elements of a table valued function call which is selected to be imported are always imported as well, even if they're not selected to be imported.
- Entities a to be imported derived model element relies on, are always imported together with the derived model element.
Meta-data elements are imported when mappings are imported. The mappings are leading: the target referred by the imported mapping is searched first in the existing meta-data using a name search. If present, that element is used. If it doesnt match due to e.g. missing fields/field types, it will lead to validation errors and you have to fix these manually afterwards. If the target doesnt exist, it is manually created from the imported meta-data if its a table. The newly created table is always considered new.
Only for newly created tables, the FK constraints are imported. The newly created table is created after the importable variant of the table the imported mapping refers to so it looks equally, with the same fields and types.
Mappings to views and stored procedures or stored procedure resultsets are always considered mappings to an existing target, as they can't be re-created from the source. If a typed view is mapped onto a table and the table doesnt exist, the table is created similar to when an entity is mapped onto the table. New elements, like catalogs, schemas and tables, created in the project the data is imported into, are created using the names specified in the import data.
The derived model feature and its derived elements are importable using the import system. The import of derived elements is designed around the root derived element: a derived model the root derived element is in is imported as well, as well as its containing embedded documents.
As derived model elements rely on entity model elements, these are always imported together with the derived model element. This is similar to importing a typed list: the entities in the typed list are always imported. If you have opted to import tables/mapping data, that data is imported as well, indirectly.
If the user imports a root derived element, the derived model the root derived element is in, is also imported, if the destination model name specified by the user isn't a name of an existing derived model in the target project. If the destination name is present as a derived model in the target project, the root derived element is added to that derived model.
When a derived model is imported, its settings are too. This means that all settings of the source derived model element, including additional interfaces/attributes etc. are imported as well.
By design, settings specific for a derived element are not imported.
The following importer plug-ins are included in LLBLGen Pro:
- LLBLGen Pro project importer, which can import data from v3, v4 or v5 project files.
- EDMX importer, which can import data from an Entity Framework project EDMX file.
The SDK documentation contains more details about how importer plug-ins work and how you can create them yourself to create importers for other data, e.g. xml file based data.
The included importers have the following rules / aspects
The LLBLGen Pro project importer can import data from v3 or v4 project files and has the following rules and characteristics:
- If the option ImportSuperTypesAutomatically in the wizard is checked (default), if an entity to import is in an inheritance hierarchy, all super-type entities of that entity are imported, even if some of them arent selected. Subtypes of that entity are not automatically imported, only if theyre selected.
- All value types definitions which are referenced (indirectly) by an entity or value type definition which is selected to import are imported as well
- All type-shortcuts which are defined in the project to import and which are used by elements to import are imported, including enum types. You have to make sure that the .typeimports are found with the new project. Custom type-shortcuts which are based on a type which is defined by a type-converter or user defined type (UDT) are imported, but you have to make sure the target meta-data and type-converters reachable from the project the data is imported in are present when the project is loaded again.
- All entities in a typed list which is selected are imported, even if theyre not selected.
- Foreign key fields which are auto-created and which are based on a relationship which isnt imported because the PK side isnt imported, will be reverted to normal fields.
The EDMX importer can import a normal, valid EDMX file into an existing LLBLGen Pro project.
The following steps show the usage:
- Start the LLBLGen Pro designer.
- Open the LLBLGen project you want to be the target of the importer, or create a new one.
- Right click at the root node of your project and click Import. This is also accesible from the File menu.
- In the importer menu, select EntityFramework EDMX importer.
- Browse the edmx file you are going to import and click Next.
- Select the entities you want to import and click Next.
- The importer is now done. Now validate the project (Project menu -> Validate) to see if there are any errors with the imported objects.