XAF: XPO Business Object Models

Base Classes

Class	Key Type	OID Field	Deferred Delete	Optimistic Lock	Use Case
`XPObject`	`int` (auto)	`OID` (int)	Yes (GCRecord)	Yes (auto)	Simple integer PK
`XPCustomObject`	Custom (`[Key]`)	User-defined	Yes (GCRecord)	Yes (auto)	Custom PK type (Guid, string, composite)
`XPBaseObject`	Custom (`[Key]`)	User-defined	No (immediate)	Yes (auto)	Physical deletion required
`XPLiteObject`	Custom (`[Key]`)	User-defined	No	No	Legacy/views/joins, no concurrency
`BaseObject` (BCL)	`Guid` (`Oid`)	`Oid` (Guid)	Yes	Yes	Recommended for new XAF projects

Inheritance chain: XPObject → XPCustomObject → XPBaseObject → PersistentBase

Deferred deletion: XPO sets GCRecord to a non-null value instead of deleting the row.

XAF recommendation: Use BaseObject (from DevExpress.Persistent.BaseImpl) for new XPO entities.

// Most common XAF XPO pattern
using DevExpress.Persistent.BaseImpl;
using DevExpress.Xpo;

public class Contact : BaseObject {
    public Contact(Session session) : base(session) { }

    private string firstName;
    public string FirstName {
        get => firstName;
        set => SetPropertyValue(nameof(FirstName), ref firstName, value);
    }
}

// XPObject (int key)
public class Product : XPObject {
    public Product(Session session) : base(session) { }
    private string name;
    public string Name {
        get => name;
        set => SetPropertyValue(nameof(Name), ref name, value);
    }
}

// XPCustomObject - custom key type
public class Setting : XPCustomObject {
    public Setting(Session session) : base(session) { }
    [Key]
    public string Key {
        get => key;
        set => SetPropertyValue(nameof(Key), ref key, value);
    }
    private string key;
}

Key Attributes

Attribute	Purpose	Example
`[Persistent("ColName")]`	Map to specific DB column/table name	`[Persistent("first_name")]`
`[NonPersistent]`	Exclude from DB (calculated/transient)	`[NonPersistent]`
`[Size(n)]`	String column length (default 100)	`[Size(255)]`
`[Size(SizeAttribute.Unlimited)]`	nvarchar(max) / TEXT	large strings/blobs
`[Indexed]`	Create DB index	`[Indexed]`
`[Indexed(Unique=true)]`	Unique constraint + index	`[Indexed(Unique=true)]`
`[Association("Name")]`	Declare relation endpoint (BOTH sides)	`[Association("Dept-Contacts")]`
`[Aggregated]`	Cascade delete child collection	on collection property
`[Key]` / `[Key(AutoGenerate=true)]`	Mark primary key	for XPBaseObject/XPLiteObject
`[PersistentAlias("expr")]`	Server-side calculated alias	`[PersistentAlias("Price*Qty")]`
`[DbType("nvarchar(50)")]`	Exact DB column type	`[DbType("decimal(18,4)")]`
`[Delayed]`	Defer loading (large blob/text)	on binary/ntext properties
`[FetchOnly]`	Read-only DB computed column	`[FetchOnly]`
`[OptimisticLocking(false)]`	Disable locking on class	class-level
`[OptimisticLockingIgnored]`	Exclude property from locking version	property-level
`[NullValue(0)]`	Default value for null reads	`[NullValue("")]`
`[DisplayName("Label")]`	UI display name	`[DisplayName("First Name")]`
`[VisibleInDetailView(false)]`	Hide in Detail View	property-level
`[NoForeignKey]`	Skip FK constraint generation	`[NoForeignKey]`

Relations

One-to-Many

Both ends MUST use the same association name string.

public class Department : BaseObject {
    public Department(Session session) : base(session) { }

    [Association("Department-Contacts")]
    public XPCollection<Contact> Contacts => GetCollection<Contact>(nameof(Contacts));
}

public class Contact : BaseObject {
    public Contact(Session session) : base(session) { }

    private Department department;
    [Association("Department-Contacts")]
    public Department Department {
        get => department;
        set => SetPropertyValue(nameof(Department), ref department, value);
    }
}

Add [Aggregated] to the collection for cascade delete.

Many-to-Many

Option A: Auto-generated intermediate table

public class Employee : BaseObject {
    public Employee(Session session) : base(session) { }

    [Association("Employee-Tasks")]
    public XPCollection<Task> Tasks => GetCollection<Task>(nameof(Tasks));
}

public class Task : BaseObject {
    public Task(Session session) : base(session) { }

    [Association("Employee-Tasks")]
    public XPCollection<Employee> Employees => GetCollection<Employee>(nameof(Employees));
}
// XPO auto-creates EmployeeTasks intermediate table

Option B: Explicit intermediate class (extra fields)

public class EmployeeTask : BaseObject {
    public EmployeeTask(Session session) : base(session) { }

    private Employee employee;
    [Association("Employee-EmployeeTasks")]
    public Employee Employee {
        get => employee;
        set => SetPropertyValue(nameof(Employee), ref employee, value);
    }

    private Task task;
    [Association("Task-EmployeeTasks")]
    public Task Task {
        get => task;
        set => SetPropertyValue(nameof(Task), ref task, value);
    }
    public DateTime AssignedOn { get; set; }
}

public class Employee : BaseObject {
    [Association("Employee-EmployeeTasks"), Aggregated]
    public XPCollection<EmployeeTask> EmployeeTasks => GetCollection<EmployeeTask>(nameof(EmployeeTasks));

    [ManyToManyAlias(nameof(EmployeeTasks), nameof(EmployeeTask.Task))]
    public XPCollection<Task> Tasks => GetCollection<Task>(nameof(Tasks));
}

One-to-One

public class Person : BaseObject {
    public Person(Session session) : base(session) { }

    private Passport passport;
    public Passport Passport {
        get => passport;
        set {
            Passport prev = passport;
            SetPropertyValue(nameof(Passport), ref passport, value);
            if (!IsLoading) {
                if (prev != null && prev.Person == this) prev.Person = null;
                if (value != null && value.Person != this) value.Person = this;
            }
        }
    }
}

Calculated / Non-Stored Properties

// NonPersistent - in-memory only, NOT filterable server-side
[NonPersistent]
public string FullName => $"{FirstName} {LastName}";

// PersistentAlias - server-side, filterable, no extra DB column
[PersistentAlias("Price * Quantity * (1 - Discount)")]
public decimal TotalPrice {
    get { return Convert.ToDecimal(EvaluateAlias(nameof(TotalPrice))); }
}

// Aggregate alias
[PersistentAlias("Orders.Count()")]
public int OrderCount {
    get { return Convert.ToInt32(EvaluateAlias(nameof(OrderCount))); }
}

// FetchOnly - maps to DB computed column (read-only)
[FetchOnly]
[Persistent("computed_total")]
public decimal ComputedTotal {
    get { return GetPropertyValue<decimal>(nameof(ComputedTotal)); }
}

Lifecycle Hooks

public class Order : BaseObject {
    public Order(Session session) : base(session) { }

    public override void AfterConstruction() {
        base.AfterConstruction();
        OrderDate = DateTime.Now;
        Status = OrderStatus.New;
    }

    public override void OnSaving() {
        base.OnSaving();
        if (IsNewObject) CreatedDate = DateTime.UtcNow;
        LastModified = DateTime.UtcNow;
    }

    public override void OnLoaded() {
        base.OnLoaded();
        // refresh in-memory caches
    }
}

Session Access

// Query in same session
public IList<LineItem> GetPendingItems() {
    return Session.Query<LineItem>()
                  .Where(li => li.Invoice == this && !li.IsProcessed)
                  .ToList();
}

// Find by criteria
public static Contact FindByEmail(Session session, string email) {
    return session.FindObject<Contact>(
        CriteriaOperator.Parse("Email = ?", email));
}

Never create new Session() inside a persistent object. Always use this.Session.

Optimistic Locking

XPO automatically adds OptimisticLockField (int) to most base classes.

// Disable for high-volume log tables
[OptimisticLocking(false)]
public class AuditLog : XPObject {
    public AuditLog(Session session) : base(session) { }
}

// Exclude property from bumping lock version
[OptimisticLockingIgnored]
public DateTime LastViewed {
    get => lastViewed;
    set => SetPropertyValue(nameof(LastViewed), ref lastViewed, value);
}
private DateTime lastViewed;

Common Pitfalls

Pitfall	Solution
Missing `Session` constructor	Every XPO class must have `public MyClass(Session session) : base(session) { }`
Auto-properties `{ get; set; }`	Breaks change tracking — always use `SetPropertyValue` with backing field
`GetCollection<T>()` in constructor	Don't access collections during construction
`new XPCollection<T>(session)` in getter	Creates unbound collection every access — use `GetCollection<T>(nameof(Prop))`
`[Association]` on one side only	Both ends MUST have `[Association("same-name")]`
Default `[Size]` is 100	Without `[Size]`, strings become `nvarchar(100)`
Cross-session object assignment	Never assign an object from one Session to another
`Session.Save()` inside `OnSaving()`	Causes infinite recursion — don't call Save/CommitChanges in hooks
`Session`/`IObjectSpace` stored in static field	Memory leak — always scope to operation with `using var os = ...`
`GetObjects<T>()` without criteria on large tables	Loads entire table — add `CriteriaOperator` or `Take()`

Source Links

Business Model Design with XPO: https://docs.devexpress.com/eXpressAppFramework/113469/business-model-design-orm/business-model-design-with-xpo
Base Persistent Classes: https://docs.devexpress.com/XPO/2026/create-a-data-model/base-persistent-classes
XPObject API: https://docs.devexpress.com/XPO/DevExpress.Xpo.XPObject
BaseObject (BCL XPO): https://docs.devexpress.com/eXpressAppFramework/DevExpress.Persistent.BaseImpl.BaseObject
PersistentAliasAttribute: https://docs.devexpress.com/XPO/DevExpress.Xpo.PersistentAliasAttribute
Collections and Associations: https://docs.devexpress.com/XPO/2055/create-a-data-model/persistent-objects-and-references
Property Change Notifications: https://docs.devexpress.com/eXpressAppFramework/117395/business-model-design-orm/property-changed-event-in-business-classes

xaf-xpo-models