Entities

Entity definitions need to follow certain rules in order to work with Xams.

Entity Rules

Entities must have a string Name field or a string field with the attribute UIName for lookup fields.
Composite Primary Keys are not supported.
Self-referencing entities must NOT include navigation properties to themselves.
System entities use base table names: User, Team, Role, Setting are always the table names—even when extended (e.g., public class AppUser : User → table name is "User" for queries and permissions).

Self-Referencing Entities

For entities that reference themselves (like nested comments), use only the ID field - do not include the navigation property.

Project / Entities / Comment.cs

[Table(nameof(Comment))]
public class Comment : BaseEntity
{
    public Guid CommentId { get; set; }

    [UIRequired]
    public string Content { get; set; }

    // Self-reference - use ID only
    public Guid? ParentCommentId { get; set; }
    // ❌ Do NOT add: public Comment? ParentComment { get; set; }
}

Navigation properties on self-referencing entities cause nullable reference errors during queries. Use only the ID field and query parent/child records separately if needed.

Cascade Delete

Configure cascade delete using the nullable operator ? and the CascadeDelete attribute.

Project / Entities / Widget.cs

[Table(nameof(Widget))]
public class Widget : BaseEntity
{
    public Guid WidgetId { get; set; }

    // Name is not nullable and required
    [UIName]
    public string Name { get; set; }

    // Company is not nullable making it required
    // Deleting the Company deletes this record
    public Guid CompanyId { get; set; }
    public Department Company { get; set; }

    // Manufacturer is nullable making it optional
    // Deleting the Manufacturer sets this to null
    public Guid? ManufacturerId { get; set; }
    public Manufacturer? Manufacturer { get; set; }

    // Contact is nullable but the UIRequired attribute makes it required
    // Deleting the contact sets this to null
    [UIRequired]
    public Guid? ContactId { get; set; }
    public Contact Contact { get; set; }

    // Address is nullable making it optional
    // The CascadeDelete attribute deletes this
    // record when the Address is deleted
    [CascadeDelete]
    public Guid? AddressId { get; set; }
    public Address Address { get; set; }
}

When a user deletes a record, delete permissions are checked only on the record being deleted—not on any dependent records removed through cascading. This behavior is consistent with how enterprise CRM systems operate.