Understanding Value Equality in .NET Records

▸ Defining value equality

▸ Challenges of collections in records

public record OrderItem(
    string ProductName,
    int Quantity,
    decimal Price);

public record BadOrder(
    string OrderId,
    string CustomerName,
    List<OrderItem> Items);

[Test]
public void TestBadOrderEquality()
{
    OrderItem item1 = new("ProductA", 2, 10.0m);
    OrderItem item2 = new("ProductB", 1, 20.0m);

    BadOrder order1 = new("Order1", "John Doe", [item1, item2]);
    BadOrder order2 = new("Order1", "John Doe", [item1, item2]);

    Assert.Multiple(() =>
    {
        Assert.That(order1.OrderId, Is.EqualTo(order2.OrderId));
        Assert.That(order1.CustomerName, Is.EqualTo(order2.CustomerName));
        Assert.That(order1.Items[0], Is.EqualTo(order2.Items[0]));
        Assert.That(order1.Items[1], Is.EqualTo(order2.Items[1]));

        // :-( THIS LINE WILL FAIL BECAUSE THE COLLECTIONS ARE NOT VALUE EQUAL
        Assert.That(order1, Is.EqualTo(order2));
    });
}

▸ Introducing ValueCollection for value-based collection equality

public record GoodOrder(
    string OrderId,
    string CustomerName,
    ValueCollection<OrderItem> Items);

using System.Collections.ObjectModel;
using System.Text;

/// <summary>
/// Represents a collection of values.
/// </summary>
/// <param name="values">The values to initialize the collection with.</param>
/// <typeparam name="T">The type of the values in the collection.</typeparam>
public class ValueCollection<T>(params IList<T> values)
    : ReadOnlyCollection<T>(new List<T>(values))
{
    /// <summary>
    /// Adds an item to the collection.
    /// </summary>
    /// <param name="item">The object to add to the value collection.</param>
    /// <exception cref="ArgumentNullException">Thrown when item is null.</exception>
    public void Add(T item)
    {
        ArgumentNullException.ThrowIfNull(item);

        Items.Add(item);
    }

    /// <summary>
    /// Determines whether the specified object is equal to the current object.
    /// The comparison is done by comparing the items in the collection.
    /// </summary>
    /// <param name="obj">The object to compare with the current object.</param>
    /// <returns>true if the specified object is equal to the current object; otherwise, false.</returns>
    public override bool Equals(object? obj)
    {
        if (ReferenceEquals(null, obj))
        {
            return false;
        }

        if (ReferenceEquals(this, obj))
        {
            return true;
        }

        return obj is ValueCollection<T> other
               && other.Items.SequenceEqual(Items);
    }

    /// <inheritdoc />
    public override int GetHashCode()
    {
        HashCode hashCode = new();
        foreach (T item in Items)
        {
            hashCode.Add(item);
        }

        return hashCode.ToHashCode();
    }

    /// <summary>
    /// Returns a string that represents the current object.
    /// If the collection has more than 3 items, only the first 3 items are shown.
    /// </summary>
    /// <returns>A string that represents the current object.</returns>
    public override string ToString()
    {
        StringBuilder sb = new();

        sb.Append("[ ");

        // if we have more than 3 items, we only show the first 3 then "..."
        if (Items.Count > 3)
        {
            sb.AppendJoin(", ", Items.Take(3));
            sb.Append(", ...");
        }
        else
        {
            sb.AppendJoin(", ", Items);
        }

        sb.Append(" ]");

        return sb.ToString();
    }
}

▸ Testing value equality with GoodOrder

[Test]
public void TestGoodOrderEquality()
{
    OrderItem item1 = new("ProductA", 2, 10.0m);
    OrderItem item2 = new("ProductB", 1, 20.0m);

    GoodOrder order1 = new("Order1", "John Doe", [item1, item2]);
    GoodOrder order2 = new("Order1", "John Doe", [item1, item2]);

    Assert.Multiple(() =>
    {
        Assert.That(order1.OrderId, Is.EqualTo(order2.OrderId));
        Assert.That(order1.CustomerName, Is.EqualTo(order2.CustomerName));
        Assert.That(order1.Items[0], Is.EqualTo(order2.Items[0]));
        Assert.That(order1.Items[1], Is.EqualTo(order2.Items[1]));

        // :-) THIS LINE WILL PASS BECAUSE THE COLLECTIONS ARE VALUE EQUAL
        Assert.That(order1, Is.EqualTo(order2));
    });
}

▸ Advantages of using ValueCollection

Consistent equality semantics: by overriding the Equals and GetHashCode methods, ValueCollection<T> ensures consistent value-based equality, making it easier to work with records that contain collections.
Simplified testing: since equality behaviour matches the expected value-based semantics, writing and maintaining unit tests becomes more straightforward without the need to address reference equality issues.
Enhanced readability and maintainability: the use of ValueCollection<T> makes the intent explicit, that the collection should be treated as a set of values and not merely a reference, which enhances code readability and maintainability.

▸ Key considerations

Immutability: ValueCollection<T> is based on ReadOnlyCollection<T>, meaning that modifications are restricted after the collection is created, except by using the Add method provided. This characteristic is crucial for preserving immutability, which is fundamental for records.
Performance implications: depending on the size of the collection, computing hash codes or performing equality checks may introduce performance overhead, as each element in the collection must be evaluated individually.

▸ Conclusion