Skip to content
Tutorials Center
My learning

Topics

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).

C#
public record Person(string Name, int Age);
public readonly record struct Point(int X, int Y);

Try it

C# Generated members

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.

C# Pitfalls: reference members and inheritance

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

C#
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 own Equals.
  • record means record class. It is a reference type. record struct is a value type and its positional properties are mutable unless you write readonly record struct.
  • with is 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 Animal is never equal to a Dog.
  • Positional properties are init-only for record classes, so the object can be shaped by with but not mutated in place. Declare { get; set; } explicitly if you really want mutation.
  • You can override pieces. Write your own Equals(Record?) and GetHashCode() to customize equality, or add a sealed 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, sealed ToString). 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.