Data Model Designer

• Mar 12, 2021
• 16 minutes to read

XPO provides the Data Model Designer for editing visual data models created via the Data Model Wizard. The designer allows you to add persistent classes and properties, modify their settings, setup associations, etc. This topic consists of the following sections:

• Overview
• Ways to Invoke
• Model Properties

• Model Elements

  • XpObject
  • Aggregation Relationship
  • Persistent Alias
  • Association
  • Comment
  • Comment Link
  • Composite Field
  • Field
  • Index
  • Inheritance
  • Many to Many Relationship
  • Collection
• Synchronize the Model with the Database
• Nullable Behavior

Note

The ORM Data Model Designer is version-agnostic. You cannot have multiple designer versions on the same machine. We recommend using the latest designer version.

Overview

The image below illustrates the Data Model Designer and related Visual Studio windows.

• Toolbox. Use it to pick data model elements and place them onto the designer surface.
• ORMDataModel. This window provides the data model’s tree-like structure. You can use it to find and focus model elements. If the window is hidden, click the VIEW | Other Windows | ORMDataModel menu command to display it.
• Properties. Displays the focused element’s properties. To edit global properties like the data connection or designed classes’ namespaces, click the empty space in the designer or focus the root Data Model item in the ORMDataModel window.
• Solution Explorer. Displays designer-generated code stored in the “<MODEL_NAME>Code“ folder. The ConnectionHelper.cs file implements the static ConnectionHelper class that exposes an auto-created connection string and provides methods that simplify Data Access Layer and data store initialization. Other code files contain persistent class implementations. Each persistent class is declared as partial and is split into two files (for example, MyObject.cs, and MyObject.Designer.cs). The designer handles files with the “Designer“ suffix. These files should not be edited manually, as the designer overrides your changes. Place your custom code in a file without the “Designer“ suffix.

Ways to Invoke

• To start with a new data model, use the Data Model Wizard. The designer starts automatically when you close the wizard.
• To design an existing data model, double-click a file with “XPO“ extension in the Solution Explorer.

Model Properties

To specify data model options, right-click the empty designer’s surface or the root Data Model item in the ORMDataModel window and choose Properties.

Property	Description
Collection Properties Type	Specifies the default type of collection properties generated by the designer. When the type is set to Auto, and the GetCollection method is available in the current persistent class, the designer generates the XPCollection<T> collection properties. If the type is Auto and the GetCollection method is not supported (for example, when the base class is PersistentBase), the IList<T> collection properties are generated.
Data Source	Specifies the database connection. Click the ellipsis button to the right of the value to open the corresponding Data Model Wizard page.
Enable nameof	Specifies whether to use ‘nameof’ instead of string literals in properties’ accessors.
Field Name Case	Specifies the case style for the names of private fields that are encapsulated by persistent properties in the generated code.
Field Name Prefix	Specifies the prefix for names of private fields that are encapsulated by persistent properties in the generated code.
Freeze Layout	When enabled, prevents the designer from modifying the existing model layout automatically.
Generate Connection Helper	Specifies whether the ConnectionHelper class is generated.
Generate Default Constructors	Specifies whether the default constructors are generated for persistent classes. When set to false, only the constructor that takes the Session parameter is created for each class. When set to true, the default parameterless constructor is additionally generated.
Generate Stored Procedures	Specifies whether auxiliary helper classes that allow you to call existing stored procedures directly and handle the results are generated.
Generate Views For Table Access	Specifies whether persistent classes and DDL (Data Description Language) code required to map database views are generated.
Namespace	Specifies the namespace for classes the designer generates.
Nullable Behavior	Specifies if the IsNullable property of class fields is considered when generating the property code (see the Nullable Behavior section).

Model Elements

XpObject

Adds a persistent class.

When the XpObject is focused, the following options can be specified in the Properties window.

You can specify the following options in the Properties window when an XpObject has focus.

Property	Description
Base Class	Specifies the current persistent class’s base class. You can choose a built-in base class. To inherit from a custom class, add this class to the designer and define the inheritance relationship instead.
Custom Attributes	Specifies custom attributes applied to the current class in the generated code. Use fully qualified attribute names. To apply several attributes at once, provide a comma-separated list.
Deferred Deletion	Specifies whether deferred object deletion is enabled for the current persistent class by applying the DeferredDeletionAttribute attribute in the generated code.
Map Inheritance	Specifies the type of object-relational inheritance mapping (see MapInheritanceType) for the current persistent class by applying the MapInheritanceAttribute attribute in the generated code.
Member Design Time Visibility	Specifies whether the current class is visible at design time by applying the MemberDesignTimeVisibilityAttribute attribute in the generated code.
Name	Specifies the persistent class name. Note that when you rename the existing XpObject, the class name changes in code, but the name of the CS or VB file that contains the class implementation does not change. Files are intentionally not renamed to avoid possible conflicts with the version control system.
Non Persistent	Specifies whether the class instances will be stored in a persistent data store by applying the NonPersistentAttribute attribute in the generated code.
Nullable Behavior	Specifies if the IsNullable property of class fields is considered when generating the property code (see the Nullable Behavior section).
Optimistic Locking	Specifies that a persistent object state can be locked during a Session, by applying the OptimisticLockingAttribute attribute in the generated code.
Optimistic Locking Behavior	Specifies the locking kind (see OptimisticLockingBehavior), by passing the OptimisticLockingAttribute.LockingKind parameter in the generated code.
Optimistic Locking Read Behavior	Specifies field-level optimistic locking settings (see OptimisticLockingReadBehavior) of a persistent object, by applying the OptimisticLockingReadBehaviorAttribute attribute in the generated code.
Persistent	Specifies the name of the table mapped to the current class, by applying the PersistentAttribute in the generated code. The table name is passed to the attribute’s PersistentAttribute.MapTo parameter.
Track Properties Modifications On Read	Specifies whether modifications made to persistent properties are tracked, by passing the OptimisticLockingReadBehaviorAttribute.TrackPropertiesModifications parameter in the generated code.
XMLDoc Comments	Specifies XML documentation tags added to the class declaration.

Aggrergation

Specifies the aggregate one-to-many relationship by applying the AssociationAttribute and AggregatedAttribute attributes in the generated code. To relate the FirstObject and SecondObject, first add a SecondObject type field to the FirstObject (this field will specify the one side of the relationship). Then, focus the Aggrergation Relationship item in the Toolbox, and draw a line from the SecondObject to the FirstObject. To convert the existing Association to Aggrergation Relationship, right click it and select Association to Aggregation

You can specify the following options in the Properties window when an Aggrergation has focus.

Property	Description
Name	Specifies the association name. The value is passed to the AssociationAttribute in the generated code.
No Foreign Key	Specifies whether the automatic creation of the FOREIGN KEY constraints is enabled. When set to true, the NoForeignKeyAttribute is applied in the generated code.
Source Collection Name	Specifies the collection property name that is a many side of the association.
Target Field Name	Specifies the reference property name that is a one side of the association.

Persistent Alias

Adds a read-only property with the PersistentAliasAttribute applied.

You can specify the following options in the Properties window when a Persistent Alias has focus.

Property	Description
Column Type	Specifies the property type.
Custom Attributes	Specifies custom attributes applied to the current property. Use fully qualified attribute names. To apply several attributes at once, provide a comma-separated list, e.g., “DevExpress.Xpo.Key, System.ComponentModel.Browsable(false)“.
Display Name	Specifies the property’s display name. The value is passed to the DisplayNameAttribute attribute in the generated code.
Expression	Required. Specifies an expression which determines how the property value is calculated. The expression is passed to the PersistentAliasAttribute in the generated code.
Is Nullable	Specifies whether the property type is nullable.
Member Design Time Visibility	Specifies whether the property is visible at design time. The value is passed to the MemberDesignTimeVisibilityAttribute in the generated code.
XMLDoc Comments	Specifies XML documentation tags added to the property declaration.

Association

Specifies the one-to-many relationship by applying the AssociationAttribute attribute in the generated code. To relate the FirstObject and SecondObject, first add a SecondObject type field to FirstObject (this field will specify the one side of the relationship). Then, focus the Association Object item in the Toolbox, and draw a line from the SecondObject to the FirstObject. To convert the existing Aggregation to Association, right click it and select Aggregation to Association

Alternatively, you can create associations of different types using the XpObject‘s title bar context menu.

You can specify the following options in the Properties window when an Association has focus.

Property	Description
Name	Specifies the association name. The value is passed to the AssociationAttribute in the generated code.
No Foreign Key	Specifies whether the automatic creation of the FOREIGN KEY constraints is enabled. When set to true, the NoForeignKeyAttribute is applied in the generated code.
Source Collection Name	Specifies the collection property name that is the many side of the association.
Target Field Name	Specifies the reference property name that is the one side of the association.

Comment

Adds a comment box.

You can specify the following options in the Properties window when a Comment has focus.

Property	Description
Text	Specifies the comment text.

Comment Link

Links a Comment to a specific data model element. To add a link, focus the Comment Link item in the toolbox and draw a line from a comment box to the desired model element.

Composite Field

Adds a struct type field that wraps specified properties.

You can specify the following options in the Properties window when a Composite Field has focus.

Property	Description
Custom Attributes	Specifies custom attributes applied. Use fully qualified attribute names. To apply several attributes at once, provide a comma-separated list, e.g., “DevExpress.Xpo.Key, System.ComponentModel.Browsable(false)”“.
Fields	Specifies the list of properties that are added to the composite field.
Generate Properties	Specifies whether generated structure members are fields or properties.
Key	Indicates that a property or a field is a key by applying the KeyAttribute in the generated code.
Name	Specifies the field name.
XMLDoc Comments	Specifies XML documentation tags added to the property declaration.

Field

Adds a persistent property.

You can specify the following options in the Properties window when a Field has focus.

Property	Description
Column Type	Specifies the property type. If the required type is not available in the combo box, do the following: In the ORMDataModel window, right-click the root Data Model item. Select Add New External Type. A new item will be added to the External Types node. Focus the new External Type item and specify its Name and Namespace in the Properties window. Go back to the persistent property and select the newly added type in the Column Type combo box. A detailed example on how to add an extra type is provided in the How do I declare an image property in the ORM Data Model Designer article.
Custom Attributes	Specifies custom attributes applied to the current property. Use fully qualified attribute names. To apply several attributes at once, provide a comma-separated list, e.g., “DevExpress.Xpo.Key, System.ComponentModel.Browsable(false)”“.
Db Type	Specifies the column type used by the database server for the current property.
Default Value	Specifies the default value of the database column mapped to the target field. The passed value is converted according to the current DBMS specifics and passed to the CREATE TABLE and ALTER TABLE statements when updating the database schema.
DB Default Value	Specifies the SQL expression representing the default value of the database column mapped to the target field. The expression is then passed to the CREATE TABLE and ALTER TABLE statements when updating the database schema.
Delayed	Indicates that the property value will be loaded the first time it is accessed, instead of loading it when the entire persistent object is requested, by applying the DelayedAttribute in the generated code.
Display Name	Specifies the property’s display name. The value is passed to the DisplayNameAttribute attribute in the generated code.
Explict Loading	When greater than zero, objects referenced by the current property are loaded in a single query. It is a recursive process, since the retrieved object might reference other objects. The reference depth of the retrieved object is specified by the Explicit Loading value. The value is passed to the Depth parameter of the ExplicitLoadingAttribute attribute applied in the generated code.
Is Identity	Specifies whether the property type is a key with an auto-generated value, by applying the KeyAttribute with the true parameter.
Is Nullable	Specifies whether the property type is nullable.
Key	Indicates that a property is a key by applying the KeyAttribute in the generated code.
Member Design Time Visibility	Specifies whether the property is visible at design time. The value is passed to the MemberDesignTimeVisibilityAttribute in the generated code.
Name	Specifies the property name.
NonPersistent	Indicates that a property will not be stored in a persistent data store by applying the NonPersistentAttribute in the generated code.
Persistent	Specifies the name of the column mapped to the current property, by applying the PersistentAttribute in the generated. code.
Read Only	Indicates that the property is read-only. When set to true, the property setter is removed.
Fetch Only	Indicates that the property value will not be saved to the database by applying the FetchOnlyAttribute in the generated code.
Size	Specifies the maximum string length supported by the current property, by applying the SizeAttribute in the generated code.
ValueConverter	Specifies the property’s ValueConverter, by applying the ValueConverterAttribute in the generated code.
XMLDoc Comments	Specifies XML documentation tags added to the property declaration.

Note

To reorder fields in a class, drag them with the mouse. Declarations in code will be reordered accordingly.

Index

Creates a single or multi-column index by applying the IndexedAttribute or IndicesAttribute attribute.

You can specify the following options in the Properties window when a Index has focus.

Property	Description
Fields	Specifies properties participating in index creation. The Indexed attribute is applied to the first property in a list. If multiple properties are specified, the IndexedAttribute.AdditionalFields parameter is used to specify names of additional columns that participate in index creation.
Include GCRecord	Specifies whether the GCRecord field is added to the current index.
Include ObjectType	Specifies whether the ObjectType field is added to the current index.
Include OptimisticLockField	Specifies whether the OptimisticLockField field is added to the current index.
Name	Specifies the index name by passing the IndexedAttribute.Name parameter in the generated code.
Unique	Specifies whether the index is unique, by passing the IndexedAttribute.Unique parameter in the generated code.

Inheritance

Specifies the inheritance relationship between two objects. To inherit the SecondObject from the FirstObject, focus the Inheritance item in the Toolbox, and draw a line from the SecondObject to the FirstObject. As a result, the FirstObject class will be the base for the SecondObject in the generated code.

The Data Model Designer can use persistent classes from external assemblies as base classes.

• Right-click the free space on the designer surface. In the invoked context menu, choose Add Assembly.
• Select the assembly and click Open.
• In the Select Types dialog, choose the persistent classes to import from the assembly and click Ok.

These actions will import classes in read-only mode. However, you will be able to use the added classes as ancestors and inherit new persistent classes from them in the designer.

Many-to-Many Relationship

Specifies the many-to-many relationship by applying the AssociationAttribute attribute in the generated code. To relate the FirstObject and SecondObject, focus the Many-to-Many Relationship item in the Toolbox, and draw a line from the FirstObject to the SecondObject.

You can specify the following options in the Properties window when a Many-to-Many Relationship has focus.

Property	Description
Name	Specifies the association name. The value is passed to the AssociationAttribute in the generated code.
Source Collection Name	Specifies the FirstObject class’ property name that is a collection of SecondObjects.
Target Collection Name	Specifies the name of the SecondObject class’ property that is a collection of FirstObjects.
Use Association Name As Intermediate Table Name	Specifies whether the association name is used as a junction table name in a many-to-many relationship, by passing the AssociationAttribute.UseAssociationNameAsIntermediateTableName parameter in the generated code.

Collection

Added automatically when you declare a one-to-many or many-to-many relationship. Represents the many side of the relationship.

You can specify the following options in the Properties window when a Collection has focus.

Property	Description
Custom Attributes	Specifies custom attributes applied to the current collection property. Use fully qualified attribute names. To apply several attributes at once, provide a comma-separated list, e.g., “DevExpress.Xpo.Key, System.ComponentModel.Browsable(false)”“.
Display Name	Specifies the collection’s display name. The value is passed to the DisplayNameAttribute attribute in the generated code.
Explict Loading	When greater than zero, objects referenced by the current property are loaded in a single query. It is a recursive process, since the retrieved object might reference other objects. The reference depth of the retrieved object is specified by the Explicit Loading value. The value is passed to the Depth parameter of the ExplicitLoadingAttribute attribute applied in the generated code.
Member Design Time Visibility	Specifies whether the collection property is visible at design time. The value is passed to the MemberDesignTimeVisibilityAttribute in the generated code.
Name	Specifies the collection property name.
Type	Specifies the collection property type. When the type is set to Auto, the Collection Properties Type option of the Data Model is used to determine the collection type to be used in the generated code.
XMLDoc Comments	Specifies XML documentation tags added to the property declaration.

Synchronize the Model with the Database

XPO can automatically update the database structure when you modify the data model (see Session.AutoCreateOption). In the meantime, you may want to change the database and reflect changes in the Data Model Designer. To do this, right-click the empty space on the designer surface and choose Update Model From Database. In the invoked wizard, select the tables and columns you want to synchronize.

Nullable Behavior

The designer can generate nullable properties when the NullableBehavior property of the model or class is set to ByUnderlyingType and the IsNullable property of a field is set to True. If the runtime property type naturally allows nulls, the property is decorated with NullableAttribute. The following table shows what property type is generated depending on the field type, its IsNullable property, and NullableBehavior.

Field type	IsNullable	AlwaysAllowNulls	ByUnderlyingType
All value types	true	ValueType	Nullable<ValueType>
All value types	false	ValueType	ValueType
String	true	string	string
String	false	string	string with the [Nullable(false)] attribute
All reference types except for Strng	any	ReferenceType	ReferenceType