How do I compare two dictionaries by value with Generator.Equals?

Use the [UnorderedEquality] attribute on dictionary properties; it compares keys and values without caring about order, similar to Enumerable.SequenceEqual for dictionaries, as shown in the examples.

Can I use Generator.Equals with nullable numeric types?

Yes, attributes like [PrecisionEquality] support nullable variants (e.g., double?), handling nulls correctly where both null are equal and one null is not equal, per the README.

Generator.Equals or manual IEquatable implementation for performance-critical code?

Manual implementation might be better for extreme performance tuning, as Generator.Equals adds abstraction and features like diff reporting that incur overhead, though it generates efficient code for most cases.

How to ignore inherited properties in a derived class?

Set IgnoreInheritedMembers = true in the [Equatable] attribute; this skips base.Equals() and compares only declared properties, useful for redefining equality without considering the base class.

Does Generator.Equals work with C# records and record structs?

Yes, it fully supports records, record structs, classes, and structs, enhancing built-in equality with attributes for collections and custom logic, as demonstrated in the usage samples.

What happens if I add a new property to an [Equatable] type?

The generator automatically includes it in equality comparisons unless annotated with [IgnoreEquality], ensuring correctness without manual updates, reducing maintenance errors.

How to implement a custom comparer for a specific property?

Use the [CustomEquality] attribute and specify a type that implements IEqualityComparer or has a static Default property, following the guidelines in the CustomEquality section.

Generator.Equals — C# IEquatable Source Generator

What is Generator.Equals?

Generator.Equals is a C# source generator that automatically implements the `IEquatable<T>` interface, along with `Equals` and `GetHashCode` methods, using attributes. It solves the problem of writing and maintaining correct, efficient equality logic, which is tedious and error-prone when done manually. The generator produces the code at compile time, ensuring best practices and eliminating boilerplate.

Target Audience

C# developers working on projects where value equality is important, such as those using domain models, data transfer objects, or any type that needs correct `Equals` and `GetHashCode` implementations.

Value Proposition

Developers choose Generator.Equals because it drastically reduces manual coding and potential bugs in equality logic, supports complex scenarios like collections and inheritance out of the box, and provides detailed diff reporting, all through a simple, declarative attribute-based API.

A source code generator for automatically implementing IEquatable<T> using only attributes.

Use Cases

Best For

Automatically generating equality implementations for C# records, classes, and structs
Comparing collections (arrays, lists, dictionaries) by value instead of reference
Implementing complex equality logic with custom comparers or precision tolerances
Handling inheritance hierarchies where equality needs to consider base class properties
Getting detailed reports on differences between two object instances for debugging or auditing
Eliminating boilerplate code for IEquatable<T> in large codebases

Not Ideal For

Projects stuck on .NET frameworks or C# versions below 9.0, as it requires LangVersion >= 9.0
Scenarios requiring runtime equality logic generation for dynamic or reflection-based types, since it's compile-time only
Teams with strict 'no external source generators' policies due to build process or tooling constraints
Simple data transfer objects where C# records' built-in equality suffices without the added attribute complexity

Pros & Cons

Pros

Zero Boilerplate Implementation

Marking a type with [Equatable] automatically generates IEquatable<T>, Equals, and GetHashCode, eliminating tedious and error-prone manual coding, as shown in the record example.

Collection-Aware Value Comparisons

Supports arrays, lists, dictionaries, and sets with attributes like [OrderedEquality] and [SetEquality], enabling deep value-based comparisons out of the box.

Highly Customizable Per-Property

Offers attributes for string comparison, numeric precision, references, and custom comparers, allowing fine-grained control without rewriting entire equality logic.

Inheritance and Deep Equality

Correctly chains base.Equals() across hierarchies and inherits attributes from overridden properties, ensuring deep equality without manual boilerplate, as detailed in the migration notes.

Structured Diff Reporting

Provides an Inequalities() method that returns detailed member-level differences with paths into nested objects and collections, useful for debugging and auditing.

Cons

C# Version Dependency

Requires setting LangVersion to 9.0 or higher, which can block adoption in legacy projects or environments with fixed toolchains.

Attribute Complexity Overhead

Developers must learn and correctly apply multiple attributes (e.g., [CustomEquality], [PrecisionEquality]), which can be overkill for simple types compared to hand-written code.

No Runtime Flexibility

As a compile-time source generator, it cannot adapt to runtime type changes or dynamic objects, limiting use in highly reflective or plugin-based architectures.

Potential Performance Trade-offs

Features like collection comparisons and structured diffs add overhead; for instance, [SetEquality] has hashing limitations and can be expensive for large collections.

Frequently Asked Questions

What is Generator.Equals?

Target Audience

Value Proposition

Use Cases

Best For

Automatically generating equality implementations for C# records, classes, and structs
Comparing collections (arrays, lists, dictionaries) by value instead of reference
Implementing complex equality logic with custom comparers or precision tolerances
Handling inheritance hierarchies where equality needs to consider base class properties
Getting detailed reports on differences between two object instances for debugging or auditing
Eliminating boilerplate code for IEquatable<T> in large codebases

Not Ideal For

Projects stuck on .NET frameworks or C# versions below 9.0, as it requires LangVersion >= 9.0
Scenarios requiring runtime equality logic generation for dynamic or reflection-based types, since it's compile-time only
Teams with strict 'no external source generators' policies due to build process or tooling constraints
Simple data transfer objects where C# records' built-in equality suffices without the added attribute complexity

Pros & Cons

Pros

Zero Boilerplate Implementation

Marking a type with [Equatable] automatically generates IEquatable<T>, Equals, and GetHashCode, eliminating tedious and error-prone manual coding, as shown in the record example.

Collection-Aware Value Comparisons

Supports arrays, lists, dictionaries, and sets with attributes like [OrderedEquality] and [SetEquality], enabling deep value-based comparisons out of the box.

Highly Customizable Per-Property

Offers attributes for string comparison, numeric precision, references, and custom comparers, allowing fine-grained control without rewriting entire equality logic.

Inheritance and Deep Equality

Correctly chains base.Equals() across hierarchies and inherits attributes from overridden properties, ensuring deep equality without manual boilerplate, as detailed in the migration notes.

Structured Diff Reporting

Provides an Inequalities() method that returns detailed member-level differences with paths into nested objects and collections, useful for debugging and auditing.

Cons

C# Version Dependency

Requires setting LangVersion to 9.0 or higher, which can block adoption in legacy projects or environments with fixed toolchains.

Attribute Complexity Overhead

Developers must learn and correctly apply multiple attributes (e.g., [CustomEquality], [PrecisionEquality]), which can be overkill for simple types compared to hand-written code.

No Runtime Flexibility

As a compile-time source generator, it cannot adapt to runtime type changes or dynamic objects, limiting use in highly reflective or plugin-based architectures.

Potential Performance Trade-offs

Features like collection comparisons and structured diffs add overhead; for instance, [SetEquality] has hashing limitations and can be expensive for large collections.

Frequently Asked Questions

Generator.Equals

What is Generator.Equals?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Generator.Equals

What is Generator.Equals?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?