Designer - Refreshing the catalog schemas
If changes were made to the catalog schemas after you've created your project (e.g. you've added a table or a relation, renamed
a field, or removed a table or view) you will need to refresh the catalog schemas in a project to start working with the new schema set.
This is because LLBLGen Pro only makes a snapshot of your database schemas while creating the project, enabling you to work on your project without being
connected to the database.
Use the refresh functionality with care:
refreshing the catalog can have severe impact on your project. If elements you use in your project have targets (like a table or view) which have been deleted
from the catalog / schema, and these elements are used in other elements as well, for example an entity is also part of a typed list, this
typed list is also modified, because the target of an entity has been removed from the catalog.
By default, LLBLGen Pro will backup your current project before starting a catalog refresh action, so you can always return to the version prior to the
refresh action. If you don't want to have a backup created, you can switch this off by setting CreateBackupBeforeRefresh
to false in the
The filename used for this is the regular filename, appended with the suffix containing the exact date and time in the following format: ddmmyyyyhhMMss. 'm' is month,
'M' is minute.
The folder into which the backup is placed is defined in the Preferences
If you have multiple catalogs in your project (SqlServer only), you can decide to refresh a single catalog (right-click on the catalog to refresh and select
'Refresh this catalog') or refresh all catalogs. The same options are available to you for an unattended refresh.
Refreshing the catalog schemas
Single catalog refresh, attended
- To perform a single catalog refresh, you right-click on the catalog in the project explorer and you select
'Refresh this catalog'.
If VerboseRefresh in the user preferences is set to true, you'll first see a
warning screen, stating the possible problems that may arise when proceeded. If a project has unsaved changes,
it is saved using the normal save procedure.
After that, if CreateBackupBeforeRefresh is set to true in the user preferences,
LLBLGen Pro will create a backup of the current project and the filename of that backup will be reported to you.
The catalog refresh dialog pops up and allows you to specify login/connection details. If you want to refresh the
catalog with a catalog with another name, first rename the catalog in the catalog explorer (SqlServer/DB2).
You can again specify which elements to read from the schemas. If you have a project element based on a table, view or stored procedure, these elements
will be refreshed always, and you can't uncheck them. If you want new catalogs / schemas to be imported into your project, you can check these as well.
Click 'Retrieve schema(s)'.
The schema's are retrieved and the project is migrated. After the migration has been completed, a full report will be presented to you,
stating any changes made to your project, if you've set ShowReportAfterRefresh in the user preferences to true.
If desired, you can save this report as .rtf or as xml for later reference.
When the refresh succeeded, the project is refreshed in the Project Explorer and you can start using the new catalog(s).
All changed objects in the project will now have their front/back color changed in the project explorer. If you've specified to automatically add
new elements to the project, by setting AddNewElementsAfterRefresh
to true in the
, the new elements are added for you automatically. If you've specified to keep the
names in the project in sync with the names in the catalog schemas, by setting SyncMappedElementNamesAfterRefresh
to true, the names are synchronized
for you automatically.
If you are not satisfied with the changed project, you can abandon the project by closing it, but not saving it, and load the backup LLBLGen Pro made,
you've decided to create a backup. An example of the catalog refresh dialog is shown below.
Catalog refresh dialog
Multi catalog refresh, attended
To perform a multi catalog refresh, you right-click on the Catalogs node in the project explorer and you select
'Refresh All Catalogs'. You can also select Project
-> Refresh All Catalogs...
from the menu.
Otherwise the steps are the same as for Single catalog refresh, attended.
Single catalog refresh, unattended
You can also perform an unattended refresh on a single catalog. Do start an unattended refresh, right click on the catalog to refresh in the project
explorer and select 'Unattended refresh' from the context menu. An unattended refresh will automatically refresh the catalog for you using the last
used connect credentials. It might be the password you used isn't yet stored in the project and the refresh fails the first time. If that's the case,
perform an attended refresh first. If you've specified to manually select stored procedures, the stored procedure selector will be shown, regardless
if you're running an unattended refresh. If you don't want this, switch off manual stored procedure selection in the user preferences. For further
information about actions taken during a refresh, please see Single catalog refresh, attended
Multi catalog refresh, unattended
To start a multi catalog unattended refresh, you right-click on the Catalogs node in the project explorer and you select
'Unattended Refresh All Catalogs'. You can also select Project
-> Unattended Refresh All Catalogs
from the menu.
For the rest, the steps are the same as for Single catalog refresh, unattended.
Changing catalog name/schema name for refresh
It can happen that during the project's lifecycle, the name of the catalog or schema changes, or the catalog is moved to another server and is called differently
on that server. Using the mechanisms to refresh the existing catalog(s)/schema(s) will fail, as the catalog name(s) / schema name(s) won't be found. To be able to
refresh your catalog or schema with the meta-data of a different catalog / schema, go to the catalog explorer
, right click the catalog- or schema name and
or press F2. Specify the name of catalog / schema you want to use for the next refresh cycle and click OK. Now refresh your catalog.
When a catalog is refreshed, it can be that a table or view was renamed since the last time the catalog was refreshed or the project was created. During the migration of the entities, when LLBLGen Pro
detects that a target table or view is not available under the old name, it will try to find back the table or view
which is now known under a new name. However, it can be it makes a mistake, because for example two tables
are renamed and they look alike, and it's then unclear which one to choose. A mistake in the mapping of an entity can lead to having an entity mapped onto the wrong
table for example. (to get an overview of which entities are mapped on which tables/views, please see
Designer - Adding and editing entities
). Normally, these mistakes are rare, but it can be you
run into them.
You can order LLBLGen Pro to show a list of 'orphaned' entities, which are entities which targets aren't found in the new catalog information under their old names.
To do this, set the preference setting ManuallySelectRenamedTargetsAfterRefresh
to true. If this preference
setting is set to true, and LLBLGen Pro detects one or more orphaned entities, it will show a dialog like the following screenshot. This dialog then lets you correct
the mappings per entity.
Project element target selector
Per selected element you can select a target from the drop down box and by clicking Set
, you set the entity to a new target. If you don't need an entity anymore,
because its target has been deleted from the database schema, simply leave its new target empty and the entity will be removed after the refresh has been completed.
By clicking 'OK', the refresh will proceed.
Not shown during an unattended refresh, in which case the catalog refresher logic will use the default for ManuallySelectRenamedTargetsAfterRefresh: false.