Skip to content

collection properties

vijay@envivo edited this page Oct 20, 2026 · 14 revisions

Collection Properties

Collection properties are similar to Object properties:

public class ShoppingCart : IAggregateRoot
{
    /// <summary>
    /// <inheritdoc/>
    /// </summary>
    [Key]
    public Guid Id { get; init; }

    /// <summary>
    /// The items contained within this cart
    /// </summary>
    [Relationship(RelationshipType.Owns)]
    [Collection(canExpandRows: true)]
    [UI(isShownInline: true)]
    public ICollection<ShoppingCartItem> Items { get; set; } = []; //👈

    ...
}

Relationships

Like objects, collections of objects may have the following relationship types:

Relationship Type Description
Has (aka "Aggregation") Object B is linked to Collection A.
Object B will always exist, regardless of what happens to Collection A.
Owns (aka "Composition") Object B is part of Collection A.
If Collection A is destroyed, Object B will cease to exist.

These relationship types are declared using the Relationship attribute, like so:

    [Relationship(RelationshipType.Owns)] //👈
    public ICollection<OrderItem> OrderItems { get; set; } = [];

“Has” relationship type

With this relationship type, you can only add existing objects to the collection via the Add existing option:

As with object properties, the UI only allow selection from an existing set of objects, so you need to declare the query that will provide that set. See Queries and Filters for more information.

“Owns” relationship type

With this relationship type, you can only add new objects to the collection via the Add new option:

Custom association logic

There may be times when extra domain logic needs to run whenever an object is added to a collection.
For example, object B may need a reference back to its parent A.
Similarly, you may want custom logic whenever an object is removed from a collection.

You can use one of these strategies to achieve this:

1. Custom collections

Create a custom collection that embeds the domain logic within the appropriate methods:

public class ShoppingCartItems: IList<ShoppingCartItem>
{
	private List<ShoppingCartItem> _Items = [];

    [Relationship(RelationshipType.OwnedBy)]
    public ShoppingCart ShoppingCart { get; internal set; }

    public void Add(ShoppingCartItem itemToAdd)
    {
        _Items.Add(itemToAdd);
        itemToAdd.ShoppingCart = this.ShoppingCart;   // 👈 Custom logic to run on Add
    }

    public void Remove(ShoppingCartItem itemToAdd)
    {
        _Items.Remove(itemToAdd);
        itemToAdd.ShoppingCart = null;                // 👈 Custom logic to run on Remove
    }

    // other members here
}

And use the custom collection type within your object:

public class ShoppingCart: IAggregateRoot
{
    [Relationship(RelationshipType.Owns)]
    public ShoppingCartItems Items { get; set; } = new();
}

2. Custom Add and Remove methods

Alongside the collection property, write new AddTo[PropertyName] and RemoveFrom[PropertyName] methods that accept the object. Then use the CollectionAttribute to bind them to the property:

public class ShoppingCart : IAggregateRoot
{
    [Relationship(RelationshipType.Owns)]
    [Collection(addMethodName : nameof(AddToItems), removeMethodName : nameof(RemoveFromItems))] //👈
    public ICollection<OrderItem> OrderItems { get; set; } = [];

    public void AddToItems(ShoppingCartItem itemToAdd) //👈
    {
        OrderItems.Add(itemToAdd);
        itemToAdd.ShoppingCart = this;    // Custom logic to run on Add
    }

    public void RemoveFromItems(ShoppingCartItem itemToRemove) //👈
    {
        OrderItems.Remove(itemToRemove);
        itemToRemove.ShoppingCart = null;  // Custom logic to run on Remove
    }
}

At run-time, Fresnel will use these custom methods to add or remove collection elements.

Both options have their pros and cons, so use the one that best fits your model.

Customising the UI

Table columns

To restrict the columns that are shown, decorate the property with the CollectionAttribute.VisibleColumnNames attribute. You can also control the order of the columns like so:

{
    ...
    [Collection(visibleColumnNames: [nameof(ShoppingCartItem.Product), //👈
                                     nameof(ShoppingCartItem.Quantity), 
                                     nameof(ShoppingCartItem.Price)])]
    public ICollection<OrderItem> OrderItems { get; set; } = [];
}

By default, collections will show all columns. To keep prototyping fast, only set explicit column names when needed.

Expandable rows

Sometimes conversations flow easier if a collection item can be expanded directly inside the table. To do this, use the CollectionAttribute.CanExpandRows attribute:

{
    ...
    [Collection(canExpandRows: true)] //👈
    public ICollection<OrderItem> OrderItems { get; set; } = [];
}

Clicking the button in the first column allows you to expand and collapse the row:

Note that only the top-level properties are shown in the expanded view. To see all of the detail, the item must be opened into its own explorer panel:

💡 Developer Tips

  • Prefer interface types (ICollection<T>, IList<T>) over concrete types (e.g. List<T>)
  • Initialise the collection immediately, to prevent null exceptions
  • When adding references to Aggregate Roots, you may need intermediary Aggregate References. See the Aggregate References section for more information.

Clone this wiki locally