[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Collapse]eXpress Persistent Objects
 [Expand]Product Information
 [Expand]Getting Started
 [Expand]Fundamentals
 [Expand]Feature Center
 [Expand]Concepts
 [Collapse]Design-Time Features
   Built-in Visual Studio Templates
   Data Model Designer
   Data Model Wizard
   OData Service Wizard
 [Expand]Examples
 [Expand]Member Tables
 [Expand]API Reference
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Data Model Designer

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:

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.

Expanded 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.

Expanded 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.

Expanded 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).

Expanded 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 Attrubutes 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.

Expanded 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.

Expanded 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

Is this topic helpful?​​​​​​​