Field Ordering

Entity definitions, value type definitions and typed views have fields which are by definition unordered, there's no ordering defined for the fields inside the contained element. In user interfaces the fields are by default displayed in alphabetical order. For code generation output, this is by default also the norm: fields are sorted alphabetically.

It can be the alphabetical ordering isn't ideal for working with the entity model, e.g. you have the fields FirstName, MiddleName and LastName in an entity Person and you want to see them enlisted in that order. Sorting the fields alphabetical will show the fields in the order FirstName, LastName, MiddleName. Also when you use a compound PK, e.g. (OrderId, ItemNo), you don't want the fields in the Primary Key to be (ItemNo, OrderId).

LLBLGen Pro offers a way to specify a custom field ordering per element: every field will be given a field index and the fields are then sorted on: FieldIndex ascending, Name ascending. By default, the fieldindex is equal for all fields, so the fields are sorted by name. Specifying a field index makes the fields become ordered by the field index.

Field indexes and user interfaces

Field indexes start at 0 and are displayed in element editors like the Entity Editor, on the fields tab, in the Order column. When you open an editor, the fields are sorted by the columns Order and then Name. When fields don't have a field index set, the Order column is empty.

Fields in the project explorer are sorted in similar fashion: on Field index and then on Name, with the difference that the identifying fields are always at the top. This is also true for entities displayed in a ModelView.

Manually editing the field order

To manually edit the field order of an element (Entity definition, value type definition or typed view), you have a couple of options to open the Field Order Selector which is the dialog in which field ordering is specified:

• Click the Set Field Order button on the Fields tab of an Entity editor, ValueType editor or TypedView editor
• Right-click an entity, typedview or valuetype node or the Fields node below an entity, valuetype or typedview node in the Project Explorer and select Set Field Order (or hit Ctrl-Shift-F)
• Right-click an entity in a ModelView and select Set Field Order

The Field Order Selector allows quick field re-ordering using keyboard or mouse. Hold the control key and press the Up or Down arrow key to move the selected field(s) up or down. Hold Shift or Control (+ mouse click) to multi select fields.

Automatically set the field order

With an existing project, it can be tedious to set the field order on every entity by hand. LLBLGen Pro offers the ability to set the field order based on the ordinal order of the mapped target fields in the table / view. How LLBLGen Pro does this depends on how you want to work.

Database First

For working database-first, this is done during a syncing the relational model data if the project setting ResetFieldOrderBasedOnTargetOrderAtRelationalModelDataSync is set to true (default is false). When reverse engineering, new entities created through reverse engineering will only get their fields ordered after the ordinal ordering of the fields of the tables/views they're mapped on if the project setting UseCustomFieldOrderingOnNewElements is set to true (false by default).

Model First

For working model-first, this is done when a new entity is defined and if the project setting UseCustomFieldOrderingOnNewElements is set to true (default is false). Fields added to a new entity will automatically get a field order (the last known field index + 1) if that setting is set to true. This works regardless of how you add the field: in the entity editor or through QuickModel or for example through adding a relationship and it will create a foreign key field in the entity.

Syncing table field ordinals with model field indexes

By default, a table field's field position isn't changed if the entity field mapped onto it receives a different field index. One of the reasons is that in general databases don't offer efficient ways to change field ordinals of tables. It can be however that in a development scenario you simply want to start over from scratch with an empty schema. In that scenario the table field ordinals should be synced with the entity field indexes as they're not updated in the schema: it's started from scratch using a Create DDL SQL script.

For this scenario, the designer offers a setting 'Sync custom field ordering with table field index', which can be found in the Project Settings in the 'Model First Development' section. By default this setting is set to false. If set to true, a model first sync action will sync custom field orderings set at the entity level with the fields in the table an entity is mapped on: the field ordinals are reset to the field index of the mapped entity field. If an entity has no custom field ordering set or the entity is part of an inheritance hierarchy, no indexes are synced.

Syncing field indexes won’t result in a change in the table fields itself and therefore won’t be included in Update DDL SQL scripts as the database system can't re-order fields in a table in a convenient way. The new field ordinals are included in a Create DDL SQL script which is simply a reflection of the current state of the relational model data.

If there are multiple entities mapped onto the same table and field indexes are synced with table field ordinals, the last one wins: there's otherwise no solution for this.

Database-first important aspects

Field ordering set automatically through a sync task has a downside when multiple database types are used in the project, e.g. SQL Server and Oracle: if the order differs for a target table / view between the SQL Server version and the Oracle version, the one which is refreshed will be used to set the field ordering if the project setting ResetFieldOrderBasedOnTargetOrderAtRelationalModelDataSync is set to true. It's therefore recommended to leave this setting to its default value false when using multiple database types in a single project.

When a new entity / typed view field is found during a relational model data synchronization, it gets its field index set to the ordinal of the target field if UseCustomFieldOrderingOnNewElements is set to true. In that case, field indexes are automatically updated to remove duplicates and gaps. If the UseCustomFieldOrderingOnNewElements setting is false, the new field gets no field index and will appear at the top of each entity field list due to sorting, or if no ordering is used, at the spot where it fits based on the field name.

Field ordering and auto-created tables (Forward mapping)

When new table fields are created when you use the Syncing the relational model data feature of LLBLGen Pro, when the sync source of your database is set to 'Model', the order in which fields are created is determined by sorting all fields in the order: FieldIndex ascending, Name ascending. This means that if you want your target tables to have the fields in a given order (e.g. pk fields at ordinal 0), you have to make sure the field ordering in the entities is in the order you want the table fields to have.

Code generation and field ordering

Field ordering is used in the LLBLGen Pro runtime framework, where primary key fields are ordered in method signatures / constructors as well as unique constraint fields. Entity fields are also ordered in the enum types for each entity. When an entity has a field ordering specified, the fields are sorted in that field order, otherwise they're sorted on Name.

The Entity Framework v1 code contains static factory methods in each entity class to create a new entity instance and set the primary key fields with the values specified for the primary key fields in the method call. The method's primary key fields are sorted on FieldIndex ascending and then on Name ascending.

LLBLGen Pro v2.x conversion to v5

When using the conversion template to convert from v2.x to v5, field ordering is preserved from v2 to v5 to make migrating the code easier.