Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Record Equality: How It Works and When to Customize

Understand how C# records implement value-based equality, when the default behavior is sufficient, and when to override Equals and GetHashCode for collections or custom rules.

~4 min readC#
#C# records#value equality#GetHashCode#EqualityContract
Two identical record boxes being compared with a checkmark, symbolizing value-based equality in C#.

C# records give you value-based equality without writing boilerplate. When you declare a record, the compiler generates an Equals method, GetHashCode, and operators == and != that compare the record's data members by value. That behavior is convenient, but it is not always what you want. This article explains how C# record equality works under the hood, where it falls short, and how to take control when your data model requires it.

How Records Implement Equality

Consider a simple positional record:

csharp
public record Person(string FirstName, string LastName);

The compiler synthesizes an Equals method that checks the runtime type and then compares each data member using EqualityComparer<T>.Default. It also generates a matching GetHashCode that combines the hash codes of those members. The == and != operators delegate to that Equals method.

That means two records are equal if they have the same type and all their compared data members are equal. The comparison is shallow in the sense that it uses the default equality comparer for each member. For simple value types like strings and integers, that gives you intuitive value semantics.

Comparing Records with Classes

A regular class uses reference equality by default. Two class instances with identical property values are not equal unless you override Equals and GetHashCode manually. Records remove that manual work. The tradeoff is that record equality works best when instances are treated as immutable data; the generated comparison assumes the data does not change after creation.

If you need reference semantics for a mutable object, a class is the better choice. If you need value semantics and are willing to treat instances as immutable data, a record saves you from writing repetitive comparison code.

Customizing Record Equality

The default record equality compares the record's data members. Sometimes you want to exclude certain fields or apply a different comparison rule. You can override the generated members manually.

For example, suppose you want to compare only the Id property of an entity record:

csharp
public record Entity { public int Id { get; init; } public string Name { get; init; } public virtual bool Equals(Entity? other) { return other is not null && Id == other.Id; } public override int GetHashCode() => Id.GetHashCode(); }

When you override Equals, you must also override GetHashCode to keep the contract that equal objects have equal hash codes. The compiler still generates the == and != operators, but they call your Equals method, so the custom logic is used consistently.

Records with Collections and Nested Objects

Record equality compares each data member using the default equality comparer. If a member is a list or a dictionary, that comparer uses reference equality for the collection itself. Two records with identical list contents but different list instances are not equal.

csharp
public record Order(int Id, List<string> Items); var a = new Order(1, new List<string> { "apple", "banana" }); var b = new Order(1, new List<string> { "apple", "banana" }); Console.WriteLine(a == b); // False

To get structural equality for collections, you need to override Equals and compare the collection contents explicitly—for example, with SequenceEqual. Alternatively, use a custom comparer that provides the value semantics you need. This is a common source of confusion because developers expect deep equality from records.

Performance Considerations

The generated GetHashCode computes a hash from every data member every time it is called. For records with many members or members that are expensive to hash, this can become a measurable cost in hash-based collections like Dictionary or HashSet. The compiler does not cache the hash code automatically.

If a record is used frequently as a dictionary key and has a large number of members, consider overriding GetHashCode to compute a hash from a subset of members that uniquely identify the record. You can also cache the hash code in a private field if the record is immutable and the hash is expensive to compute. Keep in mind that caching only works if the record is truly immutable; otherwise, the cached value becomes stale.

Common Pitfalls with Record Equality

One subtle issue arises with inheritance. A derived record inherits the equality contract of its base, but the generated Equals checks the runtime type using the EqualityContract property. Two records of different derived types are never equal, even if they share all data values. That is usually correct, but it can surprise developers who expect cross-type equality.

Another pitfall is mutable records. You can declare a record with init-only properties, but you can also use set accessors. If you mutate a record after it has been added to a hash-based collection, its hash code changes and the collection becomes corrupted. Treat records as immutable values to avoid this.

When to Use Record Equality vs Manual Implementation

Use the default record equality when your record is immutable, all data members should participate in equality, and the member values themselves have sensible value semantics. That covers DTOs, event messages, and value objects.

Override equality when you need to ignore certain fields, compare nested collections structurally, or apply a domain-specific rule. Manual implementation gives you full control but adds maintenance burden. Weigh the cost of custom code against the benefit of correct behavior for your specific data model.

For most cases, the default C# record equality works well. The key is to understand what the compiler generates and to recognize when your data model requires a different comparison strategy.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.