C# Reference ยท Classes and Object-Oriented Concepts
Records and value equality
Reference for C# records and record structs: generated equality, ==, ToString, with expressions, deconstruction, inheritance rules and pitfalls with reference members.
A record is a class (or, with record struct, a struct) for which the compiler generates the boilerplate of a data carrier: value-based Equals, GetHashCode and ==/!=, a readable ToString, a copy constructor used by with, and, for positional records, a primary constructor, init-only properties and a Deconstruct method. Two records are equal when their types match and each member is equal, not when they are the same object.
Use records for DTOs, messages, configuration and domain values. Use ordinary classes for objects with identity and behavior (a BankAccount stays the same account when its balance changes).
public record Person(string Name, int Age); public readonly record struct Point(int X, int Y);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public record Name(Type Member, ...); // positional record class public record struct Name(Type Member, ...); // mutable record struct public readonly record struct Name(Type Member); // immutable record struct public record Name { public required string Value { get; init; } // nominal (non-positional) form } var copy = original with { Member = newValue };
| Generated | Description |
|---|---|
Equals, ==, !=, GetHashCode |
Member-wise comparison using each member's default equality. For record classes the runtime type must also match. |
ToString() |
TypeName { Member = value, ... }. Can be replaced or sealed. |
Deconstruct |
Positional records only; one out parameter per positional member. |
| Copy constructor | Protected for record classes; used by with. |
EqualityContract |
Record classes only; a protected Type property that makes equality respect the exact type. |
Usage notes
- Equality is member-wise and shallow. A
List<T>member compares by reference, so two records holding equal-looking lists are not equal (first line of the second example). Use arrays that are shared, immutable collections, or your ownEquals. recordmeansrecord class. It is a reference type.record structis a value type and its positional properties are mutable unless you writereadonly record struct.withis a shallow copy. Nested reference members are shared with the original. See Copying objects.- Records can inherit from records, not from classes (and not the reverse). Derived records add members; equality respects the runtime type, so an
Animalis never equal to aDog. - Positional properties are
init-only for record classes, so the object can be shaped bywithbut not mutated in place. Declare{ get; set; }explicitly if you really want mutation. - You can override pieces. Write your own
Equals(Record?)andGetHashCode()to customize equality, or add asealed override ToString()to stop derived records from changing it. - Hash codes are process specific. Never persist
GetHashCode()results or print them. - Added in C# 9 (records) and C# 10 (
record struct,sealedToString). Primary-constructor parameters of ordinary classes (C# 12) do not create properties, unlike positional records. - Do not use mutable records as dictionary keys. Changing a member after insertion changes the hash code, which hides the entry.