Records

What it is and why it exists

A record type is a class or struct whose compiler-generated contract treats data as the type’s defining feature. Two separately allocated record objects can compare equal when their corresponding members compare equal. A plain class instead uses reference identity unless you implement another equality contract.

The record modifier asks the compiler to synthesize value equality, matching hash-code behavior, a readable ToString(), and support for with expressions. A positional declaration also supplies a primary constructor, public properties, and Deconstruct(). These members remove repetitive code, but they do not decide which data belongs in the type.

Records fit data transfer objects, messages, coordinates, money-like values, and snapshots when content determines identity. They are a poor default for an entity whose identity survives changing attributes. If two customers remain the same customer after a name change, an ID-based class contract may say that more clearly than equality over every record member.

record and record class declare a reference type. record struct and readonly record struct declare a value type . The forms share compiler-generated record features, but assignment, nullability, inheritance, and default-value behavior still follow their underlying class or struct semantics.

A record does not promise immutability. Positional record-class properties have init accessors, yet the record can declare settable properties and can contain mutable objects. Positional properties of a non-readonly record struct are read-write by default.

How it works

Positional declarations and generated members

public record OrderLine(string Sku, int Quantity); declares a record class. Its two positional parameters become public init-only properties, constructor parameters, and outputs of a synthesized Deconstruct() method. They also participate in the compiler-generated equality and string representation.

A nominal record uses an ordinary body instead of positional parameters. It still gets the record equality, hash, display, and copy members, but it does not get a primary constructor or Deconstruct() merely because it is a record. Use this form when property names, defaults, accessors, or construction rules need more space.

An init accessor permits assignment during object construction and in a with initializer, then rejects ordinary assignment. This is shallow immutability. If an init-only property refers to a List<T>, callers can still mutate that list after construction.

The generated surface depends on the declaration:

Equality and hash codes

Compiler-generated record equality is structural equality over the record’s instance state. Each member uses its own equality contract. Strings compare by their contents, but arrays and common mutable list classes compare by reference unless another comparer or wrapper says otherwise.

Equal records produce equal hash codes during the same execution, which lets records serve as dictionary keys and set elements. The reverse is not guaranteed: unequal values can collide. More importantly, every value that participates in equality and hashing must remain stable while the record is stored in a hash-based collection.

Changing a settable property after insertion can change the generated hash code. The dictionary then looks in a different bucket and may fail to find the very object used as a key. init reduces this risk for top-level properties but does not stop a nested object from changing its own equality behavior.

Record-class inheritance adds a runtime-type check to equality. A base record instance and a derived record instance are not equal merely because their shared members match. This preserves symmetry: both baseValue.Equals(derivedValue) and the reverse must reach the same answer.

Copying with with

A with expression creates a copy and then assigns the members named in its initializer. For a record class, compiler-generated machinery creates a new object through copy semantics. For a record struct, the value is copied and the selected fields or properties are changed on that copy.

The default result is a shallow copy . Reference-valued members still point to the same nested instances unless the initializer replaces them. original with { Name = "new" } does not clone an array, list, dictionary, or object held by another member.

For a record-class hierarchy, the result preserves the operand’s runtime type. A variable statically typed as a base record can refer to a derived record; applying with produces another derived object. The initializer can name only members available through the receiver’s compile-time type.

Copying also matters for derived or cached values. A property initializer calculated from positional parameters runs for the original construction and its stored result is copied. If with later changes an input property, the stored calculation can become stale; compute dependent values on access or re-establish the invariant explicitly.

Choosing equality before syntax

The deciding question is which values make two instances interchangeable. If the answer is all stable member values, a record’s generated contract is useful. If equality depends on one database identity, normalization policy, sequence contents, or a domain-specific tolerance, do not accept generated equality without reviewing it.

Copying semantics come next. A record class copies a reference on ordinary assignment and creates a new outer object with with. A record struct copies its fields on ordinary assignment as well, so large or mutable structs can surprise callers even before a with expression appears.

Construction rules are separate. required can require a caller to initialize a member, but it does not validate ranges or cross-member relationships. Constructors, factories, and validating accessors still need tests for invalid values, and default(SomeRecordStruct) remains possible regardless of constructor checks.

Examples

These examples move from the generated positional surface to shallow copying, nested-member equality, and a record hierarchy. The local environment has no .NET SDK or C# compiler, so the blocks are marked unexecuted and no output is invented.

Seeing the positional surface

Two separately created order lines compare equal. Deconstruction follows positional order, while with creates a changed outer object and leaves the original untouched.

The generated constructor accepts the boundary values in the challenge because the declaration contains no validation. Equality is ordinal member equality here: the compiler does not trim the SKU, fold case, or infer that quantity must be positive.

sealed prevents a derived record from extending the equality domain. It is a useful choice for a small value with a closed meaning, though it does not make referenced members immutable.

Exposing a shallow copy

The with expression changes Version, but it copies the Tags reference. Mutating the list through either record is visible through both.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Collections.Generic;

ReleaseNotes original = new("1.0", ["preview"]);
ReleaseNotes published = original with { Version = "1.1" };

published.Tags.Add("stable");

Console.WriteLine(ReferenceEquals(original, published));
Console.WriteLine(ReferenceEquals(original.Tags, published.Tags));
Console.WriteLine(string.Join(", ", original.Tags));
Console.WriteLine(string.Join(", ", published.Tags));

public sealed record ReleaseNotes(
    string Version,
    List<string> Tags);

# not executed here: the .NET SDK and C# compilers are unavailable

An IReadOnlyList<string> property would limit mutation through that interface, but it would not copy the supplied object or guarantee an immutable implementation. Define who owns the collection and take a defensive or immutable snapshot when the record contract requires one.

Custom copy behavior can clone nested state for a record class, but a surprise deep copy is not automatically better. Specify which graph edges are copied; otherwise identity-sensitive objects, resources, and cycles make “clone everything” ambiguous.

Testing nested-member equality

Arrays use reference equality for their own Equals implementation. The first two keys share one array and compare equal; the third has the same elements in a different array and does not satisfy generated record equality.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Collections.Generic;

string[] sharedScopes = ["read", "write"];

CacheKey first = new("tenant-a", sharedScopes);
CacheKey sameReference = new("tenant-a", sharedScopes);
CacheKey sameContents = new("tenant-a", ["read", "write"]);

HashSet<CacheKey> keys = [first, sameReference, sameContents];

Console.WriteLine(first == sameReference);
Console.WriteLine(first == sameContents);
Console.WriteLine(keys.Count);

public sealed record CacheKey(
    string TenantId,
    string[] Scopes);

# not executed here: the .NET SDK and C# compilers are unavailable

Replacing the array with IReadOnlyList<string> does not change equality by itself. If sequence contents define the value, wrap them in a type with sequence equality or implement a complete equality-and-hash contract. A custom Equals without a matching GetHashCode is broken for hash collections.

For a cache key, include every isolation field such as tenant, locale, permissions, and normalization version. Record syntax cannot tell whether an omitted field is harmless or a cross-tenant data leak.

Combining inheritance and patterns

The hierarchy gives each message a concise data shape. Pattern matching can then classify the derived runtime type and validate its values at the consuming boundary.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;

PaymentMessage[] messages =
[
    new Authorized("P-17", 42m),
    new Declined("P-18", "insufficient-funds")
];

foreach (PaymentMessage message in messages)
    Console.WriteLine(Describe(message));

static string Describe(PaymentMessage message) => message switch
{
    Authorized { Amount: > 0m } paid => $"paid {paid.Id}: {paid.Amount}",
    Authorized => "invalid authorization",
    Declined { Reason.Length: > 0 } failed => $"declined {failed.Id}: {failed.Reason}",
    _ => "unknown payment message"
};

public abstract record PaymentMessage(string Id);
public sealed record Authorized(string Id, decimal Amount) : PaymentMessage(Id);
public sealed record Declined(string Id, string Reason) : PaymentMessage(Id);

# not executed here: the .NET SDK and C# compilers are unavailable

The base type makes the accepted family visible, but C# record hierarchies are not sealed unions. Another assembly can derive from an accessible unsealed base, so the final arm still needs a deliberate unknown-type policy.

Pattern matching consumes the record’s shape; it does not validate construction. If a negative amount must never exist anywhere, establish that invariant before the message enters the hierarchy rather than relying on every consumer to repeat the same arm.

Pitfalls

Calling every record immutable

Fix: review every field and property, including nested objects. Use readonly record struct when value-type mutation is unwanted, and snapshot caller-owned collections when content must remain fixed.

Assuming with is a deep copy

Fix: test ReferenceEquals for nested members whose ownership matters. Replace a member in the initializer, use an immutable representation, or define documented custom record-class copy behavior when a deeper copy is part of the contract.

Trusting collection contents in generated equality

Fix: decide whether collection identity, order-sensitive contents, or set-like contents define equality. Encode that choice in a wrapper or a custom equality comparer and verify that equal values always produce equal hash codes.

Mutating a hash key

Fix: make hash-key state stable for the key’s whole residence time. Prefer a small immutable key record assembled from normalized scalar values, and test lookup after every operation that might mutate nested state.

Forgetting the zeroed record struct

Fix: either make the zero value meaningful, validate before use, or choose a record class or explicit optional wrapper when “no value” must be distinct. Constructor validation alone cannot prohibit a struct’s default value.

Letting copied properties go stale

Fix: express dependent values as computed getters when calculation is cheap, or route updates through an operation that rebuilds and validates all dependent state. Add a test that changes each source member through with and reads every derived member.

Further reading

• Records - C# reference
• C# record types
• with expression - C# reference
• init keyword - C# reference