DEV Community: Odumosu Matthew

Why Records Are the Better Choice for Clean, Modern, and Principle-Driven .NET Development

Odumosu Matthew — Sat, 18 Jul 2026 10:48:20 +0000

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

🛑 Why Records Are the Better Choice for Clean, Modern, and Principle-Driven .NET Development

Odumosu Matthew — Sat, 18 Jul 2026 10:28:57 +0000

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.

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?

🔍 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);

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

✨ 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) };

🏦 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

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);
}

(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

public record TransferInitiated(
    Guid TransferId,
    string SourceAccount,
    string DestinationAccount,
    decimal Amount,
    string Currency,
    DateTimeOffset InitiatedAt) : IDomainEvent;

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
    };

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

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

Junior-friendly analogy: a DTO should be an envelope, not a whiteboard. Records seal the envelope.

Open/Closed Principle (OCP)

var enriched = notification with { Narration = ResolveNarration(notification) };

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.

Interface Segregation Principle (ISP)

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

Dependency Inversion Principle (DIP)

YAGNI (You Aren't Gonna Need It)

DRY (Don't Repeat Yourself)

Principle of Least Astonishment

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;
    }
}

DDD: Records are Value Objects

CQS/CQRS alignment

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

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

Where you must be honest about costs

⚠️ 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

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

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!

4. Serializer and framework friction

5. Inheritance equality can surprise you

6. Wide records get unwieldy

7. Migration is not free in a brownfield

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

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

The Missing Row: Auto-Provisioning Derived Records Without the Race Condition

Odumosu Matthew — Sat, 18 Jul 2026 10:00:37 +0000

Why some records should be created by your system, not your users, and how to do it safely in .NET.

A support ticket lands on your desk: "The Teams page is empty. I added a member, but no team shows up."

You check the API. It's behaving exactly as written:

  { "items": [], "totalCount": 0 }

Nothing is broken. And that's the problem. The system is faithfully returning nothing, because the row that the page reads from was never created. Somewhere in your design,

you assumed a human would create it first.

This article is about a small, recurring design decision that quietly causes empty dashboards, confused users, and "is this a bug?" tickets: who is responsible for creating
derived records the user, or the system? and how to let the system do it without introducing duplicate rows or race conditions.

The problem

Let's use a fictional product: a collaboration tool called Loop.

In Loop, the important entities are:

An Organization (a paying customer).
A Member (a person invited into an organization under a plan).
A Team a grouping that members belong to, keyed by (OrganizationId, PlanCode).

The admin dashboard lists Teams. Each team card shows a member count.

Here's the catch in the original design: creating a Member wrote a member row. Creating a Team was a separate, manual step an admin was expected to do first. If an

admin invited members without first creating the matching team, the dashboard showed nothing even though the members clearly existed.

From the user's point of view, they did everything right. From the system's point of view, a required row simply didn't exist.

Why it matters

The Team record isn't independent information. It is fully derivable from the first member invited under a plan. When one entity's existence is implied by another, forcing a
human to create it manually is a design smell. It leads to:

Empty states that look like outages. Users can't tell "no data" from "misconfigured."
Support load. Every skipped step becomes a ticket.
Silent data drift. Members exist with no grouping to roll them up.

The fix is to let the system provision the derived record at the moment it first becomes necessary the first write, instead of relying on a prerequisite step.

The naive solution (and its two traps)

The obvious move: when a member is created, create the team if it isn't there yet.

  public async Task AddMemberAsync(NewMember input, CancellationToken ct)
  {
      var member = Member.Create(input);
      await _members.AddAsync(member, ct);

      // Create the team if this is the first member on this plan.
      var exists = await _teams.AnyAsync(
          t => t.OrganizationId == input.OrganizationId
            && t.PlanCode == input.PlanCode, ct);

      if (!exists)
      {
          var team = new Team(input.OrganizationId, input.PlanCode);
          await _teams.AddAsync(team, ct);
      }

      await _unitOfWork.SaveChangesAsync(ct);
  }

This works in a demo. In production it has two traps.

Trap 1: the check-then-insert race

AnyAsync(...) and AddAsync(...) are not atomic. If two members are invited to the same new team at the same moment, both requests can observe exists == false, and both

insert a team. Now the dashboard shows two identical team cards, and every downstream count is split across them.

An application-level AnyAsync check can never close this window on its own. The only reliable guard is a unique constraint, so the database, the one component that sees
all writes, rejects the second insert.

  // EF Core model configuration
  modelBuilder.Entity<Team>()
      .HasIndex(t => new { t.OrganizationId, t.PlanCode })
      .IsUnique();

With the constraint in place, turn the "check" into a "try, and treat a uniqueness violation as success", because a violation means someone else already created exactly the

row you wanted:

  private async Task EnsureTeamExistsAsync(
      Guid organizationId, string planCode, CancellationToken ct)
  {
      var exists = await _teams.AnyAsync(
          t => t.OrganizationId == organizationId
            && t.PlanCode == planCode, ct);
      if (exists) return;

      _teams.Add(new Team(organizationId, planCode));

      try
      {
          await _unitOfWork.SaveChangesAsync(ct);
      }
      catch (DbUpdateException ex) when (IsUniqueViolation(ex))
      {
          // A concurrent request created the same team first.
          // That is the desired end state, so this is a no-op, not an error.
      }
  }

The application-level AnyAsync still earns its keep: it avoids a failed insert on the common path. The constraint is what makes the code correct under concurrency. You

want both, the check for efficiency, the constraint for truth.

###Trap 2: the normalization mismatch

The team and the member are joined on PlanCode. If one side stores "pro" and the other stores "pro " (trailing space) or "PRO", the join silently returns nothing.

You'll create a team and members, and the dashboard still shows a count of zero a bug that looks identical to the original one.

Normalize the key in exactly one place, and make both sides use it:

  public Team(Guid organizationId, string planCode)
  {
      OrganizationId = organizationId;
      // Trim once, here, so the stored key matches how members store it.
      PlanCode = planCode.Trim();
      Id = Guid.NewGuid();
  }

Whatever rule you choose, trim, lowercase, collapse, apply it on every path that reads or writes the key. A join is only as reliable as the normalization behind it.

The retroactive gap

Here's the part teams forget. This fix runs at write time. It fixes every member invited after you ship it.

It does nothing for data that already exists. Organizations that invited members before the change still have no team row. They will look broken until either:

someone invites one more member (the new code then provisions the missing team), or
you run a backfill for the existing data.

Don't skip the backfill and hope the write path heals everything. Write a one-time job that creates the missing rows from what's already there:

  -- Create the missing team for every distinct (org, plan) that has members
  -- but no team yet. Idempotent: safe to run more than once.
  INSERT INTO teams (id, organization_id, plan_code, created_at_utc)
  SELECT gen_random_uuid(), m.organization_id, TRIM(m.plan_code), now()
  FROM   members m
  LEFT JOIN teams t
    ON t.organization_id = m.organization_id
   AND t.plan_code = TRIM(m.plan_code)
  WHERE  t.id IS NULL
  GROUP BY m.organization_id, TRIM(m.plan_code);

A forward fix plus a backfill is one complete change, not two optional ones. Ship them together.

Best practices

Let the system create what it can derive. If record B's existence is implied by record A, don't make a human create B first.
Guard uniqueness at the database, not just in code. Application checks are an optimization; constraints are the guarantee.
Make "already exists" a success, not an exception. Idempotent provisioning should converge on the same state no matter how many callers race.
Normalize join keys once and everywhere. Most "the data is there but the count is zero" bugs are a normalization mismatch.
Pair every write-time fix with a backfill. The forward path won't repair history.

Common mistakes

Relying on AnyAsync / SELECT ... IF NOT EXISTS alone under concurrency.
Adding the unique index but not handling the violation — turning a race into a 500 for the second caller.
Backfilling but forgetting to normalize in the backfill query, so it re-inserts near-duplicates.
Provisioning the derived row in a separate transaction from the triggering write, so a partial failure leaves one without the other.

Lessons learned

An empty response is not always "no data." Sometimes it's "the row you're reading from was never anyone's job to create." The most durable fix is to move that responsibility

from the user to the system, and then make the system's version safe under concurrency and honest about history.

The interesting engineering isn't the get-or-create. It's everything around it: the constraint that makes it correct, the normalization that makes the join real, and the

backfill that makes it true for data that already exists.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Medium

Mastering the Senior Java/Spring Boot Engineer Interview

Odumosu Matthew — Thu, 19 Mar 2026 12:14:25 +0000

I've been on both sides of the interview table for over a decade. I've bombed interviews at companies I really wanted to join. I've also hired engineers who looked mediocre on paper but turned out to be the best technical decisions I ever made.

Here's what I've learned: Senior interviews aren't knowledge tests. They're thinking tests.

Anyone can memorize that HashMap has O(1) lookup. What interviewers actually want to know is whether you'll make good decisions when the documentation runs out and Stack Overflow doesn't have your exact problem.

This guide is different. I'm not going to list 50 questions with textbook answers. Instead, I'll show you how senior engineers think through problems, because that's what actually gets you hired.

The Uncomfortable Truth About Senior Interviews

Let me be blunt: if you have 10+ years of experience and you're still getting rejected, it's probably not your technical knowledge. It's one of these:

You're answering questions like a junior - giving definitions instead of demonstrating judgment
You're not showing trade-off thinking - every solution has costs, and you're not acknowledging them
You're not telling stories - your experience is your differentiator, but you're not using it
You're solving the wrong problem - you're answering what was asked, not what was meant

Let's fix all of these.

Part 1: Core Java - But Not The Way You Think

Every Java interview covers the basics. The difference is depth. Here's what separates a senior answer from a mid-level one.

The `equals()` and `hashCode()` Question

What they ask: "What happens if you override equals() but not hashCode()?"

Mid-level answer: "It breaks hash-based collections because equal objects might have different hash codes."

Senior answer:

"It violates the hashCode contract, which creates subtle bugs that are incredibly hard to track down in production.

Here's why this is dangerous: the bug won't show up in your unit tests. It'll show up three months later when someone adds your object to a HashSet in a completely different part of the codebase.

public class TradingAccount {
    private String accountId;
    private String owner;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        TradingAccount that = (TradingAccount) o;
        return Objects.equals(accountId, that.accountId);
    }

    // Intentionally missing hashCode — this is a bug
}

Now imagine this in a trading system:

Set<TradingAccount> processedAccounts = new HashSet<>();
TradingAccount account1 = loadFromDatabase(12345);
processedAccounts.add(account1);

// Later, different code path loads the same account
TradingAccount account2 = loadFromDatabase(12345);
if (!processedAccounts.contains(account2)) {
    // This executes! We process the same account twice.
    // In a trading system, this could mean duplicate orders.
    processAccount(account2);
}

The contains() check fails because HashSet first checks the bucket using hashCode(). Since we didn't override it, account1 and account2 have different hash codes (based on memory address), so they land in different buckets. The equals() method is never even called.

I've seen this exact bug cause duplicate transactions in a payment system. Took two weeks to find because it only happened under specific load conditions where the same entity was loaded through different code paths.

The fix isn't just adding hashCode() - it's establishing team conventions. We now require that any class overriding equals() must also have a test that verifies the hashCode contract."

See the difference? The senior answer:

Explains the mechanism (hash buckets)
Describes real consequences (duplicate transactions)
Shares a war story (the two-week debugging session)
Proposes prevention (team conventions and tests)

This is what interviewers want. They're not testing if you know Java. They're testing if you've been burned by Java and learned from it.

Memory Model and Concurrency

What they ask: "Explain the Java Memory Model and when you'd use volatile."

This question is a trap. Most candidates launch into a textbook explanation of happens-before relationships and CPU caches. That's fine, but it's not impressive.

Senior approach:

"The Java Memory Model defines how threads interact through memory, but honestly, the practical implications matter more than the theory.

Here's when I've actually needed volatile in production:

1. Status flags for graceful shutdown

public class OrderProcessor implements Runnable {
    private volatile boolean running = true;

    public void shutdown() {
        running = false;  // Visible to the processing thread immediately
    }

    @Override
    public void run() {
        while (running) {
            Order order = queue.poll(100, TimeUnit.MILLISECONDS);
            if (order != null) {
                process(order);
            }
        }
        // Cleanup resources
    }
}

Without volatile, the processing thread might cache running = true and never see the shutdown signal. I've seen services that couldn't shut down cleanly because of this - they'd hang during deployments.

2. Double-checked locking (though I avoid it now)

public class ExpensiveResourceHolder {
    private volatile ExpensiveResource instance;

    public ExpensiveResource getInstance() {
        if (instance == null) {
            synchronized (this) {
                if (instance == null) {
                    instance = new ExpensiveResource();
                }
            }
        }
        return instance;
    }
}

This pattern is technically correct with volatile, but I've stopped using it. It's too easy to get wrong, and the performance benefit over simple synchronization is negligible in most applications. I now use either:

Lazy holders for singletons
ConcurrentHashMap.computeIfAbsent() for cached values
Or just accept the synchronization cost

3. Publishing immutable objects

public class ConfigurationHolder {
    private volatile ImmutableConfiguration config;

    public void updateConfiguration(ImmutableConfiguration newConfig) {
        // Single atomic write, immediately visible to all readers
        this.config = newConfig;
    }

    public ImmutableConfiguration getConfiguration() {
        return config;  // No synchronization needed for reads
    }
}

This is probably my most common use case — when you have a reference that's written rarely but read constantly.

What I'd avoid:

Using volatile for compound operations:

private volatile int counter = 0;

public void increment() {
    counter++;  // NOT THREAD-SAFE! Read-modify-write is not atomic
}

This is a classic mistake. volatile guarantees visibility, not atomicity. You need AtomicInteger or synchronization here.

The broader point is: most concurrency problems are better solved by avoiding shared mutable state entirely. Immutable objects, message passing, and higher-level constructs like CompletableFuture are almost always better choices than low-level primitives like volatile."

Part 2: Spring Boot — Beyond the Annotations

Every Java developer knows @Autowired. Senior developers know when not to use it.

Dependency Injection Philosophy

What they ask: "Explain dependency injection in Spring."

What they mean: "Do you understand why we use DI, or do you just follow patterns blindly?"

Senior answer:

"Dependency injection is fundamentally about inverting control of object creation. Instead of a class creating its dependencies, they're provided from outside. This seems simple, but the implications are profound.

Here's what DI actually buys us:

1. Testability without magic

// Without DI — hard to test
public class PaymentProcessor {
    private final PaymentGateway gateway = new StripeGateway();

    public PaymentResult process(Payment payment) {
        return gateway.charge(payment);  // How do you test this without hitting Stripe?
    }
}

// With DI — trivially testable
public class PaymentProcessor {
    private final PaymentGateway gateway;

    public PaymentProcessor(PaymentGateway gateway) {
        this.gateway = gateway;
    }

    public PaymentResult process(Payment payment) {
        return gateway.charge(payment);
    }
}

// Test
@Test
void shouldHandleDeclinedCard() {
    PaymentGateway mockGateway = mock(PaymentGateway.class);
    when(mockGateway.charge(any())).thenReturn(PaymentResult.declined("Insufficient funds"));

    PaymentProcessor processor = new PaymentProcessor(mockGateway);
    PaymentResult result = processor.process(new Payment(100));

    assertThat(result.isDeclined()).isTrue();
}

2. Configuration flexibility

@Configuration
public class PaymentConfig {

    @Bean
    @Profile("production")
    public PaymentGateway productionGateway() {
        return new StripeGateway(stripeApiKey);
    }

    @Bean
    @Profile("sandbox")
    public PaymentGateway sandboxGateway() {
        return new StripeSandboxGateway();
    }

    @Bean
    @Profile("test")
    public PaymentGateway testGateway() {
        return new InMemoryPaymentGateway();  // No external calls
    }
}

Same code, different behavior based on environment. No if-statements scattered through your business logic.

3. Lifecycle management

Spring manages object lifecycles, which matters more than people realize:

@Component
public class DatabaseConnectionPool {
    private final HikariDataSource dataSource;

    @PostConstruct
    public void initialize() {
        // Warm up connections
        dataSource.getConnection().close();
        log.info("Connection pool warmed up");
    }

    @PreDestroy
    public void shutdown() {
        // Graceful shutdown — finish in-flight queries
        dataSource.close();
        log.info("Connection pool shut down gracefully");
    }
}

What I've learned to avoid:

Field injection:

// Don't do this
@Service
public class OrderService {
    @Autowired
    private PaymentService paymentService;  // Hidden dependency
    @Autowired
    private InventoryService inventoryService;  // Another hidden dependency
}

Problems:

Dependencies are invisible in the constructor
Can't create instances without Spring (harder to test)
No compile-time safety if dependency is missing
Encourages too many dependencies (code smell for SRP violation)

Constructor injection is always better:

@Service
public class OrderService {
    private final PaymentService paymentService;
    private final InventoryService inventoryService;

    // If this constructor has 8 parameters, you know something's wrong
    public OrderService(PaymentService paymentService, InventoryService inventoryService) {
        this.paymentService = paymentService;
        this.inventoryService = inventoryService;
    }
}

With constructor injection, a class with too many dependencies becomes obvious — the constructor is unreadable. That's a feature, not a bug. It's a signal that the class has too many responsibilities."

The N+1 Problem — A Production Story

What they ask: "How do you solve N+1 queries in JPA?"

What they mean: "Have you actually debugged performance issues in production?"

Senior answer:

"The N+1 problem has cost me more production incidents than any other JPA issue. Let me tell you about one.

We had an order history page that worked fine in development — maybe 50ms response time. In production, with real data, it took 12 seconds. Users were furious.

The code looked innocent:

@GetMapping("/orders")
public List<OrderDto> getOrders(@RequestParam Long customerId) {
    List<Order> orders = orderRepository.findByCustomerId(customerId);
    return orders.stream()
        .map(this::toDto)
        .collect(toList());
}

private OrderDto toDto(Order order) {
    return new OrderDto(
        order.getId(),
        order.getTotal(),
        order.getItems().size(),  // BOOM — lazy load
        order.getCustomer().getName()  // BOOM — another lazy load
    );
}

One customer had 500 orders. That's:

1 query to get orders
500 queries to get items (one per order)
500 queries to get customer (yes, the same customer 500 times — JPA doesn't know)

1,001 queries for one page load.

Solution 1: JOIN FETCH

@Query("SELECT o FROM Order o " +
       "JOIN FETCH o.items " +
       "JOIN FETCH o.customer " +
       "WHERE o.customer.id = :customerId")
List<Order> findByCustomerIdWithDetails(@Param("customerId") Long customerId);

This generates a single query with JOINs. But there's a catch — if you have multiple collections, you get a cartesian product:

// DON'T DO THIS
@Query("SELECT o FROM Order o " +
       "JOIN FETCH o.items " +
       "JOIN FETCH o.payments " +  // Two collections = cartesian product
       "WHERE o.customer.id = :customerId")

If an order has 10 items and 3 payments, you get 30 rows per order. Hibernate deduplicates, but you've transferred way more data than needed.

Solution 2: @EntityGraph

@EntityGraph(attributePaths = {"items", "customer"})
List<Order> findByCustomerId(Long customerId);

Cleaner syntax, same result. I prefer this for simple cases.

Solution 3: Batch fetching

@Entity
public class Order {
    @OneToMany(mappedBy = "order")
    @BatchSize(size = 25)  // Load 25 orders' items in one query
    private List<OrderItem> items;
}

This changes N+1 into N/25+1. For 500 orders, that's 21 queries instead of 501. Not perfect, but much better, and it doesn't require changing your repository methods.

Solution 4: DTO projections (my preferred approach for read-heavy endpoints)

public interface OrderSummary {
    Long getId();
    BigDecimal getTotal();
    Integer getItemCount();
    String getCustomerName();
}

@Query("SELECT o.id as id, o.total as total, SIZE(o.items) as itemCount, c.name as customerName " +
       "FROM Order o JOIN o.customer c " +
       "WHERE c.id = :customerId")
List<OrderSummary> findOrderSummaries(@Param("customerId") Long customerId);

This is the nuclear option. One query, exactly the data you need, no entity mapping overhead. For read-heavy endpoints where you're just displaying data, this is usually the best choice.

How I prevent N+1 now:

Enable SQL logging in development:

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

Use a query counter in tests:

@Test
void shouldLoadOrdersInSingleQuery() {
    QueryCounter counter = new QueryCounter();

    orderRepository.findByCustomerIdWithDetails(customerId);

    assertThat(counter.getQueryCount()).isLessThanOrEqualTo(1);
}

Monitor query count in production — we alert if any endpoint exceeds 10 queries."

Part 3: System Design Thinking

Senior interviews always include system design. Here's how to approach them.

The Payment Service Question

What they ask: "Design a payment service for an e-commerce platform."

How seniors approach it:

"Before I start designing, I need to understand the constraints. Let me ask a few questions:

What's the expected transaction volume? Tens per second or thousands?
Do we need to support multiple payment providers or just one?
What's the consistency requirement? Can we ever lose a transaction?
What's the latency budget for a payment request?

[Interviewer provides context: 100 TPS, multiple providers, zero data loss, 500ms budget]

Okay, let me think through this systematically.

The core challenge with payments is reliability. Users will retry if something looks stuck. Payment providers might timeout but still process the charge. Network partitions happen. We need to handle all of this without charging someone twice or losing their order.

Architecture:

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Client    │────▶│  Payment API    │────▶│  Payment Worker │
└─────────────┘     └─────────────────┘     └─────────────────┘
                            │                        │
                            ▼                        ▼
                    ┌─────────────┐          ┌─────────────┐
                    │  Database   │          │   Stripe    │
                    │  (source    │          │   Adyen     │
                    │  of truth)  │          │   etc.      │
                    └─────────────┘          └─────────────┘

Key design decisions:

1. Idempotency is non-negotiable

Every payment request must include a client-generated idempotency key:

@PostMapping("/payments")
public PaymentResponse createPayment(
        @RequestHeader("Idempotency-Key") String idempotencyKey,
        @RequestBody PaymentRequest request) {

    // Check if we've seen this request before
    Optional<Payment> existing = paymentRepository.findByIdempotencyKey(idempotencyKey);
    if (existing.isPresent()) {
        return toResponse(existing.get());  // Return cached result
    }

    // Process new payment
    Payment payment = processPayment(request, idempotencyKey);
    return toResponse(payment);
}

This prevents duplicate charges when clients retry.

2. Two-phase state machine

Payments go through explicit states:

public enum PaymentState {
    PENDING,      // Created, not yet sent to provider
    PROCESSING,   // Sent to provider, awaiting response
    COMPLETED,    // Successfully charged
    FAILED,       // Provider declined
    REFUNDED      // Money returned
}

The critical insight: we persist state before calling the payment provider, and update it after we get a response. This way, if we crash mid-processing, we can recover:

@Transactional
public Payment initiatePayment(PaymentRequest request, String idempotencyKey) {
    // Step 1: Create payment record in PENDING state
    Payment payment = Payment.builder()
        .idempotencyKey(idempotencyKey)
        .amount(request.getAmount())
        .state(PaymentState.PENDING)
        .build();
    paymentRepository.save(payment);

    // Step 2: Transition to PROCESSING before calling provider
    payment.setState(PaymentState.PROCESSING);
    paymentRepository.save(payment);

    return payment;
}

// Separate method, possibly async
public void executePayment(Payment payment) {
    try {
        ProviderResponse response = paymentProvider.charge(payment);
        payment.setState(PaymentState.COMPLETED);
        payment.setProviderTransactionId(response.getTransactionId());
    } catch (PaymentDeclinedException e) {
        payment.setState(PaymentState.FAILED);
        payment.setFailureReason(e.getMessage());
    }
    paymentRepository.save(payment);
}

3. Recovery process for stuck payments

A background job finds payments stuck in PROCESSING:

@Scheduled(fixedDelay = 60000)
public void recoverStuckPayments() {
    Instant cutoff = Instant.now().minus(5, ChronoUnit.MINUTES);
    List<Payment> stuck = paymentRepository.findByStateAndCreatedBefore(
        PaymentState.PROCESSING, cutoff);

    for (Payment payment : stuck) {
        // Check with provider if payment actually went through
        ProviderStatus status = paymentProvider.checkStatus(payment.getIdempotencyKey());

        switch (status) {
            case COMPLETED -> payment.setState(PaymentState.COMPLETED);
            case FAILED -> payment.setState(PaymentState.FAILED);
            case NOT_FOUND -> {
                // Provider never received it — safe to retry or fail
                payment.setState(PaymentState.FAILED);
                payment.setFailureReason("Provider timeout — please retry");
            }
        }
        paymentRepository.save(payment);
    }
}

4. Provider abstraction for multi-provider support

public interface PaymentProvider {
    ProviderResponse charge(PaymentDetails details);
    ProviderStatus checkStatus(String idempotencyKey);
    RefundResponse refund(String transactionId, BigDecimal amount);
}

@Service
@Primary
public class RoutingPaymentProvider implements PaymentProvider {
    private final Map<String, PaymentProvider> providers;

    @Override
    public ProviderResponse charge(PaymentDetails details) {
        PaymentProvider provider = selectProvider(details);
        return provider.charge(details);
    }

    private PaymentProvider selectProvider(PaymentDetails details) {
        // Route based on card type, amount, merchant category, etc.
        if (details.getAmount().compareTo(new BigDecimal("10000")) > 0) {
            return providers.get("stripe");  // Lower fees for large transactions
        }
        return providers.get("adyen");  // Better for small transactions
    }
}

What I'd monitor:

Payment success rate (alert if drops below 95%)
Provider latency (p99 should be under 2 seconds)
Stuck payments count (alert if any)
Idempotency key collision rate (should be near zero)

Trade-offs I'm making:

Complexity for reliability — this is more complex than a simple REST call to Stripe
Eventual consistency — the client might get 'processing' and need to poll
Storage overhead — we're keeping full payment history"

Part 4: Behavioral Questions That Actually Matter

Senior roles require leadership and judgment. Here's how to demonstrate both.

"Tell me about a technical decision you regret"

Bad answer: "I can't think of any" (implies you don't reflect on your work)

Good answer:

"Two years ago, I pushed hard for us to adopt microservices. We were a team of six, and our monolith was getting messy. I'd read all the blog posts about how microservices would solve our problems.

We spent four months splitting the monolith into eight services. And honestly? It made everything worse.

Deployments went from 10 minutes to 2 hours because we had to coordinate across services. Debugging a request meant checking logs in five different places. We didn't have the observability infrastructure to support it. And the 'messy monolith' problems? They were still there, just distributed across services now.

What I learned: microservices are an organizational scaling solution, not a technical one. They make sense when you have multiple teams that need to deploy independently. For a team of six working on one product, a well-structured modular monolith is almost always better.

We eventually merged three of those services back. It was painful to admit the mistake, but the team's velocity doubled after we simplified."

"How do you handle disagreements with other engineers?"

Senior approach:

"I had a significant disagreement last year about our caching strategy. A colleague wanted to cache aggressively at the application layer using Redis. I thought we should rely more on database query optimization and HTTP caching.

Here's how I approached it:

First, I made sure I understood their position. Not just what they wanted, but why. Turned out they'd been burned by a slow database at a previous company, so caching was their instinctive solution.

Then I focused the discussion on data, not opinions. I proposed we measure our actual bottlenecks. We profiled a few endpoints and found that 70% of our latency was network calls to external services, not database queries.

We found a compromise based on evidence. We implemented Redis caching for external API responses (where it genuinely helped) but invested in query optimization for our own database. Both of us got part of what we wanted, and the solution was better than either original proposal.

The relationship actually improved. Because I'd taken their concerns seriously and proposed measuring instead of arguing, they trusted my judgment more afterward. We've collaborated well since then.

What I've learned is that technical disagreements are almost never purely technical. There's usually context — past experiences, assumptions, priorities — that shapes someone's position. Understanding that context is often more productive than debating the technical merits."

Final Advice

After conducting hundreds of senior interviews, here's what I look for:

Depth over breadth — I'd rather you know one thing deeply than ten things superficially
Opinions with reasons — "I prefer X because Y" is always better than "I use whatever works"
Humility about mistakes — The best engineers have strong opinions loosely held
Clear communication — If you can't explain it simply, you don't understand it well enough
Curiosity — Do you ask good questions, or just answer what's asked?

The best interview advice I ever got: treat the interview as a conversation between potential colleagues, not an exam. Ask questions. Challenge assumptions. Share your real opinions.

Good luck.

I've also written guides for C# interviews if you work across both ecosystems.

What's the hardest interview question you've faced? Drop it in the comments — I'll add my take.

Why I Built a Centralised Platform Admin in a Microservices Architecture -And What I Learned

Odumosu Matthew — Thu, 19 Mar 2026 07:31:34 +0000

It Started With a Slack Message

Our CTO posted in #engineering at 9:47 AM on a Tuesday:

"Can someone tell me how many active users we have across all products right now?"

Silence. For forty-five minutes.

Not because nobody cared - because nobody knew. The auth service had login counts. The user service had registration numbers. The billing service knew who was paying. But no single place could answer: "How many active users do we have?"

That Slack message cost us a morning of three engineers querying different databases and reconciling numbers in a Google Sheet. That's when we knew we had a problem.

The Microservices Hangover

Here's the thing nobody warns you about in the "Why Microservices" blog posts: decentralisation is fantastic for business logic and terrible for everything else.

We had twelve services. Each one managed its own roles. Its own permissions. Its own metrics. Its own version of the truth. And when anyone outside engineering asked a straightforward question - "Who has admin access?" "What's our uptime?" "When did this permission change?" - the answer was always the same: "Give us a few hours."

We had three specific nightmares:

The Permission Nightmare. Service A thought a user was an admin. Service B disagreed. Both were technically correct according to their own databases. A customer escalation later, we discovered the role had been revoked in one service but not the other. Fun times.

The Dashboard Nightmare. Leadership wanted a single executive dashboard. We had twelve Grafana dashboards, each telling a different story. Our "platform uptime" was a vibes-based estimate that someone calculated manually every Monday morning.

The Audit Nightmare. A compliance review asked: "Show us every admin role change in the last 90 days, who approved it, and why." We spent a week grepping logs across services and reconstructing a timeline in a spreadsheet. The auditor was not impressed.

So we did what any reasonable team would do: we built another microservice. But this one had a different job.

The Platform Admin: One Service to Rule the Cross-Cutting Concerns

The mandate was simple: own the things that get worse when distributed.

Authorization - One source of truth for roles and permissions. Every service asks us: "Can this user do this thing?" We answer in under 10ms.
Observability - One place where metrics from every service converge into a single dashboard.
Audit - One immutable, append-only log of every permission change, role assignment, and admin action across the entire platform.

Not a God service. Not a monolith in disguise. A focused service with a clear boundary: cross-cutting platform governance.

Here's what we learned building it.

Bet #1: Let Services Push Metrics (Don't Pull)

Our first instinct was to have the Platform Admin poll every service. Hit their health endpoints, scrape their stats, aggregate.

Then someone on the team asked the obvious question: "What happens when the auth service is down and we're trying to pull its uptime metric?"

Right. The monitoring system can't depend on the availability of the things it's monitoring. That's not architecture — that's a comedy sketch.

So we flipped it. Every service pushes its own metrics to us via POST endpoints. Auth service reports its call counts. Payment service reports its API volumes. User service reports active users. We receive, validate, store, and serve.

Auth Service ──→ POST /ingest/subsystem-metrics ──→ Platform Admin DB
Payment Service ──→ POST /ingest/api-calls ──→ Platform Admin DB
User Service ──→ POST /ingest/active-users ──→ Platform Admin DB

Frontend ←── GET /dashboard/executive-summary ←── Platform Admin DB

The beauty of this: we don't need to know about new services in advance. A team spins up a new microservice, starts posting to our ingestion endpoint, and their metrics appear on the dashboard. Zero configuration on our side.

And when a service goes silent? Its metrics expire via TTL. The absence of data is the signal. No heartbeat checks needed.

Bet #2: One Table for All Metrics (Yes, Really)

We needed to serve seven different metric types on the dashboard. The obvious move was seven database tables with seven migrations and seven sets of CRUD operations. Then someone on the team muttered: "And next quarter, when product wants three more metric types...?"

Instead, we went with a single table. One row per metric. A composite string key, a JSONB value column, and a TTL timestamp. That's it.

Want to add a new metric type? Create a DTO, pick a key prefix, and start writing. No migration. No PR to update the schema. No waiting for the DBA.

"But you can't query individual fields inside the JSON!"

Correct. And we don't need to. Dashboard data is always read as a complete object and handed to the frontend. We're not running analytical queries against it. We're serialising, storing, and deserialising. The table is a smart cache with persistence, not a relational data model.

Months later, we've added four more metric types. Zero migrations. The table doesn't care.

Bet #3: Validate Tenants at the Gate, Not in Business Logic

Multi-tenant platforms have a sneaky bug pattern: someone passes a tenant ID that doesn't exist, and the system happily returns empty results instead of saying "that's not a real tenant."

We caught this one during testing when someone called our endpoint with /dashboard/metrics/banana/30 and got a 200 OK with zeros. Technically correct — there's no data for the "banana" tenant. Practically useless - it should have been a 400 error.

So we built tenant validation into the request pipeline. Every request with a tenant identifier gets checked against the database before it reaches any business logic. The special keyword all (meaning "aggregate across all tenants") short-circuits and never touches the database.

Since tenant codes change roughly never, we cache the valid set in a HashSet for 10 minutes. The hot path is an O(1) lookup. The cold path hits the database once every 10 minutes. Thirteen endpoints, one validation rule, enforced consistently through FluentValidation in the MediatR pipeline. No endpoint can skip it, even by accident.

Bet #4: CQRS, Because Reads and Writes Live Different Lives

Here's the access pattern for a platform admin:

Writes: Rare, high-stakes. An admin changes a role, ingests metrics, creates an audit entry. Maybe a few hundred writes per hour.
Reads: Constant, latency-sensitive. Permission checks from other services, dashboard queries from the frontend, audit log lookups. Thousands per minute.

Treating these the same way is like designing a library and a nightclub with the same floor plan. They have fundamentally different requirements.

CQRS let us optimise each side independently. The write side does thorough validation, persists carefully, and emits domain events. The read side is aggressively cached and optimised for speed. A permission check from another service hits the cache and returns in single-digit milliseconds. The write path doesn't even notice.

Bet #5: Side Effects Belong in Event Handlers, Not Command Handlers

When an admin assigns a role, here's everything that needs to happen:

Validate the request
Persist the role assignment
Invalidate the permission cache for that user
Send an email notification to the affected user
Notify all admins for visibility
Write an immutable audit log entry
Refresh platform statistics cache

Our first version had all seven steps in the command handler. It was 200+ lines, touched four different infrastructure services, and was a nightmare to test. Mocking the email service to test the cache invalidation? Really?

We refactored to domain events. The command handler does steps 1 and 2 - validate and persist. Then it publishes an event: "A role was assigned." Separate, independent handlers pick up the event and handle their own concern. Cache handler invalidates keys. Notification handler fires emails (fire-and-forget, never blocking the response). Audit handler writes the log.

Now each handler is 20 lines, testable in isolation, and completely unaware of the others. Adding a new side effect - say, posting to a Slack channel, means adding a new event handler. No existing code changes.

Bet #6: Don't Make Reads Pay for Expired Data

Metrics have a TTL. The lazy approach: add WHERE ExpiresAt > NOW() to every query. It works... until you have 50,000 expired rows cluttering the table and your index scans are doing unnecessary work.

We built a background service that wakes up every 30 minutes, deletes expired metrics in batches, and goes back to sleep. Batch size is capped so a single cleanup cycle can't lock the table. If it hits the limit, it logs a warning so ops can tune the configuration.

The metrics table stays lean. Queries stay fast. And instead of every read request paying a tiny tax to filter garbage, a background job handles it once in bulk. It's not clever — it's just good housekeeping.

Bet #7: Design the Audit Log for the Auditor, Not the Developer

Our first audit log was a message text column with entries like: "User admin@company.com assigned role Admin to user john@company.com". Human-readable. Unsearchable. Useless for compliance.

The redesigned audit log captures:

Who initiated the action (with IP address)
Who was the target
What changed (previous state → new state, as structured JSON)
When it happened
Why (a mandatory reason field)
Whether it succeeded or failed

It's append-only. No updates. No deletes. Not even soft deletes. Once a record exists, it exists forever. That's not a technical constraint — it's a compliance requirement. When an auditor asks "has anyone tampered with these logs?" the answer needs to be architecturally impossible, not "we promise we didn't."

We also added CSV export, because auditors don't want to learn your API. They want to open a file in Excel, apply some filters, and go home. Meeting your users where they are applies to internal users too.

The Caching Philosophy That Changed Everything

Here's what I wish someone had told me earlier: caching isn't a performance optimisation. It's an architectural decision.

When fifteen microservices are calling your permission endpoint on every request, the difference between 200ms and 5ms is the difference between a platform that feels snappy and one that feels sluggish. And the bottleneck isn't your code — it's the database round trip.

Our caching strategy is tiered by how often data actually changes:

Data	Cache TTL	Invalidation
User permissions	5 min	Immediate on role change (domain event)
Reference data (role list)	30 min	On any role modification
Dashboard metrics	5 min	On ingestion writes
Tenant codes	10 min	Almost never changes

The critical insight: TTLs are safety nets, not invalidation strategies. When we know data changed (because we just processed the command), we invalidate immediately via domain events. The TTL only exists for the edge case where an event gets lost or a cache entry somehow becomes stale.

This gives us sub-10ms permission checks in production. Other services call us on every request and barely notice the network hop. That's not optimisation - that's making centralised auth viable.

Honest Mistakes We Made

We bolted on audit logging after building RBAC. Retrofitting event publishing into existing command handlers was a week of tedious work. If we'd designed the audit schema first, every handler would have been built with events from day one. Lesson: compliance requirements should shape your architecture, not be stapled on later.

We let each team define their own ingestion payload. One team used count, another used total, a third used value. Same concept, three different field names. A shared contract or schema registry would have saved us a normalisation sprint.

We underinvested in cache invalidation testing. Our unit tests mocked the cache and passed beautifully. The bugs lived in timing — a role change followed by an immediate permission check, where the cache hadn't been invalidated yet. These only surfaced under concurrent load testing. Test your cache invalidation under race conditions, not just in isolation.

What It Looks Like Today

Thirteen endpoints. Six ingestion (microservices pushing data in), seven dashboard (frontend pulling data out). Every single one has:

Tenant validation against the database
Input validation in the request pipeline
JWT authentication
In-memory caching with event-driven invalidation
Structured logging
Automated TTL cleanup

Our CTO's question - "How many active users do we have?" — now takes about 3 seconds to answer. Open the dashboard. It's right there.

TL;DR for the Architects

Centralise cross-cutting concerns, decentralise business logic. Auth, audit, and observability get worse when spread across services. Give them a home.
Push over pull for metrics. The monitoring system shouldn't depend on the availability of what it's monitoring.
Schema flexibility beats relational purity for metrics. A key-value store with JSONB means zero migrations when product wants new dashboard widgets.
Event-driven cache invalidation, not just TTLs. You know when data changes. Act on it immediately.
Design for the auditor. Immutable logs, CSV exports, structured change records. It feels like overhead until the compliance review. Then it's the best thing you built.
Caching is architecture. When your service is in the critical path of every other service, response time isn't a nice-to-have — it's existential.

Building platform infrastructure isn't the kind of work that gets you on stage at a conference. Nobody's tweeting about your audit log schema. But the next time an auditor asks "who had admin access on March 3rd?" and you answer in three seconds flat — or when the CEO opens one dashboard instead of pinging five engineering leads — you'll know it was worth it.

Built with .NET 9, Clean Architecture, CQRS, Entity Framework Core, and PostgreSQL.

Nigeria's Tax Reform 2025: What It Means for You (And Why TaxEngine Changes Everything)

Odumosu Matthew — Thu, 20 Nov 2025 21:20:17 +0000

Let's be honest. When Nigerians hear "tax reform," most people think:

"Government don start again."

"Abeg, how does this one affect my salary?"

"Me wey be freelancer, which tax concern me?"

But this reform? It affects everyone, salary earners, freelancers, influencers, SMEs, startups, and the big companies you buy from every day.

It also signals a new era: Nigeria is moving into digital tax.

This article breaks it all down in simple English, with relatable examples and introduces a platform called TaxEngine, built to help Nigerians navigate this new era without stress.

⚖️ What Exactly Is This Tax Reform? (Simple English Version)

Nigeria updated:

✅ How tax is calculated
✅ How tax is paid
✅ How salaries are taxed
✅ How freelancers and creators file
✅ How businesses issue invoices
✅ How companies remit VAT, CIT, and WHT
✅ How financial records are tracked

But the biggest change is this:

Everything is becoming digital, automated, and cross-checked.

No more guessing your PAYE.

No more Word document invoices with random numbers.

No more "my accountant says…"

👩‍💼 1. How the Reform Affects Salary Earners (PAYE in 2025)

Most Nigerians don't know how their PAYE is calculated and many HR teams don't calculate correctly. Under the new system, accuracy matters more than ever.

Example: Salary PAYE (Relatable Example)

Let's say Ada earns ₦350,000/month.

Her HR tells her: "Your PAYE is ₦17k."

But is that correct? Most people don't know.

PAYE involves:

CRA
Pension
NHF
Statutory reliefs

This complexity is why automation is becoming essential.

🧑‍💻 2. Freelancers, Influencers & Remote Workers, Yes, You Are Taxable Now

If you earn money from:

Fiverr
Upwork
Instagram services
YouTube
TikTok
Remote work
Digital consulting

…you are expected to file Personal Income Tax (PIT).

Example: Freelancer Income

Chidi earns:

₦120k from logo design
₦200k from voiceovers
₦80k from social media jobs
------------------------
Monthly total = ₦400,000

He must calculate PIT and file annually. Digital platforms make these earnings visible, so compliance matters.

🏪 3. SMEs & Small Businesses; The Reform Is Coming for Your Books

If you run a:

👗 Fashion brand
🍰 Bakery
🚚 Logistics service
📸 Studio
💻 Tech company
📱 Agency
...or any registered business

You are expected to comply with:

VAT
WHT
PAYE
E-invoicing
E-filing
CIT

Example: VAT for SMEs

Monthly Sales: ₦1,000,000
VAT (7.5%): ₦75,000

Most SMEs don't remit consistently. The digital reform will expose inconsistencies automatically.

💸 4. Withholding Tax (WHT); The One Businesses Love to Forget

WHT applies to:

Services
Consulting
Design
Rent
Contracts

Usually 5% or 10%.

Example: WHT Scenario

Pay a designer: ₦500,000
WHT (10%): ₦50,000
Amount to remit: ₦50,000

It must be deducted and remitted. Many SMEs don't. The reform tightens enforcement.

🏢 5. Corporate Income Tax (CIT); For Businesses That Make Profit

If your business makes profit, CIT applies.

Example: CIT

Annual Profit: ₦20,000,000
CIT applies automatically

New digital filings reduce under-reporting.

🧾 6. VAT Is Going Fully Digital; No More Manual Invoices

VAT now requires:

✅ Digital invoices
✅ Proper documentation
✅ VAT-accurate totals
✅ Digital records

This removes guesswork and exposes manual mistakes.

🧱 7. The Real Problem: Nigeria's Tax System Is Too Complicated

Let's be honest, even accountants get confused.

The system involves:

Multiple reliefs
Different state rules
Exceptions everywhere
Manual spreadsheets
Monthly filing
Yearly filing
VAT
WHT
CIT
PIT
PAYE

This creates confusion, inconsistency, and mistakes.

And that's exactly why tax automation is becoming crucial.

🚀 Introducing TaxEngine; Nigeria's Modern Tax Infrastructure

TaxEngine is built to remove confusion and automate compliance for:

✅ Individuals
✅ Freelancers
✅ SMEs
✅ Large Enterprises
✅ Developers

Think of it as the Stripe of Nigerian taxes.

⭐ TaxEngine for Individuals

Accurate salary/PAYE calculator
PIT calculator
Reverse salary calculator ("What should my gross be to take home ₦X?")
Filing reminders
Monthly tax breakdown

⭐ TaxEngine for Freelancers & Creators

Track earnings
Auto-compute PIT
Generate e-invoices
Prepare digital records for filing

⭐ TaxEngine for SMEs & Businesses

VAT automation
WHT deduction + remittance
Payroll tax engine
E-filing preparation
Compliance alerts
Digital audit-safe records

⭐ TaxEngine for Developers (API)

APIs for:

PAYE
PIT
VAT
WHT
Company Tax
Payroll automation
E-invoice generation
Tax compliance integrations

Perfect for:

💳 Fintech apps
👥 HR systems
💰 Payroll tools
🛍️ Marketplaces
🏦 Banking apps
📱 POS platforms

🎯 Real-Life Use Cases (Very Relatable)

Use Case 1, Tunde (Salary Earner)

Tunde wants to confirm his PAYE.

TaxEngine calculates it instantly.

Use Case 2, Grace (Freelancer)

Grace earns from Upwork and Instagram.

TaxEngine gives her annual PIT and filing dates.

Use Case 3, A Small Fashion Business

The business pays staff + freelancers weekly.

TaxEngine handles VAT, WHT, and PAYE.

Use Case 4, A Fintech Startup

They need tax-correct receipts.

They plug into the TaxEngine API.

Use Case 5, A Large Company

They have 200+ employees.

TaxEngine automates payroll tax every month.

🌍 Why TaxEngine Matters in Nigeria's New Tax Era

Because Nigeria is moving toward:

📊 Digital reporting
⚡ Instant cross-checks
✅ Audit-safe compliance
🤖 Automated invoices
🎯 Accurate calculations

Manual spreadsheets cannot survive this era. Automation is the only future.

🏁 Final Thoughts, The Future Is Digital, Automated & Transparent

Whether you're:

A worker
A business owner
A freelancer
A creator
A developer
An enterprise

This reform affects you.

And in this new era, tax shouldn't be confusing.

TaxEngine is built to make tax in Nigeria:

✅ Simple
✅ Accurate
✅ Automated
✅ Accessible

No stress. No guesswork. No penalties. Just clarity.

🚀 TaxEngine is Going Live Soon!
The application will be launching soon to help you navigate Nigeria's new tax era with confidence.
Stay Updated! Follow us for launch updates:

💼 LinkedIn: TaxEngine
🐦 Twitter/X: @TaxEngineNG

Be among the first to experience the future of tax compliance in Nigeria!

What are your thoughts on Nigeria's tax reform? How are you preparing for the digital tax era? Let's discuss in the comments! 👇

NigeriaTax #TaxReform #Fintech #TaxEngine #DigitalTransformation #NigerianStartups

Entity Framework Core Isn’t Slow; You’re Just Using It Wrong

Odumosu Matthew — Wed, 10 Sep 2025 10:28:54 +0000

“EF Core is slow.”
It’s one of the most common complaints I hear from developers and one of the most misleading.

After years of working with .NET and building high-scale, enterprise applications, I can say with confidence:
Entity Framework Core isn’t inherently slow, most of the time, it’s being misused.

Yes, EF Core has its limits. No ORM is perfect. But in the majority of projects I’ve audited or worked on, performance issues weren’t caused by EF itself — they were caused by how developers used EF.

In this article, I’ll walk through the most common mistakes that lead to poor EF Core performance, and show you practical solutions to get things running smoothly.

🚫 Mistake 1: Not Using `AsNoTracking()` for Read-Only Queries

By default, EF Core tracks all entities it retrieves from the database. That means it keeps a copy of every entity and monitors it for changes so that you can update it later.

That’s useful, but only when you actually need to update the data.

If you're just reading data (e.g., returning it from an API or showing it in a view), tracking is unnecessary and adds significant overhead.

🔧 The Fix: Use AsNoTracking()

// ❌ Slower: Tracking enabled
var products = await _context.Products.ToListAsync();

// ✅ Faster: Tracking disabled
var products = await _context.Products
    .AsNoTracking()
    .ToListAsync();

✅ When to Use

Report generation
Read-only admin panels
Any time you don’t call SaveChanges()

Using AsNoTracking() can dramatically reduce memory usage and speed up query execution, especially on large datasets.

🐌 Mistake 2: Relying on Lazy Loading - The N+1 Query Problem

Lazy loading sounds convenient, EF loads related entities only when you access them. But this can easily cause what’s known as the N+1 query problem.

🧨 Example: The Pitfall

var students = await _context.Students.ToListAsync();

foreach (var student in students)
{
    // Triggers a separate SQL query per student
    var courseName = student.EnrolledCourse.Name;
}

This can destroy performance.

🔧 The Fix: Use Eager Loading with .Include()

var students = await _context.Students
    .Include(s => s.EnrolledCourse)
    .ToListAsync(); // Just 1 query

✅ Best Practices

Use .Include() when you know you’ll need related data.
Avoid lazy loading unless you’re dealing with very small or optional relationships.
Disable lazy loading globally if it’s not required:

services.AddDbContext<AppDbContext>(options =>
    options.UseLazyLoadingProxies(false));

🧼 Mistake 3: Keeping `DbContext`Alive Too Long

The DbContextclass is designed to be short-lived and used for a single unit of work. Holding onto it for too long (like across multiple requests or operations) can lead to:

Memory leaks
Excessive tracking
Concurrency issues

🔧 The Fix: Use Scoped Lifetime

In an ASP.NET Core app, always register your DbContextwith a scoped lifetime:

services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer("your-connection-string"),
    ServiceLifetime.Scoped);

In short:

Don’t treat DbContext as a singleton.
Don’t inject it into background threads or async voids.
Do keep it scoped to the request or operation.

🎯 Mistake 4: Pulling Full Entities Instead of DTOs

One of the most common (and expensive) EF Core mistakes is loading entire entities from the database when you only need a few fields.

Let’s say you need to show a list of users with their name and email:

❌ Inefficient Query

var users = await _context.Users.ToListAsync();
// Loads all columns, including those you don't need

✅ Efficient Query with Projection

var users = await _context.Users
    .Select(u => new UserDto
    {
        Id = u.Id,
        Name = u.Name,
        Email = u.Email
    })
    .ToListAsync();

This generates a lean SQL query that only selects the fields you need. It also skips navigation properties and lazy loading entirely.

Bonus: Use AutoMapper for Clean Projection

var users = await _context.Users
    .ProjectTo<UserDto>(_mapper.ConfigurationProvider)
    .ToListAsync();

🔧 Bonus Tips for Senior Software Engineers
📦 Use Bulk Operations for Performance at Scale

EF Core does not optimize batch inserts, updates, or deletes by default.

Instead of:

foreach (var item in list)
{
    _context.Update(item);
}
await _context.SaveChangesAsync();

Use a library like EFCore.BulkExtensions

await _context.BulkUpdateAsync(list);

🕵️‍♂️ Monitor EF Core Queries with Logging

Add query logging to see exactly what SQL EF is executing:

services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer("your-connection-string")
           .LogTo(Console.WriteLine, LogLevel.Information));

This helps you:

Spot N+1 problems
Detect large object graphs
Optimize complex LINQ expressions

📌 TL;DR — EF Core Performance Checklist

❌ Mistake	✅ Solution
Tracking unnecessary data	Use `AsNoTracking()`
N+1 queries via lazy loading	Use `.Include()`
Holding DbContext too long	Use scoped DbContext
Fetching full entities	Project into DTOs
Slow batch operations	Use BulkExtensions
Hidden slow queries	Enable SQL logging

🧠 Final Thoughts

EF Core is a powerful, flexible ORM. But like any powerful tool, it’s easy to misuse. Most performance issues I’ve seen in production applications come down to:

Not understanding how EF Core works under the hood
Relying on defaults instead of being intentional
Prioritizing convenience over performance

Once you learn how to use EF Core the right way, it becomes a fast, scalable, and elegant data access layer, even for complex, high-load applications.

🙋‍♂️ Over to You

Have you struggled with EF Core performance in the past? Have a tip I missed?

Let me know in the comments or connect with me directly. I’d love to hear your experience.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Gunnarpeipman Blog

Building a Scalable .NET 8 Web API: Clean Architecture + CQRS + JWT + PostgreSQL + Redis - A Complete Guide

Odumosu Matthew — Sat, 09 Aug 2025 09:17:28 +0000

Every .NET developer has been there, starting a new project with the best intentions, following SOLID principles, writing clean code. Fast forward six months, and you're staring at a monolithic controller with 47 methods, business logic scattered across layers, and a test suite that breaks every time you breathe on the database. Sound familiar?

The problem isn't your coding skills; it's the architecture. Most .NET tutorials show you how to build a "simple" API that works perfectly for demos but crumbles under real-world pressure. Today, we're going to change that.

In this comprehensive guide, we'll build a production-ready .NET 8 Web API from the ground up using Clean Architecture, CQRS pattern, JWT authentication, PostgreSQL for persistence, and Redis for distributed caching. We're not building another "todo app" we're creating a bakery application that could handle real business requirements, scale to thousands of users, and remain maintainable as your team grows.

By the end of this article, you'll have a complete understanding of how to structure enterprise-grade applications, implement proper separation of concerns, handle authentication securely, and leverage caching for optimal performance. More importantly, you'll have working code you can use as a foundation for your next project.

Why This Architecture Matters

Traditional .NET applications often suffer from what I call "layered architecture syndrome" everything depends on everything else, making testing nearly impossible and changes risky. Clean Architecture, combined with CQRS (Command Query Responsibility Segregation), solves these problems by enforcing strict boundaries and single responsibilities.

Here's what we're building:

┌─────────────────────────────────┐
│         Presentation Layer       │  ← Controllers, Middleware, DTOs
│         (BakingApp.API)         │
├─────────────────────────────────┤
│         Application Layer        │  ← Use Cases, CQRS Handlers
│      (BakingApp.Application)    │    Validation, Business Logic
├─────────────────────────────────┤
│       Infrastructure Layer      │  ← Database, Caching, External
│    (BakingApp.Infrastructure)   │    Services, Authentication
├─────────────────────────────────┤
│          Domain Layer           │  ← Entities, Value Objects
│        (BakingApp.Domain)       │    Domain Rules, Exceptions
└─────────────────────────────────┘

This isn't just theoretical, each layer has a specific job, clear boundaries, and testable components. The domain layer contains pure business logic with zero dependencies. The application layer orchestrates use cases without caring about databases or external services. The infrastructure layer handles the messy details of data persistence and external integrations.

Technology Stack Deep Dive

NET 8: Latest LTS version with performance improvements and new features
PostgreSQL: Robust, feature-rich database with excellent .NET support
Redis: High-performance in-memory data store for caching and sessions
Entity Framework Core: ORM with advanced features and performance optimizations
MediatR: Implements mediator pattern for CQRS and cross-cutting concerns
FluentValidation: Powerful validation library with expressive syntax
JWT Bearer Authentication: Stateless authentication perfect for APIs
Docker: Containerization for development and deployment consistency

Project Structure and Setup

Let's start by creating the solution structure. This isn't arbitrary each project represents a distinct architectural layer with specific responsibilities:

BakingApp/
├── src/
│   ├── BakingApp.Domain/           # Core business entities and rules
│   ├── BakingApp.Application/      # Use cases, CQRS, Validators
│   ├── BakingApp.Infrastructure/   # Data access, external services
│   └── BakingApp.API/             # Web API controllers
├── tests/
│   ├── BakingApp.Domain.Tests/
│   ├── BakingApp.Application.Tests/
│   └── BakingApp.API.Tests/
└── docker-compose.yml             # PostgreSQL & Redis containers

The dependency flow is crucial: Domain has no dependencies, Application depends only on Domain, Infrastructure depends on Application and Domain, and API depends on all layers. This creates a stable architecture where changes to external concerns don't ripple through your business logic.

Domain Layer: The Heart of Clean Architecture

The domain layer is the foundation of our application, it contains the core business entities and rules with zero external dependencies. This isn't just a data container; it's where your business logic lives.

// BakingApp.Domain/Entities/User.cs
using System.ComponentModel.DataAnnotations;

namespace BakingApp.Domain.Entities;

public class User
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public string Email { get; set; } = string.Empty;
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public string PasswordHash { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public DateTime? UpdatedAt { get; set; }
    public bool IsActive { get; set; } = true;
    public string Role { get; set; } = "Customer"; // Customer, Baker, Admin
}

Notice how the User entity is a plain C# class with business-relevant properties. We're not inheriting from DbContext entities or implementing repository interfaces this is pure domain logic.

Domain exceptions are equally important. They express business rule violations in the language of your domain:

// BakingApp.Domain/Exceptions/DomainException.cs
namespace BakingApp.Domain.Exceptions;

public class DomainException : Exception
{
    public DomainException(string message) : base(message) { }
    public DomainException(string message, Exception innerException) : base(message, innerException) { }
}

public class UserAlreadyExistsException : DomainException
{
    public UserAlreadyExistsException(string email) 
        : base($"User with email '{email}' already exists.") { }
}

These exceptions communicate business rules clearly. When a UserAlreadyExistsExceptionis thrown, everyone on the team immediately understands what went wrong without digging through database error codes.

Application Layer: CQRS with MediatR

The application layer is where Clean Architecture really shines. Using CQRS (Command Query Responsibility Segregation), we separate read operations (queries) from write operations (commands), leading to cleaner, more maintainable code.

Understanding CQRS Benefits

CQRS isn't just an academic pattern, it solves real problems:

Clarity: Commands and queries have different concerns and can be optimized differently
Scalability: Read and write models can scale independently
Testing: Each handler has a single responsibility, making unit tests straightforward
Performance: Queries can be optimized for reading, commands for consistency

Let's implement user registration using the command pattern:

// BakingApp.Application/Users/Commands/RegisterUser/RegisterUserCommand.cs
using MediatR;

namespace BakingApp.Application.Users.Commands.RegisterUser;

public record RegisterUserCommand(
    string Email,
    string FirstName,
    string LastName,
    string Password,
    string ConfirmPassword
) : IRequest<RegisterUserResponse>;

public record RegisterUserResponse(
    Guid UserId,
    string Email,
    string FirstName,
    string LastName,
    string Token
);

Using records for commands and responses isn't just trendy, it gives us immutability, structural equality, and concise syntax. The command represents intent (what the user wants to do), while the response provides the result.

FluentValidation: Enterprise-Grade Input Validation

Input validation is where many APIs fall apart in production. FluentValidation provides a fluent interface for building complex validation rules:

// BakingApp.Application/Users/Commands/RegisterUser/RegisterUserCommandValidator.cs
using FluentValidation;

namespace BakingApp.Application.Users.Commands.RegisterUser;

public class RegisterUserCommandValidator : AbstractValidator<RegisterUserCommand>
{
    public RegisterUserCommandValidator()
    {
        RuleFor(x => x.Email)
            .NotEmpty().WithMessage("Email is required")
            .EmailAddress().WithMessage("Invalid email format")
            .MaximumLength(100).WithMessage("Email must not exceed 100 characters");

        RuleFor(x => x.FirstName)
            .NotEmpty().WithMessage("First name is required")
            .MaximumLength(50).WithMessage("First name must not exceed 50 characters")
            .Matches(@"^[a-zA-Z\s]+$").WithMessage("First name can only contain letters and spaces");

        RuleFor(x => x.LastName)
            .NotEmpty().WithMessage("Last name is required")
            .MaximumLength(50).WithMessage("Last name must not exceed 50 characters")
            .Matches(@"^[a-zA-Z\s]+$").WithMessage("Last name can only contain letters and spaces");

        RuleFor(x => x.Password)
            .NotEmpty().WithMessage("Password is required")
            .MinimumLength(8).WithMessage("Password must be at least 8 characters long")
            .Matches(@"^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]")
            .WithMessage("Password must contain at least one lowercase letter, one uppercase letter, one digit, and one special character");

        RuleFor(x => x.ConfirmPassword)
            .NotEmpty().WithMessage("Confirm password is required")
            .Equal(x => x.Password).WithMessage("Passwords do not match");
    }
}

These aren't just basic checks, we're enforcing real business rules. The password validation ensures complexity requirements that would satisfy most enterprise security policies. The regex patterns prevent common injection attacks and ensure data consistency.

Command Handler Implementation

The command handler is where the magic happens, it orchestrates the use case without worrying about infrastructure details:

// BakingApp.Application/Users/Commands/RegisterUser/RegisterUserCommandHandler.cs
using BakingApp.Application.Common.Interfaces;
using BakingApp.Domain.Entities;
using BakingApp.Domain.Exceptions;
using MediatR;
using Microsoft.EntityFrameworkCore;

namespace BakingApp.Application.Users.Commands.RegisterUser;

public class RegisterUserCommandHandler : IRequestHandler<RegisterUserCommand, RegisterUserResponse>
{
    private readonly IApplicationDbContext _context;
    private readonly IPasswordHasher _passwordHasher;
    private readonly IJwtTokenGenerator _jwtTokenGenerator;
    private readonly ICacheService _cacheService;

    public RegisterUserCommandHandler(
        IApplicationDbContext context,
        IPasswordHasher passwordHasher,
        IJwtTokenGenerator jwtTokenGenerator,
        ICacheService cacheService)
    {
        _context = context;
        _passwordHasher = passwordHasher;
        _jwtTokenGenerator = jwtTokenGenerator;
        _cacheService = cacheService;
    }

    public async Task<RegisterUserResponse> Handle(RegisterUserCommand request, CancellationToken cancellationToken)
    {
        // Check if user already exists
        var existingUser = await _context.Users
            .FirstOrDefaultAsync(u => u.Email.ToLower() == request.Email.ToLower(), cancellationToken);

        if (existingUser != null)
        {
            throw new UserAlreadyExistsException(request.Email);
        }

        // Create new user
        var user = new User
        {
            Email = request.Email.ToLower(),
            FirstName = request.FirstName,
            LastName = request.LastName,
            PasswordHash = _passwordHasher.HashPassword(request.Password),
            Role = "Customer"
        };

        _context.Users.Add(user);
        await _context.SaveChangesAsync(cancellationToken);

        // Generate JWT token
        var token = _jwtTokenGenerator.GenerateToken(user.Id, user.Email, user.Role);

        // Cache user info for quick lookups
        var cacheKey = $"user:{user.Id}";
        await _cacheService.SetAsync(cacheKey, new { user.Id, user.Email, user.FirstName, user.LastName, user.Role }, 
            TimeSpan.FromHours(1), cancellationToken);

        return new RegisterUserResponse(
            user.Id,
            user.Email,
            user.FirstName,
            user.LastName,
            token
        );
    }
}

This handler demonstrates several important patterns:

Dependency Injection: All external concerns are injected as interfaces
Error Handling: Business rule violations throw domain exceptions
Performance: User data is cached immediately after creation
Security: Passwords are properly hashed, emails are normalized
Async Operations: Everything is async for better scalability

Validation Pipeline Behavior

One of MediatR's most powerful features is pipeline behaviors cross-cutting concerns that run before or after handlers. Our validation behavior ensures all commands are validated automatically:

// BakingApp.Application/Common/Behaviours/ValidationBehavior.cs
using FluentValidation;
using MediatR;

namespace BakingApp.Application.Common.Behaviours;

public class ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);

        var validationResults = await Task.WhenAll(
            _validators.Select(v => v.ValidateAsync(context, cancellationToken)));

        var failures = validationResults
            .SelectMany(r => r.Errors)
            .Where(f => f != null)
            .ToList();

        if (failures.Any())
            throw new ValidationException(failures);

        return await next();
    }
}

This behavior runs before every command handler, automatically validating input and throwing validation exceptions if rules are violated. It's a perfect example of the decorator pattern in action.

Infrastructure Layer: The Heavy Lifting

The infrastructure layer handles all the messy details of external systems—databases, caching, authentication, and third-party services. This is where architectural boundaries really matter because changes here shouldn't affect your business logic.

PostgreSQL with Entity Framework Core

PostgreSQL is an excellent choice for .NET applications, it's open source, feature-rich, and has outstanding performance characteristics. Our DbContext configuration demonstrates several best practices:

// BakingApp.Infrastructure/Data/ApplicationDbContext.cs
using BakingApp.Application.Common.Interfaces;
using BakingApp.Domain.Entities;
using Microsoft.EntityFrameworkCore;

namespace BakingApp.Infrastructure.Data;

public class ApplicationDbContext : DbContext, IApplicationDbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options) { }

    public DbSet<User> Users { get; set; } = null!;

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // User entity configuration
        modelBuilder.Entity<User>(entity =>
        {
            entity.HasKey(e => e.Id);

            entity.Property(e => e.Email)
                .IsRequired()
                .HasMaxLength(100);

            entity.Property(e => e.FirstName)
                .IsRequired()
                .HasMaxLength(50);

            entity.Property(e => e.LastName)
                .IsRequired()
                .HasMaxLength(50);

            entity.Property(e => e.PasswordHash)
                .IsRequired();

            entity.Property(e => e.Role)
                .IsRequired()
                .HasMaxLength(20)
                .HasDefaultValue("Customer");

            entity.Property(e => e.IsActive)
                .HasDefaultValue(true);

            entity.Property(e => e.CreatedAt)
                .HasDefaultValueSql("CURRENT_TIMESTAMP");

            // Create unique index on email
            entity.HasIndex(e => e.Email)
                .IsUnique()
                .HasDatabaseName("IX_Users_Email");
        });

        base.OnModelCreating(modelBuilder);
    }

    public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        // Update timestamps for modified entities
        var entries = ChangeTracker.Entries<User>()
            .Where(e => e.State == EntityState.Modified);

        foreach (var entry in entries)
        {
            entry.Entity.UpdatedAt = DateTime.UtcNow;
        }

        return await base.SaveChangesAsync(cancellationToken);
    }
}

Key configuration points:

Explicit constraints: We define maximum lengths and required fields explicitly
Database defaults: Some fields have database-level defaults for consistency
Unique indexes: Email uniqueness is enforced at the database level
Automatic timestamps: Modified entities get updated timestamps automatically

JWT Authentication Implementation

JWT (JSON Web Token) authentication is perfect for stateless APIs. Our implementation includes all the security best practices you'd expect in production:

// BakingApp.Infrastructure/Authentication/JwtTokenGenerator.cs
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using BakingApp.Application.Common.Interfaces;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.Tokens;

namespace BakingApp.Infrastructure.Authentication;

public class JwtSettings
{
    public string Secret { get; set; } = string.Empty;
    public string Issuer { get; set; } = string.Empty;
    public string Audience { get; set; } = string.Empty;
    public int ExpirationInHours { get; set; } = 24;
}

public class JwtTokenGenerator : IJwtTokenGenerator
{
    private readonly JwtSettings _jwtSettings;

    public JwtTokenGenerator(IOptions<JwtSettings> jwtSettings)
    {
        _jwtSettings = jwtSettings.Value;
    }

    public string GenerateToken(Guid userId, string email, string role)
    {
        var claims = new List<Claim>
        {
            new(ClaimTypes.NameIdentifier, userId.ToString()),
            new(ClaimTypes.Email, email),
            new(ClaimTypes.Role, role),
            new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
            new(JwtRegisteredClaimNames.Iat, DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer64)
        };

        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_jwtSettings.Secret));
        var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var token = new JwtSecurityToken(
            issuer: _jwtSettings.Issuer,
            audience: _jwtSettings.Audience,
            claims: claims,
            expires: DateTime.UtcNow.AddHours(_jwtSettings.ExpirationInHours),
            signingCredentials: credentials
        );

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

This implementation includes:

Standard claims: User ID, email, and role for authorization
JWT ID: Unique identifier for token tracking and revocation
Issued at time: For audit trails and time-based validation
Configurable expiration: Different environments can have different token lifespans
Strong signing: HMAC SHA-256 with a sufficiently long secret

Redis Distributed Caching

Distributed caching is essential for scalable applications. Redis provides high-performance caching with features like data persistence, pub/sub, and various data structures:

// BakingApp.Infrastructure/Caching/CacheService.cs
using System.Text.Json;
using BakingApp.Application.Common.Interfaces;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.Logging;

namespace BakingApp.Infrastructure.Caching;

public class CacheService : ICacheService
{
    private readonly IDistributedCache _distributedCache;
    private readonly ILogger<CacheService> _logger;
    private readonly JsonSerializerOptions _jsonOptions;

    public CacheService(IDistributedCache distributedCache, ILogger<CacheService> logger)
    {
        _distributedCache = distributedCache;
        _logger = logger;
        _jsonOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = false
        };
    }

    public async Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default) where T : class
    {
        try
        {
            var cached = await _distributedCache.GetStringAsync(key, cancellationToken);

            if (string.IsNullOrEmpty(cached))
                return null;

            return JsonSerializer.Deserialize<T>(cached, _jsonOptions);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error retrieving data from cache for key: {Key}", key);
            return null;
        }
    }

    public async Task SetAsync<T>(string key, T value, TimeSpan? expiration = null, CancellationToken cancellationToken = default) where T : class
    {
        try
        {
            var options = new DistributedCacheEntryOptions();

            if (expiration.HasValue)
                options.SetSlidingExpiration(expiration.Value);
            else
                options.SetSlidingExpiration(TimeSpan.FromMinutes(30)); // Default 30 minutes

            var serialized = JsonSerializer.Serialize(value, _jsonOptions);
            await _distributedCache.SetStringAsync(key, serialized, options, cancellationToken);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error storing data in cache for key: {Key}", key);
        }
    }

    public async Task RemoveAsync(string key, CancellationToken cancellationToken = default)
    {
        try
        {
            await _distributedCache.RemoveAsync(key, cancellationToken);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error removing data from cache for key: {Key}", key);
        }
    }
}

The cache service demonstrates several important patterns:

Graceful failure: Cache errors don't break the application—they're logged and handled
Configurable expiration: Different data can have different cache lifetimes
Generic implementation: Works with any serializable object
Consistent JSON serialization: Uses camelCase for JavaScript compatibility

Password Hashing Security

Password security is non-negotiable in production applications. We use ASP.NET Core Identity's password hasher, which implements industry best practices:

// BakingApp.Infrastructure/Authentication/PasswordHasher.cs
using BakingApp.Application.Common.Interfaces;
using Microsoft.AspNetCore.Identity;

namespace BakingApp.Infrastructure.Authentication;

public class PasswordHasher : IPasswordHasher
{
    private readonly IPasswordHasher<object> _passwordHasher;

    public PasswordHasher()
    {
        _passwordHasher = new PasswordHasher<object>();
    }

    public string HashPassword(string password)
    {
        return _passwordHasher.HashPassword(new object(), password);
    }

    public bool VerifyPassword(string password, string hashedPassword)
    {
        var result = _passwordHasher.VerifyHashedPassword(new object(), hashedPassword, password);
        return result == PasswordVerificationResult.Success || 
               result == PasswordVerificationResult.SuccessRehashNeeded;
    }
}

This implementation uses PBKDF2 with SHA-256, includes salt generation, and supports hash upgrades—exactly what you need for enterprise security.

API Layer: Bringing It All Together

The API layer is the entry point to our application. It's responsible for HTTP concerns, routing, model binding, authentication, and response formatting, while delegating business logic to the application layer.

Controller Implementation

Our controllers are thin by design—they validate input, delegate to handlers, and format responses:

// BakingApp.API/Controllers/AuthController.cs
using BakingApp.Application.Users.Commands.LoginUser;
using BakingApp.Application.Users.Commands.RegisterUser;
using BakingApp.Domain.Exceptions;
using MediatR;
using Microsoft.AspNetCore.Mvc;

namespace BakingApp.API.Controllers;

[Route("api/[controller]")]
[ApiController]
public class AuthController : ControllerBase
{
    private readonly IMediator _mediator;

    public AuthController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpPost("register")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> Register([FromBody] RegisterUserCommand command)
    {
        var result = await _mediator.Send(command);
        return Ok(new
        {
            success = true,
            message = "User registered successfully",
            data = result
        });
    }

    [HttpPost("login")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
    public async Task<IActionResult> Login([FromBody] LoginUserCommand command)
    {
        var result = await _mediator.Send(command);
        return Ok(new
        {
            success = true,
            message = "Login successful",
            data = result
        });
    }
}

Global Exception Handling

Exception handling middleware provides consistent error responses across the entire API:

// BakingApp.API/Middleware/ExceptionHandlingMiddleware.cs
using BakingApp.Domain.Exceptions;
using FluentValidation;
using System.Net;
using System.Text.Json;

namespace BakingApp.API.Middleware;

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "An unhandled exception occurred: {Message}", exception.Message);

        // This ProblemDetails object will be the foundation for our response
        var problemDetails = new ProblemDetails
        {
            Instance = $"{httpContext.Request.Method} {httpContext.Request.Path}"
        };

        // Map exceptions to status codes and titles
        (problemDetails.Status, problemDetails.Title, problemDetails.Detail) = exception switch
        {
            DomainException domainEx =>
                ((int)HttpStatusCode.BadRequest, "Bad Request", domainEx.Message),

            ValidationException validationEx =>
                ((int)HttpStatusCode.BadRequest, "Validation Error", "One or more validation errors occurred."),

            UnauthorizedAccessException unauthorizedEx =>
                ((int)HttpStatusCode.Unauthorized, "Unauthorized", unauthorizedEx.Message),

            _ =>
                ((int)HttpStatusCode.InternalServerError, "An internal server error has occurred.", "Please try again later.")
        };

        // For validation exceptions, we can add the specific errors to the extensions
        if (exception is ValidationException validationException)
        {
            problemDetails.Extensions["errors"] = validationException.Errors
                .Select(e => new { property = e.PropertyName, error = e.ErrorMessage });
        }

        httpContext.Response.StatusCode = problemDetails.Status.Value;

        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);

        // Return true to signal that the exception has been handled.
        return true;
    }
}

This middleware ensures that:

Validation errors return 400 with detailed field-level errors
Domain exceptions return 400 with business-friendly messages
Authorization failures return 401 with clear messaging
Unexpected errors return 500 without exposing internal details

PIPELINE CONFIGURATION

// program.cs
using FluentValidation;
using MediatR;
using MyBank.API.Middleware;
using MyBank.Application.Behaviours;
using MyBank.Infrastructure;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// Application Layer
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(DependencyInjection).Assembly));
builder.Services.AddValidatorsFromAssembly(typeof(DependencyInjection).Assembly);
builder.Services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));

// Add Infrastructure Layer
builder.Services.AddInfrastructure(builder.Configuration);

// Add CORS
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", builder =>
    {
        builder.AllowAnyOrigin()
               .AllowAnyMethod()
               .AllowAnyHeader();
    });
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}


app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Infrastructure Setup: Docker Compose

Development environment setup should be effortless. Our Docker Compose configuration provides PostgreSQL and Redis with a single command:

# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: bakingapp-postgres
    environment:
      POSTGRES_DB: bakingapp_db
      POSTGRES_USER: bakingapp_user
      POSTGRES_PASSWORD: bakingapp_password123
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - bakingapp-network

  redis:
    image: redis:7-alpine
    container_name: bakingapp-redis
    command: redis-server --appendonly yes --requirepass redis_password123
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - bakingapp-network

volumes:
  postgres_data:
  redis_data:

networks:
  bakingapp-network:
    driver: bridge

This configuration provides:

PostgreSQL 15: Latest stable version with excellent performance
Redis 7: Latest version with persistence enabled
Data persistence: Volumes ensure data survives container restarts
Network isolation: Services communicate on a private network
Security: Password protection for both services

Configuration and Secrets Management

Production applications need flexible configuration management. Our approach separates development and production settings while keeping secrets secure:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=bakingapp_db;Username=bakingapp_user;Password=bakingapp_password123",
    "Redis": "localhost:6379,password=redis_password123"
  },
  "JwtSettings": {
    "Secret": "ThisIsAVerySecureSecretKeyForJWTTokenGenerationThatIs32CharactersLong!",
    "Issuer": "BakingApp",
    "Audience": "Bak

GITHUB RESPOSITORY: GitHub

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Dev.To

Mastering LINQ in C#: A Comprehensive Guide to Methods and When to Use Them

Odumosu Matthew — Thu, 07 Aug 2025 16:17:54 +0000

LINQ (Language Integrated Query) is one of C#’s most powerful features, allowing developers to query and transform data using a clean, readable syntax. Whether you're working with in-memory collections like List<T> or querying a database using Entity Framework Core, LINQ offers a unified approach to accessing and shaping your data.

In this guide, we’ll walk through every commonly used LINQ method, grouped by purpose, and explain when and why to use them—with examples and real-world insights.

🔍 1. Element Operators

These methods are used to retrieve single items from a collection.

Method	When to Use
`First()`	When you're certain the collection has at least one match.
`FirstOrDefault()`	When the match might not exist and you want to avoid exceptions.
`FirstOrDefaultAsync()`	Async version for EF Core; avoids blocking the main thread.
`Single()`	When you expect exactly one matching item. Throws if more than one.
`SingleOrDefault()`	When there may be zero or one match, and duplicates are not allowed.
`Last()`	When you need the last item in a collection.
`LastOrDefault()`	Safe alternative to `Last()`.
`ElementAt(index)`	When accessing a specific index.
`ElementAtOrDefault()`	Safe alternative that returns default if index is out of bounds.

Example:

var user = await _context.Users.FirstOrDefaultAsync(u => u.Id == userId);

✅ 2. Filtering Operators

Filter elements that meet certain conditions.

Method	When to Use
`Where()`	To filter multiple elements by a condition.
`OfType<T>()`	To filter by type in non-generic collections.

Example:

var activeUsers = users.Where(u => u.IsActive).ToList();

🔢 3. Projection Operators

Used to transform data from one shape to another.

Method	When to Use
`Select()`	To map each item into a new form or DTO.
`SelectMany()`	To flatten nested collections into a single collection.

var userNames = users.Select(u => u.Name).ToList();

🔁 4. Sorting Operators

For ordering data.

Method	When to Use
`OrderBy()`	To sort in ascending order.
`OrderByDescending()`	To sort in descending order.
`ThenBy()`	For secondary ascending sort.
`ThenByDescending()`	For secondary descending sort.
`Reverse()`	To reverse the current order.

Example:

var sorted = users.OrderBy(u => u.Name).ThenBy(u => u.CreatedAt);

❓ 5. Quantifier Methods

Return true or false based on conditions.

Method	When to Use
`Any()`	To check if any items exist or match a condition.
`AnyAsync()`	Async version for EF Core.
`All()`	To check if all items match a condition.
`Contains()`	To check if a specific value exists in the collection.

Example:

bool exists = await _context.Users.AnyAsync(u => u.Email == email);

🧮 6. Aggregation Methods

Used to perform summary calculations.

Method	When to Use
`Count()`	To count items in a collection.
`Sum()`	To calculate a total.
`Average()`	To calculate the average of numeric values.
`Min()` / `Max()`	To get the smallest/largest value.
`Aggregate()`	To create custom aggregations (e.g., string joins).

Example:

var totalSales = orders.Sum(o => o.TotalAmount);

🧱 7. Grouping Methods

Group data based on a key.

Method	When to Use
`GroupBy()`	To group elements by a common key or value.

Example:

var grouped = orders.GroupBy(o => o.CustomerId);

➕ 8. Set Operators

Used to perform set-based logic like union or intersection.

Method	When to Use
`Distinct()`	To remove duplicate items.
`Union()`	Combines two sets, removes duplicates.
`Intersect()`	Returns common items from both collections.
`Except()`	Returns items from one set not found in the other.

Example:

var uniqueEmails = users.Select(u => u.Email).Distinct();

🔗 9. Joining Operators

Combine elements from multiple collections.

Method	When to Use
`Join()`	To join two collections based on a key (similar to SQL INNER JOIN).
`GroupJoin()`	To join and group elements (similar to LEFT JOIN).
`Zip()`	To combine two collections element-by-element.

Example:

var userRoles = users.Join(roles,
    user => user.RoleId,
    role => role.Id,
    (user, role) => new { user.Name, role.Name });

🛠️ 10. Generation Methods

Used to create data sequences.

Method	When to Use
`Range()`	To generate a sequence of numbers.
`Repeat()`	To repeat a value multiple times.
`Empty<T>()`	To return an empty collection of type `T`.

Example:

var numbers = Enumerable.Range(1, 10);

🔄 11. Conversion Methods

Transform query results into a specific type.

Method	When to Use
`ToList()`	Convert to a `List<T>`.
`ToArray()`	Convert to an array.
`ToDictionary()`	Convert to a dictionary.
`AsEnumerable()`	Switch to LINQ to Objects from LINQ to SQL.
`AsQueryable()`	Enable further querying (esp. in LINQ to SQL).

Example:

var userList = users.Where(u => u.IsActive).ToList();

💡 Real-World Use Cases

Scenario	Recommended LINQ Method(s)
Retrieve user by ID	`FirstOrDefault()`, `SingleOrDefault()`
Check if an email exists	`Any()` / `AnyAsync()`
Get first five recent orders	`OrderByDescending().Take(5)`
Join users with roles	`Join()`
Sum total sales	`Sum()`
Group products by category	`GroupBy()`
Convert results to list or array	`ToList()`, `ToArray()`

🧠 Best Practices & Pitfalls to Avoid

✅ Prefer FirstOrDefault() over First() to avoid exceptions.

✅ Use Any() instead of Count() > 0 for better performance.

✅ Avoid calling ToList() early in the query chain.

⚠️ Be cautious with SelectMany(), it flattens data, which can be confusing.

⚠️ Single() is strict—use only when you're confident about unique matches.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from pawelmajewski'S Blog

🧠 Understanding the Difference Between IEnumerable and IQueryable in C#

Odumosu Matthew — Tue, 29 Jul 2025 19:55:18 +0000

When working with data in C#, especially when using LINQ or Entity Framework, developers often come across two interfaces: IEnumerableand IQueryable. Although both allow iteration over collections, they have crucial differences especially regarding performance and execution context.

This article will break it all down in plain English, using analogies, real-world examples, and relevant code blocks.

Feature	`IEnumerable`	`IQueryable`
Namespace	`System.Collections`	`System.Linq`
Execution	In-memory	Out-of-memory (like database)
Filtering	After data is loaded	Translates filtering to data source (e.g., SQL)
Deferred Execution	✅ Yes	✅ Yes
Best Used With	Local collections (Lists, Arrays, etc.)	Remote data (Entity Framework, LINQ to SQL)

🎯 High-Level Concept

IEnumerable is like fetching all books from a library to your house and then picking the ones you like.
IQueryable is like calling the library and asking them to only send you books published after 2010.

🏗️ Deep Dive: IEnumerable

✅ Definition

IEnumerable is an interface that allows iteration over a collection in memory.

public interface IEnumerable
{
    IEnumerator GetEnumerator();
}

📘 Example Use Case

List<string> names = new List<string> { "Alice", "Bob", "Charlie" };
IEnumerable<string> filteredNames = names.Where(n => n.StartsWith("A"));

foreach (var name in filteredNames)
{
    Console.WriteLine(name); // Output: Alice
}

The filtering (Where) happens after the list is loaded in memory.
Great for working with already-fetched data like arrays or lists.

🌐 Deep Dive: IQueryable

✅ Definition

IQueryable extends IEnumerable and is designed for querying remote data sources like databases. It allows LINQ queries to be translated to SQL and executed on the server.

public interface IQueryable : IEnumerable
{
    Type ElementType { get; }
    Expression Expression { get; }
    IQueryProvider Provider { get; }
}

📘 Example Use Case (Entity Framework)

IQueryable<User> users = dbContext.Users.Where(u => u.Age > 30);

No data is fetched yet.
When enumerated (e.g., with .ToList()), it gets translated into:

SELECT * FROM Users WHERE Age > 30

Only the relevant data is pulled from the database much more efficient for large datasets.

⚖️ IEnumerable vs IQueryable : Real-World Analogy

🍎 Grocery Shopping Analogy

Scenario	`IEnumerable`	`IQueryable`
You go to the store and bring home all the fruits, then sort them.	✅	❌
You call ahead and ask them to only pack fruits under \$5, then you pick up the box.	❌	✅

📦 Under the Hood: Execution Flow

IEnumerable:

List<Product> products = db.Products.ToList(); // Data loaded into memory
var cheapProducts = products.Where(p => p.Price < 50); // Filtering in memory

Query is translated to SQL.
Only required rows are returned from the database, better for performance.

💥 Performance Impact

Example
Imagine a Productstable with 1 million rows.

// IEnumerable - Bad!

List<Product> allProducts = db.Products.ToList(); // Loads ALL rows
var filtered = allProducts.Where(p => p.Price > 1000); // Filters in memory

❌ Loads a ton of unnecessary data

// IQueryable - Good!
var filtered = db.Products.Where(p => p.Price > 1000).ToList(); // SQL does the filtering

✅ Only needed rows come across the network

🛠 When to Use What?

Use Case	Use `IEnumerable`	Use `IQueryable`
Working with in-memory collections	✅ Yes	❌ No
Querying large datasets from database	❌ No	✅ Yes
LINQ to Objects	✅	❌
Entity Framework / LINQ to SQL	❌	✅
You want SQL optimization (e.g., joins, WHERE)	❌	✅

🧩 Bonus: Mixing Both

You can combine both interfaces:

// IQueryable: query to DB
var query = db.Users.Where(u => u.IsActive);

// IEnumerable: further filter in memory
var activeAdmins = query.ToList().Where(u => u.Role == "Admin");

✅ Summary

Criteria	`IEnumerable`	`IQueryable`
Execution	In-memory	Database or remote query
Performance	Slower for large datasets	Faster, optimized for data queries
Best For	Collections already in memory	Querying databases

🧠 Final Thought

If you’re working with data that’s already in memory, go with IEnumerable.

If you’re pulling from a database, use IQueryable to avoid performance issues.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Yohan's Blog

Threads, Tasks, and Async in C#: What Every .NET Developer Must Know

Odumosu Matthew — Fri, 25 Jul 2025 18:30:54 +0000

🧠 PART 1: What Is a Thread?

Imagine you're running a kitchen.

You (the computer) have one stove 🔥 (your CPU).
A thread is like a cook 🍳.
Each cook can do one task at a time, boil rice, fry meat, chop onions.

If you have one cook (1 thread), he has to do everything in order:
1️⃣ Boil water
2️⃣ Fry eggs
3️⃣ Toast bread

But if you have multiple cooks (multiple threads), they can work at the same time.
One cooks rice, another chops onions, another sets the table.

✅ Threads allow your program to do multiple things at once (or appear to).

🧪 Real-World Analogy

Imagine this:

You’re writing an app that downloads files from the internet.
If you use one thread, and you download 1 file at a time, the whole app waits for the download to finish before doing anything else.

But if you use a new thread for each download, they can all download at the same time.

📦 Simple C# Example: No Threads

public void DownloadFiles()
{
    DownloadFile("file1"); // Waits
    DownloadFile("file2"); // Waits again
    DownloadFile("file3"); // Waits again
}

This is one cook in the kitchen. Slow. One at a time.

🧵 Now, Let’s Use Threads

public void DownloadFiles()
{
    new Thread(() => DownloadFile("file1")).Start();
    new Thread(() => DownloadFile("file2")).Start();
    new Thread(() => DownloadFile("file3")).Start();
}

This is like saying:
“Hey, I’ve got 3 cooks. Each one will handle one file. Go!”

They all work in parallel.

😳 But Wait: Why Not Use Threads Everywhere?

Because threads are expensive. They:

Use memory (about 1 MB per thread)
Can crash your app if you make too many
Need management if one thread accesses data while another thread is writing, boom: race condition 🧨

If you start 1000 threads to do 1000 downloads, your computer might freeze. That's too many cooks in the kitchen fighting for the stove.

✅ Better Way: Use Task and ThreadPool

.NET gives you a helper: Task, which uses a shared pool of threads safely.

public async Task DownloadFiles()
{
    var tasks = new List<Task>();

    tasks.Add(Task.Run(() => DownloadFile("file1")));
    tasks.Add(Task.Run(() => DownloadFile("file2")));
    tasks.Add(Task.Run(() => DownloadFile("file3")));

    await Task.WhenAll(tasks); // Waits for all downloads to finish
}

This says: “.NET, you manage the threads for me, and don’t make a mess.”

🧠 When Should I Use a Thread?

Use threads (or Task.Run) only when you need to do heavy work without blocking the main app.

✅ Examples:

Image processing
Compressing a file
Doing complex math
Logging or background tasks

❌ Don’t use a thread to wait for a file to download or an API to respond. Use async/await for that (it doesn’t block any threads).

🛑 DON'T: Block the UI or Main Thread

In UI apps (WinForms, WPF, Blazor), if you do something slow on the main thread, the app freezes.

// Bad: Freezes UI
public void Button_Click()
{
    Thread.Sleep(5000); // App stops responding
}

✅ Instead:

public async void Button_Click()
{
    await Task.Delay(5000); // Doesn't freeze UI
}

🔄 Summary in Super Simple Terms

Concept	Think of it like…	When to use it
Thread	A cook in your kitchen	Heavy CPU work
Task	A smart kitchen manager who assigns cooks	Everyday parallel work
async/await	A waiter—hands off an order, doesn’t wait	For slow things like downloading or database

🧠 PART 2: So What Really Happens Inside a Thread?

Let’s go behind the scenes and understand how the operating system and .NET manage threads.

🧩 1. A Thread = A Lightweight Process (Kind Of)

When your app runs, it starts as a process (like an .exe file).

A process contains:

Program code
Memory (heap and stack)
At least one thread to execute code

Each thread in that process:

Shares the heap memory (shared objects, like variables, services, etc.)
Has its own stack (local variables, method calls)
Gets scheduled by the OS scheduler

🔄 2. Thread Lifecycle

New → Running → Waiting/Sleeping → Terminated

Example:

var thread = new Thread(() => DoWork());
thread.Start(); // Running
thread.Join();  // Waits until it ends

Start() — kicks it off
Sleep() — pauses it
Join() — tells the main thread to wait for it
Abort() — dangerous, avoid it (it's been deprecated)

🧵 3. Why new Thread() is Rarely Used Now

Creating a thread manually is like saying:

"Spawn a new person from scratch to do this one job."

That’s slow, expensive, and not sustainable if you're doing this often.

So .NET gives you a ThreadPool.

🛠️ Part 3: ThreadPool – The .NET Smart Thread Manager

The ThreadPool is like a team of pre-hired cooks, sitting around waiting for work.

Benefits:

No overhead of creating a thread every time
Threads are reused
Managed based on load
Automatically scales up/down

Usage:

ThreadPool.QueueUserWorkItem(state =>
{
    Console.WriteLine("Running on a thread pool thread");
});

Or more modern:

await Task.Run(() => DoSomethingHeavy());

This is 99% of what you’ll use in a professional app.

⚙️ Part 4: Threads for CPU-Bound vs I/O-Bound Work

This is super important, and often misunderstood:

Type of Work	Description	Best Approach
CPU-bound	Intense computation, math, image resizing, compression	Use `Task.Run`, thread pool
I/O-bound	Waiting for web requests, disk, database	Use `async/await` no thread needed while waiting

CPU-Bound Example:

public async Task CalculateAsync()
{
    await Task.Run(() => ExpensiveCalculation());
}

I/O-Bound Example:

public async Task GetDataAsync()
{
    var response = await httpClient.GetStringAsync("https://api.com/data");
}

✅ Notice: In I/O-bound, you don’t need to spin a thread at all! The OS takes care of it through something called IO Completion Ports (IOCP).

🔐 Part 5: The Real Problem : Shared Memory and Thread Safety

When multiple threads work on the same data, chaos can happen unless you're careful.

🧨 Problem: Race Condition

int count = 0;

void Increment()
{
    for (int i = 0; i < 1000; i++)
        count++; // Not thread-safe
}

Run this on 10 threads = 👎 unpredictable result.

✅ Fix: Use Locks

object _lock = new object();

void Increment()
{
    for (int i = 0; i < 1000; i++)
    {
        lock (_lock)
        {
            count++;
        }
    }
}

This ensures only one thread at a time can touch count.

📈 Part 6: Real Examples Where Threads Shine

Example 1: Parallel Image Processing

string[] files = Directory.GetFiles("images/");
Parallel.ForEach(files, file =>
{
    ResizeImage(file); // Runs in parallel across multiple threads
});

This uses multiple CPU cores and speeds things up 4x–8x easily.

Example 2: Background Worker Queue

BlockingCollection<Action> queue = new();

void StartWorker()
{
    Task.Run(() =>
    {
        foreach (var job in queue.GetConsumingEnumerable())
        {
            job(); // Run the job on this background thread
        }
    });
}

// Main app
queue.Add(() => DoSomething());
queue.Add(() => DoSomethingElse());

✅ Perfect for background processing, queues, logging, etc.

🔄 Part 7: Best Practices

| Goal                            | Best Approach                            |
| ------------------------------- | ---------------------------------------- |
| Run heavy CPU logic             | `Task.Run` or `Parallel.For`             |
| Do background work continuously | `BackgroundService` or `HostedService`   |
| Wait for I/O                    | `async/await`, don’t block threads       |
| Don't block main thread         | Never use `Thread.Sleep` in UI or APIs   |
| Avoid `new Thread()`            | Almost always use `Task` or `ThreadPool` |

🚀 Final Summary

Threads let you do multiple things at once but use them wisely.
Too many threads = memory issues + poor performance.
For heavy work → use Task.Run() or Parallel with ThreadPool.
For I/O work → use async/await no need to spin a thread.
Keep shared data safe with lock, ConcurrentQueue, or Channels.
Use thread aware architectures for real world systems: logging, job queues, background workers, etc.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from bugeto.net

Synchronous by Design: Why async/await in REST or gRPC Doesn’t Make Your System Asynchronous

Odumosu Matthew — Thu, 24 Jul 2025 15:02:58 +0000

Modern .NET developers often lean on async/await to build performant APIs and services. But here's a critical truth:

Using async/await in a synchronous communication model doesn’t make your system asynchronous.

This misunderstanding is common in RESTful and gRPC-based architectures. It often leads to bottlenecks, false scalability assumptions, and overly tight coupling between services.

Let’s dive into the core of the issue what asynchronicity really means, how it's different from non-blocking code, and why REST/gRPC are inherently synchronous, even when wrapped in async/await.

🧠 1. Synchronous vs Asynchronous: Let’s Define Them Clearly

🔗 Synchronous Systems
In synchronous communication, the caller waits for a response from the callee before proceeding.

Example:

var user = await _userServiceClient.GetUserAsync(userId);

Even though you're using await, the service cannot continue until it receives a response from the _userServiceClient. The thread may be released, but the logical flow is still request-response blocking.

⛓ Characteristics:

Tight temporal coupling
Immediate feedback required
Latency is part of business flow
Failure in downstream = upstream timeout/failure

🔄 Asynchronous Systems

In truly asynchronous systems, the caller doesn’t wait. It sends a message or triggers an event, and then continues. Processing happens independently, often triggered by an event or message queue.

Example:

await _messageBus.PublishAsync(new OrderPlacedEvent(orderId));

There’s no response expected. The event is handed off to a queue, and processing happens elsewhere. If no consumer exists, it still doesn’t break the producer.

⚡ Characteristics:

Loose coupling
Message-driven
Can be processed later
Failures don’t immediately bubble back

🧩 2. async/await ≠ Asynchronous Architecture

Let’s make this crystal clear:
async/await is non-blocking, but REST or gRPC is still synchronous because it is fundamentally request-response.

⚠️ Misconception:

public async Task<IActionResult> GetOrders()
{
    var orders = await _orderService.GetOrdersAsync();
    return Ok(orders);
}

Looks asynchronous. But it’s not an asynchronous system.

The controller waits for the service to respond.
The client waits for the controller to respond.
The whole call chain is temporally coupled, all services must be alive and responsive right now.

Even if it uses async/await internally, it’s synchronous by communication model.

🚫 Why REST/gRPC Stay Synchronous Even with async/await

REST:

HTTP 1.1/2 protocol
Follows strict request-response semantics
Timeout failures propagate up the chain
Cannot defer response naturally

gRPC:

Binary, faster, supports streaming
Still client waits for server
Streaming may reduce blocking, but still does not break coupling

Even with all the await, both REST and gRPC rely on:

Immediate network delivery
Live services
Predefined response structure

They cannot natively support:

Deferred processing
Unpredictable consumer availability
Retry logic with dead-letter queues

🏗 3. True Asynchronous Programming: Message Queues & Event-Driven Systems

Let’s now examine asynchronous programming at the system level, not just syntax.

🎯 Architecture

Client fires an event or enqueues a command
Server consumes it later, possibly in a different process, thread, or container
No waiting; temporal and spatial decoupling

🔁 Example in C#: Publish to a Queue

public async Task SubmitOrderAsync(Order order)
{
    var message = new ServiceBusMessage(JsonSerializer.Serialize(order));
    await _queueClient.SendMessageAsync(message);
}

No OrderResponse needed. The message is stored, acknowledged, and processed later.

🧠 Why This Is Truly Asynchronous:

No round-trip waiting
Built-in retry, dead-letter, backpressure
System can scale horizontally
Consumers can process at their own pace
Supports resilience and eventual consistency

🔥 Real-World Analogy

Let’s compare two real-world systems:

Scenario	Synchronous (REST/gRPC)	Asynchronous (Messaging/Eventing)
Restaurant	You order, wait at the counter	You place an order, get a buzzer
Customer Action	Blocks your time	Continues your day
Server Dependency	Must cook now	Can fulfill when ready
Failure	Customer leaves if delayed	Buzzer system retries or notifies later

⚙️ C# System Comparison: Synchronous vs Asynchronous

🔗 REST Controller (Synchronous System)

[HttpPost]
public async Task<IActionResult> PlaceOrder(OrderDto order)
{
    var orderId = await _orderService.PlaceOrderAsync(order); // Waits here
    return Ok(orderId);
}

🔁 Messaging Controller (Asynchronous System)

[HttpPost]
public async Task<IActionResult> PlaceOrder(OrderDto order)
{
    var orderId = Guid.NewGuid();
    var @event = new OrderPlacedEvent(orderId, order);
    await _messageBus.PublishAsync(@event);
    return Accepted(orderId);
}

The request returns immediately, the actual work happens elsewhere.

🛠 Tools for Building Asynchronous Systems in .NET

Tool	Purpose
MassTransit	Message bus abstraction over RabbitMQ, Azure SB, etc.
Hangfire / Quartz.NET	Delayed job scheduling
Azure Service Bus	Durable messaging with retry, DLQ
Kafka	High-throughput event streams
System.Threading.Channels	In-memory backpressure pipeline
TPL Dataflow	Actor-style pipelines and transformations

✅ Summary: Async ≠ Asynchronous System

Concept	`async/await`	Event-Driven Messaging
Thread release	✅ Yes	✅ Yes
Non-blocking	✅	✅
Decoupled systems	❌	✅
Fault isolation	❌	✅
Eventual consistency	❌	✅
Retry logic	❌ (manual)	✅ (built-in)
Scalable architecture	⚠️ Limited	✅ Horizontal scale ready

🧠 Final Thought

"async/await makes your code non-blocking, but only messaging and event-driven design make your architecture asynchronous."

As engineers, it's vital we understand this distinction. Use async/await to improve responsiveness. But when building resilient, scalable systems use queues, events, and asynchronous communication models to truly decouple and future-proof your system.

LinkedIn Account : LinkedIn
Twitter Account: Twitter
Credit: Graphics sourced from Dictionary.com

DEV Community: Odumosu Matthew

Why Records Are the Better Choice for Clean, Modern, and Principle-Driven .NET Development

🚚 What Are DTOs in Practice?

🔍 The Real Problems with Class-Based DTOs

1. Mutability is a liability at boundaries

2. Reference equality is the wrong equality

3. The boilerplate hides the contract

4. Nothing communicates intent

✨ Enter Records: The Type That Says What It Means

🏦 Records in the Wild: Enterprise Fintech Scenarios

Scenario 1: Idempotent webhook ingestion

Scenario 2: Event-driven architecture on Kafka

Scenario 3: Maker-checker workflows

Scenario 4: End-of-day reconciliation

🧭 How Records Fulfill Software Engineering Principles

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

Liskov Substitution Principle (LSP)

Interface Segregation Principle (ISP)

Dependency Inversion Principle (DIP)

YAGNI (You Aren't Gonna Need It)

DRY (Don't Repeat Yourself)

Principle of Least Astonishment

Fail Fast

DDD: Records are Value Objects

CQS/CQRS alignment

⚡ Performance: What Records Actually Buy You (and What They Don't)

Where records genuinely help

Where you must be honest about costs

⚠️ Limitations and Sharp Edges (Read This Before You Migrate)

1. Do not use records for EF Core entities

2. Collection properties break value equality

3. with is a shallow copy

4. Serializer and framework friction

5. Inheritance equality can surprise you

6. Wide records get unwieldy

7. Migration is not free in a brownfield

🧰 When a Class Is Still the Right Answer

📋 A Practical Decision Guide

🏁 Conclusion: This Was Never About Syntax

🛑 Why Records Are the Better Choice for Clean, Modern, and Principle-Driven .NET Development

🚚 What Are DTOs in Practice?

🔍 The Real Problems with Class-Based DTOs

1. Mutability is a liability at boundaries

2. Reference equality is the wrong equality

3. The boilerplate hides the contract

4. Nothing communicates intent

✨ Enter Records: The Type That Says What It Means

🏦 Records in the Wild: Enterprise Fintech Scenarios

Scenario 1: Idempotent webhook ingestion

Scenario 2: Event-driven architecture on Kafka

Scenario 3: Maker-checker workflows

Scenario 4: End-of-day reconciliation

🧭 How Records Fulfill Software Engineering Principles

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

Liskov Substitution Principle (LSP)

Interface Segregation Principle (ISP)

Dependency Inversion Principle (DIP)

YAGNI (You Aren't Gonna Need It)

DRY (Don't Repeat Yourself)

Principle of Least Astonishment

Fail Fast

DDD: Records are Value Objects

CQS/CQRS alignment

⚡ Performance: What Records Actually Buy You (and What They Don't)

Where records genuinely help

Where you must be honest about costs

⚠️ Limitations and Sharp Edges (Read This Before You Migrate)

1. Do not use records for EF Core entities

2. Collection properties break value equality

3. with is a shallow copy

4. Serializer and framework friction

5. Inheritance equality can surprise you

6. Wide records get unwieldy

7. Migration is not free in a brownfield

🧰 When a Class Is Still the Right Answer

📋 A Practical Decision Guide

🏁 Conclusion: This Was Never About Syntax

The Missing Row: Auto-Provisioning Derived Records Without the Race Condition

3. `with` is a shallow copy

3. `with` is a shallow copy

The `equals()` and `hashCode()` Question

🚫 Mistake 1: Not Using `AsNoTracking()` for Read-Only Queries

🧼 Mistake 3: Keeping `DbContext`Alive Too Long