U2U.ValueObjectComparers 0.1.1

This blog discusses how to implement a Value Object's Equals method efficiently.

What are Value Objects?

In Domain Driven Design objects are divided into two groups: Entities and Value Objects.

Entities are objects that have an identity and life cycle, and NOT the focus of this post.

Value Objects are objects that don't have any real identity and are mainly used to describe aspects of an entity, such as your name which is of type string.

For example, when writing on a whiteboard you want to use a blue marker. If you have many blue markers, do you care which one you are holding? If so, then that marker is an entity, if not it is a value object. Entities are equal when they have the same identity, value objects are equal when all properties that define one are equal.

String is definitely a value object, because you don't care about which instance of "Hello World!" you are holding.

Implementing Equality for Value Objects

To implement equality for a value object we need to compare each of its properties for equality (You could say that a value object's identity is defined by all of its properties). This is not hard, but it is repetitive work. Each time you add a new property you have to update the Equals method to use that property too. This is something I'd like to avoid, if possible.

Here is an example of what a Value Object looks like. No inheritance, so this can also be used for structs.

The Equals method simply delegates to the ValueObjectComparer<SomeObject>. Same for the IEquatable<SomeObject> interface implementation. The IQuatable<T> interface uses a strongly typed Equals method, which is better for structs, as it will avoid boxing.

The difference between the built-in object's Equals and IEquatable<T> is that the compiler will pick the most specific matching Equals(T other).

public class SomeObject : IEquatable<SomeObject>
{
  public string Name { get; set; }
  public int Age { get; set; }

  public override bool Equals(object obj)
    => ValueObjectComparer<SomeObject>.Instance.Equals(this, obj);

  public bool Equals([AllowNull] SomeObject other) 
    => ValueObjectComparer<SomeObject>.Instance.Equals(this, other);
}

Ignoring Certain Properties

Some Value Objects have calculated properties, and using them in the comparison is not necessary. You might want to use the ValueObjectComparer<T> for other, non-value-object, types. So you might want to ignore certain properties for short.

Simply add the [Ignore] attribute to the property, and it won't be used for equality.

[Ignore]
public int NotUsed { get; set; }

Performance

Let's see how the performance compares between the 'Equals' as prescribed by Microsoft or the "Just Once" reflection implementation. For this I have used the excellent BenchmarkDotNet library, and here are the results:

|                                              Method |       Mean |        Min |        Max |
|---------------------------------------------------- |-----------:|-----------:|-----------:|
|                     UsingHCValueObjectsThatAreEqual |   8.657 ms |   8.512 ms |   9.511 ms |
|                     UsingMyValueObjectsThatAreEqual |   9.878 ms |   9.497 ms |  11.083 ms |
|                     UsingMSValueObjectsThatAreEqual | 282.006 ms | 276.861 ms | 296.591 ms |
|          UsingHCValueObjectsThatAreEqualWithNesting |  24.081 ms |  22.648 ms |  28.420 ms |
|          UsingMyValueObjectsThatAreEqualWithNesting |  33.038 ms |  32.148 ms |  35.188 ms |
|          UsingMSValueObjectsThatAreEqualWithNesting | 607.281 ms | 592.930 ms | 647.931 ms |
|                    UsingSameInstanceOfHCValueObject |   4.238 ms |   4.193 ms |   4.281 ms |
|                    UsingSameInstanceOfMyValueObject |   4.339 ms |   4.223 ms |   4.549 ms |
|                    UsingSameInstanceOfMSValueObject |   3.698 ms |   3.676 ms |   3.747 ms |
|                  UsingHCValueObjectsThatAreNotEqual |   9.275 ms |   9.127 ms |   9.318 ms |
|                  UsingMyValueObjectsThatAreNotEqual |   8.491 ms |   8.393 ms |   8.660 ms |
|                  UsingMSValueObjectsThatAreNotEqual | 233.310 ms | 232.583 ms | 234.565 ms |
|               UsingMyValueObjectStructsThatAreEqual |  27.393 ms |  27.334 ms |  27.443 ms |
| UsingMyValueObjectStructsThatAreEqualWithInModifier |  27.162 ms |  26.475 ms |  28.694 ms |

Using ValueObjectComparer<T> results in about a 20x-30x faster execution time then the Microsoft implementation, and is about as fast as the hardcoded version (with no nesting)!

You can read more here