C# Record Usage: Syntax, Equality, and Tradeoffs
Understand C# records: declaration syntax, value equality, with-expressions, inheritance, and when records fit better than classes or structs.

Records in C# are a concise way to define data-carrying types. They were introduced in C# 9, and the examples in this article use the reference-type record; C# 10 also supports record struct for value-type records. The sections below cover declaration syntax, equality, with expressions, inheritance, and tradeoffs.
What a Record Changes Compared to a Class
A record is a reference type by default, like a class, but the compiler generates additional members that change how instances behave. The most visible difference is value equality: two record instances are equal when their property values match, not when they reference the same object. The compiler also generates equality members, a protected copy constructor, and, for positional syntax, a Deconstruct method.
This matters because records remove a lot of boilerplate you would otherwise write by hand for data-carrying types. You get equality, hashing, and string representation from a single declaration.
Declaring Records With Positional Syntax
The positional form is the most common way to declare a record:
public record OrderItem(string ProductCode, int Quantity, decimal UnitPrice);The compiler creates init-only properties for each parameter. That means you can set the values during construction, but you cannot reassign them afterward:
var item = new OrderItem("A-100", 2, 19.99m);
// item.Quantity = 3; // compile error: init-only propertyIf you need mutable properties, you can declare them explicitly with set accessors, but that works against the immutable design that records are meant to provide.
How Value Equality Works
For a record, Equals compares each public property by value, not by reference. The compiler generates Equals, GetHashCode, and the == and != operators. Two separately constructed instances with the same values compare as equal:
var first = new OrderItem("A-100", 2, 19.99m);
var second = new OrderItem("A-100", 2, 19.99m);
Console.WriteLine(first == second); // True
Console.WriteLine(first.Equals(second)); // TrueThe generated GetHashCode is based on the same property values, so records work correctly in hash-based collections like Dictionary and HashSet. If you override equality manually, you must keep Equals and GetHashCode consistent, which the compiler-generated version already does for you.
Using with-Expressions for Non-Destructive Mutation
Because record properties are init-only, you cannot mutate an instance in place. The with expression creates a copy with one or more properties changed:
var original = new OrderItem("A-100", 2, 19.99m);
var updated = original with { Quantity = 5 };
Console.WriteLine(original.Quantity); // 2
Console.WriteLine(updated.Quantity); // 5The original instance stays unchanged. The compiler uses the generated copy constructor to clone the record, then applies the property changes. This is the intended way to "update" a record, and it keeps the data flow explicit.
Records vs Classes vs Structs
The choice depends on what the type represents. A record is a good fit when the type is primarily a data carrier and you want value semantics without manual equality code. A class is better when the type has identity, mutable state, or behavior that depends on being the same instance. A struct is better for small, frequently allocated value types where avoiding heap allocation matters.
| Criterion | Record | Class | Struct |
|---|---|---|---|
| Equality | Value-based | Reference-based | Value-based |
| Mutability | Init-only by default | Fully mutable | Mutable if declared so |
| Allocation | Heap | Heap | Stack or inline |
| Typical use | DTOs, messages, results | Services, entities with identity | Small numeric-like values |
The table refers to the default reference-type record. C# 10 also supports record struct, which gives a value type record-like equality and generated members.
A common mistake is using records for entity types that have identity, such as a customer whose equality should be based on an ID. If two customer objects with the same ID but different names should be equal, a record with value equality will not behave the way you want.
Record Inheritance and Hierarchies
Reference-type record classes support inheritance, and the equality behavior extends to derived types. A derived record inherits the equality members and adds its own properties to the comparison:
public record OrderItem(string ProductCode, int Quantity, decimal UnitPrice);
public record DiscountedOrderItem(
string ProductCode,
int Quantity,
decimal UnitPrice,
decimal DiscountPercent)
: OrderItem(ProductCode, Quantity, UnitPrice);The positional declaration of the derived record passes the base parameters to the base constructor. Equality between a base and derived instance returns false when the types differ, which is the expected behavior for value equality.
Runtime and Performance Considerations
Records are reference types, so they allocate on the heap. The generated equality code iterates over properties, which is slower than a simple reference comparison. For large collections of records, repeated equality checks or hashing can become a measurable cost. If you are comparing millions of instances, a struct with manually implemented equality may be faster because it avoids the allocation and uses a more compact layout.
The with expression also allocates a new instance on every call. That is usually fine for occasional updates, but in a hot loop that clones records frequently, the allocation pressure can be significant.
Serialization and Framework Compatibility
Records serialize cleanly with System.Text.Json because they expose public properties with getters. Deserialization works with the init-only properties through the parameterized constructor that the positional syntax generates. Most modern frameworks handle records without extra configuration.
One limitation: records rely on generated members, so any code that reflects over the type and expects a parameterless constructor will not find one on a positional record. If a library requires a parameterless constructor, you may need to declare the record with explicit properties and a default constructor instead.
Try matching browser tools
All toolsSmall utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related C# guides
All C# guidesC# Dispose vs Destructor: Key Differences Explained
c# dispose vs destructor: Understand the difference between Dispose and destructors in C#, when each runs, and how to manage unmanaged resources correctly.
C# Variable Declaration: Syntax and Practical Usage
Learn how to declare variables in C# with explicit types, var, and nullable annotations, and understand how defaults, scope, and readability affect your choices.
C# Primary Constructors for Classes: Syntax and Usage
Learn how to use C# primary constructors for classes: syntax, initialization, dependency injection, and limitations with practical examples.
C# IComparer: Custom Sorting with IComparer<T>
Learn how to implement IComparer<T> in C# to define custom sort order for arrays and lists, handle nulls, and avoid common performance pitfalls.
More in C#
All C# guidesThe guides filed next to this one in C#, in library order.