Dev.to
🛑 Why Records Are the Better Choice for Clean, Modern, and Principle-Driven .NET Development
If you've been writing C# for more than a few years, you've written thousands of DTOs. Request models, response models, event payloads, integration contracts, the connective tissue of every distributed system. And if you're like most of us, you've written nearly all of them as classes with { get; set; } properties, because that's what we've done since .NET Framework 2.0.
Here's the uncomfortable truth: a mutable class is the wrong data structure for a DTO, and it has been since C# 9 gave us a better one. Not "stylistically wrong." Wrong in ways that show up as production incidents, duplicate payments, corrupted audit trails, and race conditions in async pipelines.
This article makes the case from first principles, with examples drawn from banking and fintech systems, payment processing, reconciliation, maker-checker workflows, because that's where the cost of getting this wrong is measured in money, not just bugs. Whether you're a junior engineer writing your first API contract or a solutions architect reviewing a payment platform design, the goal is the same: understand why records exist, not just how to type them.
🚚 What Are DTOs in Practice?
Imagine you're building a ride-sharing app like Uber or Bolt. When the frontend requests a list of nearby drivers, you return a DriverDto:
{
"id": 142,
"name": "Linda",
"rating": 4.9
}
In C#, you might write:
public class DriverDto
{
public int Id { get; set; }
public string Name { get; set; }
public double Rating { get; set; }
}
This works, but it's bloated, mutable, and doesn't reflect the true intent of a DTO: a simple, structured data carrier.
Now zoom out from ride-sharing to where DTOs really earn their keep: system boundaries in enterprise software. In a payments platform, DTOs are everywhere:
The inbound webhook payload from a card scheme or a partner bank notifying you of a settlement.
The API response your mobile app receives when a customer checks their balance.
The Kafka event published when a transfer moves from PENDING to SETTLED.
The reconciliation record you compare against the processor's end-of-day file.
Every one of these is a contract. It represents a fact — "this transaction, with this reference, for this amount, at this time" — communicated across a boundary. And here is the key insight the whole article rests on:
A DTO is a snapshot of data at a point in time. Snapshots don't change. So why are we modeling them with a type whose defining feature is that it changes?
A junior engineer can think of it this way: a DTO is like a printed bank statement. Once it's printed, nobody should be able to grab a pen and change the numbers. If the numbers need to be different, you print a new statement. Classes with set; accessors hand everyone a pen. Records take the pen away.
🔍 The Real Problems with Class-Based DTOs
Let's be precise about what's wrong, because "bloated" alone wouldn't justify changing a decade of habit. There are four concrete failures.
1. Mutability is a liability at boundaries
Consider a simplified inbound payment notification in a fintech platform:
public class PaymentNotificationDto
{
public string TransactionRef { get; set; }
public decimal Amount { get; set; }
public string Currency { get; set; }
public string SenderAccount { get; set; }
public DateTime ReceivedAt { get; set; }
}
This object will pass through validation, enrichment, fraud screening, ledger posting, and notification services, often across async hops and sometimes across threads. Any one of those stages can silently mutate it. A well-meaning teammate writes:
// "Normalizing" inside the fraud check — seems harmless
notification.Amount = Math.Round(notification.Amount, 2);
Now the amount that reaches your ledger is not the amount you received from the partner bank. When reconciliation runs at end of day and finds a ₦0.005 discrepancy across two million transactions, you'll spend a very unpleasant week finding this line. The compiler could have prevented it. With a mutable class, it can't.
In banking, this isn't hypothetical. The single most valuable property of financial data in flight is that it cannot be tampered with between the boundary and the ledger. Mutability is an open invitation to tampering, usually accidental, occasionally worse.
2. Reference equality is the wrong equality
Two DTOs carrying identical data are, for every practical purpose, the same fact. But classes compare by reference:
var a = new PaymentNotificationDto { TransactionRef = "TXN-8842", Amount = 50_000m, Currency = "NGN" };
var b = new PaymentNotificationDto { TransactionRef = "TXN-8842", Amount = 50_000m, Currency = "NGN" };
Console.WriteLine(a == b); // false
Console.WriteLine(a.Equals(b)); // false
Why does this matter? Idempotency the backbone of every payment system. Partner banks retry webhooks. Kafka delivers at-least-once. Mobile apps resubmit on timeout. Your system must recognize "I've seen this exact fact before" cheaply and correctly. With classes, you either hand-write Equals/GetHashCode (and forget to update them when a property is added — a classic source of subtle dedup bugs), pull in a library, or compare serialized JSON like a barbarian.
3. The boilerplate hides the contract
A class-based DTO with proper equality, immutability via constructor injection, and a useful ToString for structured logging is 40–60 lines. The contract — the thing an engineer actually needs to read, is 5 lines. The other 90% is ceremony that must be maintained, reviewed, and kept in sync. In an enterprise codebase with 400 DTOs, that's tens of thousands of lines of pure noise, every line a place for a bug to hide.
4. Nothing communicates intent
public class PaymentNotificationDto tells a reader nothing about how the type is meant to be used. Is it safe to cache? Safe to share across threads? Is mutation expected? The type system is silent, so the answer lives in tribal knowledge and code review vigilance — the two most expensive and least reliable enforcement mechanisms in software.
✨ Enter Records: The Type That Says What It Means
The same DTO as a record:
public record PaymentNotificationDto(
string TransactionRef,
decimal Amount,
string Currency,
string SenderAccount,
DateTime ReceivedAt);
Five lines. And the compiler generates, for free:
Init-only properties - the object is frozen after construction.
Value-based Equals and GetHashCode - two records with the same data are equal.
A readable ToString - PaymentNotificationDto { TransactionRef = TXN-8842, Amount = 50000, ... }, which is a quiet superpower for structured logging in Serilog.
Deconstruction - var (txnRef, amount, currency, _, _) = dto;
with expressions - non-destructive "mutation" that produces a new copy.
Our idempotency check now just works:
var a = new PaymentNotificationDto("TXN-8842", 50_000m, "NGN", "0123456789", timestamp);
var b = new PaymentNotificationDto("TXN-8842", 50_000m, "NGN", "0123456789", timestamp);
Console.WriteLine(a == b); // true — same fact, recognized as such
And the tampering bug from earlier? It's now a compile-time error:
notification.Amount = Math.Round(notification.Amount, 2);
// CS8852: Init-only property can only be assigned in an object initializer
The pen has been taken away. If a stage in your pipeline genuinely needs a normalized amount, it must be explicit about creating a new fact:
var normalized = notification with { Amount = Math.Round(notification.Amount, 2) };
Notice what happened to the semantics: mutation-in-place (invisible, untraceable) became transformation (visible, reviewable, loggable). In a regulated environment where auditors ask "show me every place this value could have changed," that difference is not cosmetic.
🏦 Records in the Wild: Enterprise Fintech Scenarios
Abstract arguments are cheap. Let's walk through four scenarios that recur in nearly every banking or fintech platform and see how records change the engineering.
Scenario 1: Idempotent webhook ingestion
Your platform receives settlement notifications from multiple partner banks. Networks are unreliable; partners retry aggressively. A duplicate posting means a customer gets credited twice — a direct financial loss.
public record SettlementNotification(
string ProviderRef,
string SessionId,
decimal Amount,
string Currency,
string BeneficiaryAccount,
DateTimeOffset SettledAt);
Because records give you correct GetHashCode for free, deduplication within a processing window becomes trivially correct:
// In-memory dedup for a processing window — HashSet just works
private readonly HashSet<SettlementNotification> _seenInWindow = new();
public async Task HandleAsync(SettlementNotification notification)
{
if (!_seenInWindow.Add(notification))
{
_logger.LogWarning("Duplicate settlement ignored: {Notification}", notification);
return; // structured log includes full payload via generated ToString
}
await _ledger.PostAsync(notification);
}
With a class, HashSet.Add would happily accept ten copies of the same notification, because each is a distinct reference. You'd need hand-rolled equality — and every hand-rolled GetHashCode is a future bug when someone adds NarrationText to the DTO and forgets to update the hash.
(In production you'd also have a durable idempotency store keyed on ProviderRef + SessionId — value equality complements that; it doesn't replace it. More on this in the limitations section.)
Scenario 2: Event-driven architecture on Kafka
In an event-driven core banking system, events are facts about the past: TransferInitiated, FraudCheckPassed, TransferSettled. The first rule of event sourcing is that facts are immutable — you never rewrite history; you append new events.
public record TransferInitiated(
Guid TransferId,
string SourceAccount,
string DestinationAccount,
decimal Amount,
string Currency,
DateTimeOffset InitiatedAt) : IDomainEvent;
When a consumer replays this event during recovery or a new projection is built from the event log, the guarantee that no handler anywhere could have mutated the event is what makes replay deterministic. With mutable class events, one handler that "fixes up" a field poisons every downstream consumer in the same process — and you'll only discover it when a rebuilt projection disagrees with the ledger.
Records make the architectural rule ("events are immutable facts") a compiler-enforced invariant instead of a wiki page nobody reads.
Scenario 3: Maker-checker workflows
Regulated back-office operations — bulk account onboarding, limit changes, manual reversals , follow maker-checker: one officer initiates, another approves. The state transition must be explicit and auditable.
public record ReversalRequest(
Guid RequestId,
string TransactionRef,
decimal Amount,
string MakerId,
string? CheckerId,
ApprovalStatus Status,
DateTimeOffset CreatedAt,
DateTimeOffset? DecidedAt);
The with expression models the transition beautifully — the original request is preserved untouched, and approval produces a new state:
public ReversalRequest Approve(ReversalRequest request, string checkerId) =>
request with
{
CheckerId = checkerId,
Status = ApprovalStatus.Approved,
DecidedAt = _clock.UtcNow
};
For audit purposes you can log both objects — before and after — and the generated ToString gives the auditor a complete, readable diff. Try producing that with a mutated class: the "before" state is gone; you overwrote it.
This is the event-sourcing mindset in miniature: state changes are new values, not edits. Records make that the path of least resistance.
Scenario 4: End-of-day reconciliation
Reconciliation is fundamentally a set-comparison problem: our view of the day's transactions versus their file. Value equality turns this from a bespoke matching engine into LINQ:
public record ReconRow(string Ref, decimal Amount, string Currency, DateOnly ValueDate);
var internalRows = await _ledger.GetRowsAsync(date);
var providerRows = ParseProviderFile(file);
var missingOnOurSide = providerRows.Except(internalRows); // they have it, we don't
var missingOnTheirSide = internalRows.Except(providerRows); // we have it, they don't
Except, Intersect, Distinct, GroupBy — the entire LINQ set-algebra toolkit works correctly by default on records because they carry proper value semantics. With classes you'd be writing IEqualityComparer<T> implementations, one per comparison, each a maintenance liability.
🧭 How Records Fulfill Software Engineering Principles
This is where the article stops being about syntax and starts being about design. Records aren't just terser — they align data contracts with the principles we already claim to follow.
Single Responsibility Principle (SRP)
A DTO has one job: carry data across a boundary. A mutable class quietly takes on a second job — being a workspace that pipeline stages scribble on. That second job is precisely what causes the tampering bugs above. Records structurally reject the second job. The type does one thing, and the compiler enforces it.
Junior-friendly analogy: a DTO should be an envelope, not a whiteboard. Records seal the envelope.
Open/Closed Principle (OCP)
"Open for extension, closed for modification" is usually discussed for behavior, but it applies to data too. The with expression is OCP for values: you extend an existing fact into a new one without modifying the original.
var enriched = notification with { Narration = ResolveNarration(notification) };
Every stage of an enrichment pipeline receives an input it cannot break for other consumers and emits a new output. Pipelines composed this way are trivially parallelizable and testable, because no stage has side effects on shared state.
Liskov Substitution Principle (LSP)
Records support inheritance (public record ChildDto : ParentDto) and — unlike hand-written class equality - the generated equality is hierarchy-aware. A record's Equals checks the runtime type via a synthesized EqualityContract, so a ParentDto and a ChildDto with identical property values are correctly not equal. Hand-rolled class equality gets this wrong constantly (the classic symmetric-equality bug in Equals overrides). Records give you LSP-safe equality out of the box.
That said — and this is a genuine senior-level guideline — prefer flat records and composition for DTOs. Deep DTO inheritance hierarchies are usually a design smell regardless of the type mechanism. Records just fail more safely when you do it.
Interface Segregation Principle (ISP)
Positional records make fat contracts visible. A 22-property class DTO looks like any other file. A 22-parameter positional record looks alarming in the constructor — and that discomfort is a feature. It nudges you toward segregating the contract:
public record BeneficiaryDetails(string Account, string BankCode, string Name);
public record TransferAmount(decimal Value, string Currency);
public record TransferRequest(Guid Id, TransferAmount Amount, BeneficiaryDetails Beneficiary);
Nested records compose value equality automatically: two TransferRequests are equal if their nested records are equal, all the way down. You get well-factored, comparable aggregate contracts with zero extra code.
Dependency Inversion Principle (DIP)
DIP is about depending on stable abstractions. In distributed systems, the most stable abstraction between two services is an immutable contract. A record shared in a contracts package is a promise: "this shape, these semantics, no hidden mutation." Consumers can cache it, memoize on it, and key dictionaries by it, all safely — because the contract's stability is enforced, not merely documented.
YAGNI (You Aren't Gonna Need It)
Every set; accessor on a DTO is speculative capability: "someone might need to mutate this someday." YAGNI says: don't build it until they do. Records are YAGNI applied to data — you ship exactly the capability a data carrier needs (construction, reading, comparison, copying) and nothing more. When a genuine mutation need appears, with handles it explicitly, and the code review sees it.
DRY (Don't Repeat Yourself)
The 40 lines of Equals/GetHashCode/ToString/copy-constructor boilerplate per DTO is repetition at industrial scale — the same pattern re-implemented hundreds of times, each an opportunity to diverge. Records move that pattern into the compiler, where it's written once and correct forever. This is DRY in its strongest form: not just avoiding copy-paste, but eliminating the category of code entirely.
Principle of Least Astonishment
a == b returning false for two identical payment notifications is astonishing to every engineer who hasn't been burned by it yet. Records make equality behave the way domain intuition expects for data: same values, same fact, equal. Fewer surprises, fewer 2 a.m. debugging sessions.
Fail Fast
Positional records force construction through a single point — the primary constructor — which is exactly where validation belongs:
public record TransferAmount
{
public decimal Value { get; init; }
public string Currency { get; init; }
public TransferAmount(decimal value, string currency)
{
if (value <= 0)
throw new ArgumentOutOfRangeException(nameof(value), "Amount must be positive.");
if (currency is not { Length: 3 })
throw new ArgumentException("ISO 4217 code required", nameof(currency));
Value = value;
Currency = currency;
}
}
Because the object can't be mutated afterward, valid at construction means valid forever. Compare that with a mutable class, where validity is a moving target you must re-verify at every use site.
DDD: Records are Value Objects
If you practice Domain-Driven Design, you've been hand-writing value objects — Money, AccountNumber, Bvn, IdempotencyKey — for years, with all the equality ceremony that entails. Records are the value-object pattern promoted to a language feature. Eric Evans's definition — "an object that describes some characteristic... with no conceptual identity, compared by value" — is a description of a C# record. This is the deepest reason records feel right for DTOs: DTOs were always value objects; we just lacked the language support to say so.
CQS/CQRS alignment
In a CQRS system (MediatR users, this is you), queries return read models and commands carry intent. Both are one-way messages — facts flowing in one direction. Immutable records match that semantics exactly: a GetAccountBalanceQuery or its AccountBalanceResult has no business being mutated after creation. Making commands, queries, and results records turns your MediatR pipeline into a chain of pure-ish transformations, which is dramatically easier to reason about, test, and parallelize.
⚡ Performance: What Records Actually Buy You (and What They Don't)
Senior engineers should be suspicious of performance claims, so let's be honest and specific.
Where records genuinely help
1. Correct, fast equality without reflection. The compiler-generated Equals and GetHashCode are direct field comparisons - no reflection, no boxing of the comparands, no serialization tricks. Teams that fall back to comparing DTOs via JsonSerializer.Serialize(a) == JsonSerializer.Serialize(b) (it happens more than anyone admits) are paying two full serializations plus a string comparison per check. Record equality is orders of magnitude cheaper and allocation-free for the comparison itself.
2. Dictionary and set performance by construction. Because GetHashCode is generated correctly, records are first-class citizens as keys in Dictionary<TKey,TValue>, HashSet<T>, ConcurrentDictionary, and memoization caches. In a fraud-screening service that caches risk scores per (Account, Channel, AmountBand) tuple, a record key gives you O(1) lookups with hash distribution you didn't have to think about.
3. Lock-free sharing under concurrency. This is the big one for throughput. An immutable object can be read by any number of threads with zero synchronization. In a high-TPS inbound payments pipeline — parallel Kafka consumers, Parallel.ForEachAsync enrichment, fan-out to multiple downstream handlers — mutable shared DTOs force you into locks, defensive copies, or prayer. Immutable records eliminate the entire category: no locks, no torn reads, no defensive Clone() calls scattered through the code. The performance win isn't the object itself; it's all the synchronization machinery you get to delete.
4. Defensive copying disappears. Mature codebases with mutable DTOs accrue defensive copies — "clone it before passing it to that service, just in case." Each copy is allocation and CPU spent to compensate for mutability. With records, passing a reference is safe sharing. The copies you no longer make are a real, measurable saving in hot paths.
5. record struct for the truly hot path. Since C# 10, readonly record struct gives you value semantics with stack allocation — zero GC pressure for small, short-lived carriers:
public readonly record struct FxRate(string Pair, decimal Rate, DateTimeOffset AsOf);
For a pricing engine evaluating thousands of FX quotes per second, this avoids heap allocation entirely for the quote objects, which shows up directly in Gen0 collection frequency. The guidance mirrors regular structs: keep them small (≈16 bytes as a rule of thumb, pragmatically a few fields), and prefer readonly record struct to prevent the defensive-copy costs of non-readonly structs.
Where you must be honest about costs
with expressions allocate. Every with produces a full new instance. In a pipeline that transforms a record five times, that's five allocations where a mutable class would have zero. For typical API/webhook DTOs (short-lived, Gen0-collected) this is noise — Gen0 collection of small objects is extremely cheap, and correctness wins. But if profiling shows a genuinely hot loop churning large records through repeated with copies, that's a legitimate case for a builder or a mutable working type inside the tight scope, converting to a record at the boundary.
Record equality is O(n) in fields. Comparing two 30-property records field-by-field costs more than a reference check. If you're doing millions of comparisons and references would suffice (i.e., you know it's the same instance), ReferenceEquals still exists. This is rarely a real problem, but it's worth knowing the shape of the cost.
The performance argument, summarized for an architect: records are not "faster objects." They are objects whose guarantees let you delete slower code — locks, defensive copies, hand-rolled comparers, serialization-based equality — and whose struct variant removes allocation where it matters. The system gets faster because the design gets simpler.
⚠️ Limitations and Sharp Edges (Read This Before You Migrate)
Records are the right default for DTOs. They are not the right choice for everything, and they have gotchas that will bite teams who treat them as "classes but shorter."
1. Do not use records for EF Core entities
This is the most common misapplication. ORM entities are the opposite of DTOs: they have identity (primary key), a lifecycle, and mutation is the mechanism — EF Core's change tracker works by detecting property modifications on tracked instances. Records fight this at every turn: value equality confuses identity-based logic and DbSet semantics, with copies break change tracking (the copy is a different, untracked object), and lazy-loading proxies don't play well with record equality. Keep entities as classes. Map them to record DTOs at the query boundary — which is exactly the layering clean architecture prescribes anyway.
2. Collection properties break value equality
The gotcha that surprises everyone:
public record BatchDto(string BatchId, List<string> TransactionRefs);
var a = new BatchDto("B-01", new List<string> { "T1", "T2" });
var b = new BatchDto("B-01", new List<string> { "T1", "T2" });
Console.WriteLine(a == b); // FALSE — List<T> compares by reference
Generated equality compares each member with its own Equals — and List<T> equality is reference equality. So a record containing a collection silently loses the value-equality guarantee you adopted records for. In a reconciliation or dedup context, this is a correctness bug, not a style issue. Mitigations: use ImmutableArray<T>/ImmutableList<T> with a custom Equals override for that member, model the data to avoid collections in equality-sensitive records, or explicitly override Equals/GetHashCode with sequence comparison. Whatever you choose, make it a documented team convention.
3. with is a shallow copy
with copies field values. If a field is a reference to a mutable object (that List<string> again), the original and the copy share it:
var copy = original with { BatchId = "B-02" };
copy.TransactionRefs.Add("T3"); // also visible through original — same list!
The record's own scalar fields are safe; nested mutable state is not. The clean fix is to make records immutable all the way down — nested records, immutable collections — so shallow copy and deep copy become indistinguishable. Half-immutable records are arguably more dangerous than honest mutable classes, because they look safe.
4. Serializer and framework friction
Modern System.Text.Json and current Newtonsoft.Json handle records and constructor binding well, but the wider ecosystem varies: some mappers, legacy binders, and reflection-based tools still assume a parameterless constructor and settable properties. AutoMapper needs ForCtorParam configuration for positional records. If a tool forces you to add set; accessors back onto a record to make it work, you've kept the syntax and lost the point — reconsider the tool or use init with object-initializer-style records.
5. Inheritance equality can surprise you
Record inheritance is safer than hand-rolled class equality, but the EqualityContract behavior — a base-typed variable holding a derived instance never equals a base instance with identical values — surprises engineers who expected structural comparison across the hierarchy. Combined with the general smell of deep DTO hierarchies, the pragmatic rule stands: flat records, composition over inheritance.
6. Wide records get unwieldy
A positional record with 20+ parameters is miserable to construct and brittle to reorder (positional args have no names at most call sites). For wide contracts, use nominal records with init properties and object initializers, or — better — apply ISP and decompose the contract, as shown earlier.
7. Migration is not free in a brownfield
Introducing records into a 7-year-old codebase means auditing every place that mutates DTOs today. Some of those mutations are bugs you'll be glad to find; others are load-bearing hacks. Migrate boundary-first: new contracts, new events, and new endpoints as records; refactor legacy DTOs opportunistically when you're already touching their pipelines. A big-bang conversion of 400 DTOs is a two-week PR nobody can review.
🧰 When a Class Is Still the Right Answer
To be a trustworthy advocate for records, you have to know their boundary. Reach for a class when the type:
Has identity and a lifecycle — ORM entities, aggregate roots, anything where "same object over time despite changing state" is the point.
Is fundamentally behavioral — services, handlers, strategies. Records model data; classes model actors.
Requires managed mutable state — builders, accumulators, caches, connection pools.
Must integrate with mutation-assuming frameworks you can't replace — some legacy binders, certain UI frameworks, older SOAP/WCF tooling.
Is a large object copied in a proven hot loop — where with-copy allocation genuinely dominates a profile (measure first; it almost never does).
The mental model to give a junior engineer:
Records are for facts. Classes are for actors. A payment notification is a fact. The service that processes it is an actor. Facts don't change; actors do things.
📋 A Practical Decision Guide
Type of thing
Use
API request/response contracts
record
Kafka / message-bus events
record
MediatR commands, queries, results
record
DDD value objects (Money, AccountNumber)
record (with constructor validation)
Small hot-path carriers (FX ticks, coordinates)
readonly record struct
EF Core entities / aggregate roots
class
Services, handlers, middleware
class
Builders, accumulators, mutable caches
class
Configuration bound at startup (IOptions)
record with init properties
🏁 Conclusion: This Was Never About Syntax
The record keyword saves you 40 lines per DTO, and that alone would justify using it. But the real argument is architectural:
Mutable class DTOs make correctness a matter of discipline. Records make it a matter of compilation.
In consumer software, the cost of a mutated DTO is a weird bug. In banking and fintech, it's a duplicated settlement, a reconciliation break, a corrupted audit trail — failures with monetary and regulatory consequences. Every principle we invoked — SRP, OCP, YAGNI, DRY, fail-fast, least astonishment, DDD value semantics — converges on the same conclusion: data crossing a boundary should be an immutable, value-comparable fact, and C# now has a first-class type for exactly that.
So the next time you type public class SomethingDto { get; set; }, stop. Ask yourself: is this a fact or an actor? If it's a fact — and a DTO always is — reach for the record, take the pen away, and let the compiler enforce what your code reviews have been trying to enforce for years.
Your reconciliation team will thank you. Eventually. Silently. By never having to call you at 2 a.m. about a ₦0.005 discrepancy.
If you found this useful, drop a comment with the worst mutable-DTO bug you've debugged in production - the war stories are half the education.
LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Dev.To
4 hours ago
