[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]Report and Dashboard Server
[Collapse]eXpressApp Framework
 [Expand]Getting Started
 [Expand]Design-Time Features
 [Collapse]Task-Based Help
  [Collapse]Business Model Design
   [Expand]Common Tasks
   [Expand]Entity Framework (EF)
   [Collapse]eXpress Persistent Objects (XPO)
     How to: Calculate a Property Value Based on Values from a Detail Collection
     How to: Initialize Business Objects with Default Property Values in XPO
     How to: Generate XPO Business Classes for Existing Data Tables
     How to: Create a Business Model in the XPO Data Model Designer
     How to: Map a Persistent Class to a Database View Which Has No Key Field
     How to: Handle Renamings and Deletions of Business Classes and their Properties
     How to: Change the Format Used for the FullAddress and FullName Properties
     How to: Use XPO Upcasting in XAF
     How to: Implement a Custom Base Persistent Class
     How to: Implement File Data Properties
   [Expand]Non-Persistent Objects
  [Expand]Application Model
  [Expand]List Editors
  [Expand]Property Editors
  [Expand]Scheduler and Notifications
  [Expand]Maps Module
  [Expand]Miscellaneous UI Customizations
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

How to: Implement a Custom Base Persistent Class

XAF ships with the Business Class Library that contains a number of persistent classes ready for use in your applications. All these classes derive from the BaseObject base persistent class declared in the same library. This is a recommended-to-use feature-rich persistent class. In certain scenarios though, it may not meet your requirements. In this case, you can either use one of the base persistent classes offered by XPO to implement a custom one. This topic describes the steps you need to perform to implement a custom base persistent class to ensure that it functions as expected throughout the entire eXpressApp Framework. If you do not need to implement a custom class and want to use one of the base classes offered by XPO, refer to the Base Persistent Classes help topic instead.


A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1255.

While you can implement a custom base persistent class from scratch, it is better to reuse an exiting functionality by deriving it from one of the base classes offered by XPO. In this example we will derive the custom base class from XPCustomObject. This XPCustomObject class supports deferred deletion and optimistic concurrency control, but does not offer an auto-generated primary key property.

Expanded Implement the Auto-Generated Primary Key Property

If the base class you derive from does not have an auto-generated key property, you need to implement it manually. We do not recommend implementing composite or compound keys for new databases. While it is possible to design persistent classes for legacy databases with composite keys in certain scenarios, it is always better to modify the database schema to avoid this as using composite keys imposes some limitations on the default functionality. Refer to the How to create a persistent object for a database table with a compound key KB article to learn more. The following code snippet illustrates a GUID property marked with the Key attribute specifying that XPO should auto-generate its values. Note that XPO supports automatic generation of key property values via the Key attribute for the Int32 and GUID types only.

It does not make much sense to persist this class as it contains a single property (for the auto-generated primary key) and thus the class is marked as non-persistent. As a result, primary key columns will be created in database tables corresponding to a descendant of this class. This eliminates redundant JOIN statements from SQL queries generated by XPO, thus improving database performance. Additionally, you should override the OnSaving method in the demonstrated way to support the correct saving of new objects derived from your class and created via a nested unit of work in specific situations.

Expanded Implement the ToString Method

To complete custom base persistent class implementation, override its ToString method to manage default properties. Default properties are displayed in Lookup Property Editors and take part in form caption generation. Additionally they are automatically used by the FullTextSearch Action and are displayed first in List Views. When implementing a custom base persistent class, override the ToString method to check whether or not the DefaultProperty attribute is applied to the class and return its value.

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