A class asks "is this the same object?" A record asks "does this hold the same data?" — and for a lot of modern C#, that second question is the one you actually care about.

Say you have two Point objects, each with X = 3, Y = 4. Are they equal? If Point is an ordinary class, the answer — by default — is no. C# classes compare by reference: two instances are only "equal" if they're literally the same object in memory, even if every field inside them is identical.

That surprises a lot of people the first time they hit it, because for plain data — a coordinate, a money amount, a snapshot of an order at a point in time — "equal" obviously should mean "holds the same values," not "is the same object." Getting that right with a plain class means hand-writing Equals, GetHashCode, and usually a readable ToString too — for every single data type in your codebase.

In this lesson, you'll learn what records are, how record/record class/record struct differ, why they give you value-based equality for free, and how with expressions let you create modified copies without ever mutating the original.

What Is It?

The Simple Explanation

A record is a special kind of type, purpose-built for modeling data rather than behavior. You declare its shape once — the properties it holds — and the compiler automatically writes the boring-but-important plumbing for you: equality that compares actual values, a readable string representation, and an easy way to make a modified copy without touching the original.

The Technical Definition

A record (C# 9) is a reference type declared with the record (or explicitly record class) keyword that the compiler augments with synthesized value-based equality (Equals, GetHashCode, ==/!=), a synthesized ToString that prints all property values, a synthesized Deconstruct method, and support for with expressions that produce a copy with one or more properties changed. A record struct (C# 10) applies the same synthesized members to a value type instead of a reference type, when you want records' ergonomics with struct's stack-allocation and copy-by-value semantics.

Why Does It Exist?

The Problem

Modeling a plain data type as a class means hand-rolling a lot of repetitive machinery to make it behave the way data intuitively should:

public class Point
{
    public int X { get; }
    public int Y { get; }

    public Point(int x, int y) { X = x; Y = y; }

    public override bool Equals(object? obj) =>
        obj is Point other && X == other.X && Y == other.Y;

    public override int GetHashCode() => HashCode.Combine(X, Y);

    public override string ToString() => $"Point {{ X = {X}, Y = {Y} }}";
}

That's a lot of boilerplate for a type that's just "two numbers." And every data type in your codebase — an order snapshot, a money value, a coordinate — needs the same treatment, over and over, or you get subtly wrong equality (two identical-looking objects that Equals says are different) and unhelpful debug output (ToString() just prints the type's namespace-qualified name).

The Need

Developers needed a concise way to say "this type represents data — please generate the standard, correct value-comparison plumbing for me" without writing it by hand every time, and a clean way to produce a modified copy of an immutable value without a wall of "copy constructor" boilerplate either.

The Solution

Records. The exact same Point above, as a record:

public record Point(int X, int Y);

One line. Value-based equality, a readable ToString, and with-expression support are all included automatically.

Big Picture

How It Works

public record Point(int X, int Y);

var p1 = new Point(3, 4);
var p2 = new Point(3, 4);

Console.WriteLine(p1 == p2);       // True — same X and Y
Console.WriteLine(p1.Equals(p2));  // True
Console.WriteLine(p1);             // "Point { X = 3, Y = 4 }" — readable, no override needed

var p3 = p1 with { Y = 10 }; // a NEW Point(3, 10) — p1 is untouched

Console.WriteLine(p1); // still "Point { X = 3, Y = 4 }"
Console.WriteLine(p3); // "Point { X = 3, Y = 10 }"

Simple Example

// record class — reference type, ideal for most data models
public record Money(decimal Amount, string Currency);

// record struct — value type, ideal for small, frequently-copied values
public readonly record struct Coordinate(double Latitude, double Longitude);

var price = new Money(19.99m, "USD");
var discounted = price with { Amount = 14.99m };

Console.WriteLine(price);      // Money { Amount = 19.99, Currency = USD }
Console.WriteLine(discounted); // Money { Amount = 14.99, Currency = USD }
Console.WriteLine(price == discounted); // False — different Amount

var here = new Coordinate(51.5074, -0.1278);
var there = new Coordinate(51.5074, -0.1278);
Console.WriteLine(here == there); // True — record structs get value equality too

Meaning: Money and Coordinate both get equality-by-value, readable printing, and with-based copying — Money as a reference type (a normal object on the heap), Coordinate as a value type (copied by value, like any struct), with the same generated members either way.

Real-World Example

Auditing is a natural home for records: you want an immutable snapshot of "what the order looked like at this exact moment," and you want to compare two snapshots to see if anything actually changed.

public record OrderSnapshot(
    int OrderId,
    string Status,
    decimal Total,
    DateTime CapturedAt);

public class AuditLog
{
    private readonly List<OrderSnapshot> _history = new();

    public void Capture(OrderSnapshot snapshot) => _history.Add(snapshot);

    public bool HasChangedSince(OrderSnapshot current, OrderSnapshot previous) =>
        current with { CapturedAt = default } != previous with { CapturedAt = default };
        // ignore the timestamp when comparing — we only care whether the DATA changed
}

// ─── Usage ───
var snapshot1 = new OrderSnapshot(5001, "Pending", 89.99m, DateTime.UtcNow);
audit.Capture(snapshot1);

// Later, the order ships — capture a new snapshot instead of mutating the old one
var snapshot2 = snapshot1 with { Status = "Shipped", CapturedAt = DateTime.UtcNow };
audit.Capture(snapshot2);

// snapshot1 is completely untouched — it's still "Pending", exactly as it was recorded

Because with never mutates the original, snapshot1 remains a trustworthy historical record even after snapshot2 is created from it — which is exactly the guarantee an audit trail needs. And because equality compares values, you can directly ask "did anything meaningful change between these two snapshots?" without writing a manual field-by-field comparison.

Analogy

Under the Hood

public class Point : IEquatable<Point>
{
    public int X { get; init; }
    public int Y { get; init; }

    public Point(int x, int y) { X = x; Y = y; }

    public override bool Equals(object? obj) => Equals(obj as Point);
    public bool Equals(Point? other) =>
        other is not null && X == other.X && Y == other.Y;
    public override int GetHashCode() => HashCode.Combine(X, Y);
    public override string ToString() => $"Point {{ X = {X}, Y = {Y} }}";

    public void Deconstruct(out int x, out int y) { x = X; y = Y; }

    // a hidden "copy constructor" and a Clone-style method back the `with` expression
    protected Point(Point original) { X = original.X; Y = original.Y; }
}

Common Confusion

1. "Records are immutable" — not automatically, but strongly encouraged to be

A positional record's generated properties use init accessors, which means they can only be set during object initialization — not reassigned afterward. But you can write a record with regular mutable { get; set; } properties if you choose to. Records don't force immutability; they default you toward it, because init plus with is by far the most common and idiomatic way to use them.

2. record vs record class — identical, just spelled differently

record Point(...) and record class Point(...) mean exactly the same thing — class is implied by default. The explicit form exists mainly to make the intent unambiguous next to record struct, especially in code where both appear.

3. with does a shallow copy, not a deep one

If a record holds a reference to a mutable object (say, a List<string>), with copies the reference to that list, not a brand-new list. Mutating the list through the copy would also affect the original, because both records point at the same underlying list object. For genuinely deep immutability, use immutable collection types (like ImmutableList<T>) for any collection-typed properties.

Common Mistakes

Mistake 1 — Using a record for a type that genuinely needs identity and mutable state

Modeling a long-lived, stateful service or entity (say, a live database connection wrapper, or a domain entity tracked by a unique ID where two objects with the same field values should still be treated as separate) as a record, and getting surprised by value-based equality.

Use a class for anything where "is this the same object/entity" matters more than "does this hold the same data" — records are for data, not identity.

Mistake 2 — Assuming with deep-copies everything

public record Cart(List<string> Items);

var cart1 = new Cart(new List<string> { "Book" });
var cart2 = cart1 with { }; // "copy" — but Items is the SAME list reference

cart2.Items.Add("Pen");
Console.WriteLine(cart1.Items.Count); // 2 — cart1 was affected too!

For collection-typed properties you want truly independent, either copy the collection explicitly in the with expression (cart1 with { Items = new List<string>(cart1.Items) }) or use an immutable collection type.

Mistake 3 — Forgetting record structs still copy by value everywhere, like any struct

A record struct gets all the record ergonomics (value equality, ToString, with) but it's still a value type — passing it to a method, or assigning it to another variable, copies the whole thing. For a small type like a coordinate that's fine and often desirable; for a record with many fields, that copying can add measurable overhead. Choose record (reference type) for larger data, record struct for small, frequently-copied values.

When Should I Use It?

• Use a record for DTOs, API request/response models, snapshots, event payloads, and any type that primarily represents data you compare and pass around, not behavior.
• Use a record struct when the data is small and copied frequently (coordinates, money-with-currency, ranges) and you want value-type performance characteristics.
• Stick with a plain class when identity matters (two instances with the same data should still be "different things"), or when the type is mostly about behavior with mutable internal state.

Mental Model

Key Takeaway

Check Your Understanding

You've seen how records give you value equality and non-destructive copying essentially for free. Let's check your understanding.

You now understand why records exist and when value-based equality is exactly the right tool for the job.

dotnetmadeeasy.com — Learn C# and .NET, the right way.