Building a custom EqualityComparer for HashSet in C#

When you add items to a HashSet in C#, the collection relies on two mechanisms to decide whether a value already exists: an equality check and a hash function. Out of the box, the default comparer walks the fields of your type and produces a numeric hash, which works fine for primitives and simple POCOs. The moment your domain logic considers two objects "the same" only when a specific subset of properties match, the framework's default behaviour quietly disagrees with your rules. That gap is where custom comparers earn their keep.

A custom EqualityComparer hands you explicit control over what counts as a duplicate and how values are bucketed into hash slots. Once you grasp the contract, you can model collections around business rules instead of refactoring every object to override Equals and GetHashCode, which is especially useful when working with third-party records you cannot modify.

How a HashSet stores and looks up items

Internally, HashSet in System.Collections.Generic maintains an array of buckets and a parallel array of slots that hold references to the entries you've inserted. When you call Add, the runtime computes the hash code of the item, applies a bitmask to translate it into a bucket index, and scans any chained entries for an equality match before writing a new slot. If you call Contains, the same steps happen without the final write.

The bucket-and-slot layout has a couple of practical consequences. Lookup remains effectively O(1) only while the distribution of hash codes is reasonably even. Collisions degrade the constant-time promise because the chain must be walked entry by entry. Mutating an object's state after insertion can also leave the entry orphaned, because the bucket address was computed from the original hash, which is the same reason Dictionary keys must remain stable.

These mechanics explain why any comparer you write must keep Equals and GetHashCode consistent: equal objects must produce equal hashes, and unequal objects should produce different hashes whenever feasible. Violate that pairing and either lookups return the wrong answer or the buckets pile up in a way that turns every Add into a linear scan.

The default behaviour and why it stops fitting

The default equality comparer for a reference type uses the object's reference identity, and for value types it uses memberwise comparison after reflection. Both behaviours are technically correct and frequently unhelpful. Imagine loading a CSV of Australian business addresses into a HashSet for deduplication. Two records representing the same ABN registered at the same Sydney suburb are semantically duplicates, but AddressLine1, Suburb, and Postcode alone do not distinguish them reliably against entries with slightly different formatting.

Overriding Equals and GetHashCode on the type itself is one path forward, and for many shops in Melbourne and Brisbane that approach is the conventional wisdom taught in local meetups. It also couples the comparison logic tightly to the data class, which becomes awkward when the same record belongs to multiple collections where equality means different things in each context. A user record is "the same" as a billing record is "the same" as an audit record, and these three definitions rarely align.

Implementing IEqualityComparer<T> decouples the rules from the type and lets each collection host its own definition. You can use one comparer for deduplication, another for grouping by case-insensitive email, and a third for matching on a synthetic identity drawn from external systems, all without touching the type's own members.

Building a comparer step by step

The interface itself is small, with three members that matter. Equals takes two instances of T and returns a bool, GetHashCode returns an int, and Equals(object, object) plus GetHashCode(object) handle the non-generic surface inherited from the base interface. Most implementations override only the typed members and inherit the object-typed ones from EqualityComparer<T>'s default fallback.

A minimal example for an Order entity might look like a class that returns true when OrderId matches, ignoring timestamps and audit fields. GetHashCode for the same comparer needs to derive its value solely from OrderId, so that two orders with different captured-at values still collide into the same bucket. As an aside, many teams in Australia's fintech sector anchor such identifiers on AUSTRAC-supplied data feeds, where mismatch handling is auditable through Australian Prudential Regulation Authority reporting cycles.

The fluent idiom in modern C# leans on override patterns that look like language features, but they compile down to the same interface. Writing the class by hand keeps the dependency surface visible, which matters when code is reviewed by colleagues who keep an eye on the Australian Cyber Security Centre's secure coding guidance.

A worked example with complex objects

To make this concrete, consider a Product catalogue pulled from the National Product Catalogue used by Australian pharmacies and healthcare providers. Each entry carries a GTIN, a supplier code, a name, and pricing fields denominated in Australian dollars. Two catalogue entries from different suppliers can represent the same product by GTIN even when their internal SKUs and shelf names diverge.

A comparer that ignores SKU, name, and price but insists on identical GTIN eliminates duplicates without flattening the underlying records. GetHashCode in that comparer multiplies GTIN's hash by a prime such as 397 and mixes in a salt integer to spread results across buckets. Choosing a multiplier is more art than science; small primes keep distribution tight while large primes widen the spread. Most local teams in Perth and Adelaide settle on 397 or 31 as community defaults after enough profiling.

The same pattern scales across other identity-bearing records common to Australian systems. The Digital Transformation Agency's data standards suggest similar conventions for de-duplication during intake, and AU$ amount fields are usually ignored for equality purposes because they shift between ingestion runs. Baking those decisions into a comparer rather than into the entity keeps the model free of helper properties that serve only one consumer.

Case sensitivity, culture, and immutable records

String-heavy code in Australia carries a regional quirk: comparison rules often depend on whether the user prefers en-AU or en-US collations, and Australian English differs from US spelling in predictable ways. The default string comparer ignores culture entirely, which is fine for ASCII keys and problematic for catalogue words that mix accented characters, US-style trailing whitespace, or currency symbols.

For customer-facing lookups, StringComparer.Create(CultureInfo.GetCultureInfo("en-AU"), CompareOptions.IgnoreCase) is a pragmatic choice. For internal SLA timers tied to AEST, ISO 8601 strings compared with OrdinalIgnoreCase outperform culture-aware variants and play nicely with audit logs reviewed by the Office of the Australian Information Commissioner. Mixing the two approaches inside the same HashSet rarely causes trouble, but mixing Ordinal and culture-aware rules across collaborating modules invites subtle bugs.

Record types introduced in C# 9 free you from writing Equals and GetHashCode for many cases by deriving them from positional parameters. The trade-off is that records fix the equality definition at compile time, so when an Australian government dataset treats the same person across the Commonwealth Persons Portal under a single identity, you cannot redefine the equality contract to include legacy ID formats. A custom comparer layered on top of records recaptures the flexibility the language designers removed on purpose.

Avoiding collisions and common pitfalls

A surprising amount of debugging time in collections work traces back to GetHashCode returning the same value for every instance of a type. The bug usually looks like a comparer that forgets to mix in a field, or worse, returns a constant. The HashSet then behaves like a linked list, and the developer concludes that HashSet is slow, when in fact the comparer has broken the dispersion. Unit tests that assert uniqueness across a synthetic population catch this before it ships.

Another recurring mistake is mutating a field that contributes to GetHashCode after the object enters the HashSet. Picture an Order whose Status transitions from Pending to Shipped; if Status feeds into the hash, the original bucket becomes unreachable until the entry is removed and re-added. Many teams in Sydney's banking district enforce this through code review checklists that ban post-insertion mutation on hash-bearing fields, a habit reinforced by APRA's expectation of state-stable identifiers across reconciliation runs.

Threading adds another wrinkle. GetHashCode and Equals can be called on different threads simultaneously, so both must be pure functions of the fields they read. Closures that capture loggers, request contexts, or HttpContext references turn comparers into sources of memory leaks and NullReferenceException crashes. Static, allocation-free comparers are the cleanest answer.

Real-world usage patterns

Once the comparer exists, the rest of the code becomes conventional. A deduplication pipeline feeds records through the HashSet during ingestion and emits a stable diff. A real-time fraud-screening service in a Melbourne fintech keeps a rolling set of recent transaction fingerprints, with an eviction policy that prunes entries older than a window measured in AEST hours. A test harness asserts that two deserialised payloads compare equal under a strict comparer while differing under a tolerant one.

Benchmarking matters. When the comparer discriminates on a single integer, the overhead compared to the default reference comparer is negligible. When it touches multiple strings or runs culture-aware comparisons, the gap can widen enough to affect high-throughput endpoints. BenchmarkDotNet profiles run on Australian cloud regions around Sydney and Melbourne give numbers that translate more directly into production behaviour than results from offshore test labs.

Custom comparers are therefore not exotic machinery. They are an ordinary tool for an ordinary job: letting a collection reflect the rules of the domain. With a careful implementation and a small set of tests covering collision cases, HashSet becomes a deterministic, fast, and auditable building block, qualities that Australian regulators and engineering leads tend to ask for in any reviewed system.