CQRS in .NET with MediatR

Command and Query Responsibility Segregation (CQRS) gives .NET applications two deliberate paths for handling work. A command expresses an intention to change state, while a query asks for information without changing it. Keeping those responsibilities apart can make complex business rules easier to enforce and high-volume reporting easier to optimise. CQRS does not require event sourcing: many implementations use relational databases, domain events and read-model projections without storing an event log.

MediatR is a .NET mediator library that connects requests to handlers through dependency injection. Controllers, background workers or service layers publish IRequest and INotification messages, while specialised command handlers and query handlers perform the work. This in-process messaging style removes direct handler lookups from application code and creates a useful seam for validation, logging, authorisation and transaction boundaries.

For Australian development teams, the pattern is relevant wherever products combine transactional APIs with dashboards, mobile clients and operational reporting. Banks, health providers, logistics firms, retailers and mining businesses often operate across Sydney, Melbourne, Brisbane and Perth, so system boundaries and data visibility matter as much as raw throughput. A measured CQRS design can improve those workloads while remaining grounded in Australian privacy, security and cloud-residency expectations.

Why CQRS fits complex .NET systems

A conventional ASP.NET Core controller commonly calls one application service, which both mutates entities and returns data. That arrangement works well for modest CRUD applications, but it tends to pull a large object graph, authorisation rules and reporting concerns into the same path. As a system grows, queries may accidentally track entities, lock rows or return more fields than a client needs.

Separating commands from queries creates explicit boundaries. The write side validates a command, loads aggregate state, enforces invariants and commits a change. The read side retrieves purpose-built records shaped for a screen or integration. Each side can then evolve independently: commands can become richer domain workflows, while queries can use indexed tables, caches or search indexes optimised for retrieval.

This separation does not automatically reduce complexity. Teams need two models, projection logic and a strategy for stale data. It is most valuable when read and write pressures genuinely differ; a small application with one workflow can often remain simpler without CQRS. In Australian enterprise systems, the trade-off becomes easier when a reusable platform pattern serves several products rather than one bespoke API.

Commands, queries, and the domain model

Start with language that reflects business intent. A PlaceOrderCommand can carry an order identifier, customer details and line items, while RenameProductCommand carries the product identifier and new name. Handlers own the transaction and return a small result, such as an order number or failure reason. A command should not double as a general-purpose data container, because that weakens the boundary between intent and persistence.

Queries should return immutable response records rather than tracked EF Core entities. For example, OrderSummaryResponse can expose an order date, status and total, while SalesByRegionResponse contains only the fields needed by a chart. Read handlers can use AsNoTracking, projection-to-DTO queries, pagination and cancellation tokens. This prevents a view endpoint from accidentally invoking domain behaviour or triggering a lazy database query.

Aggregate changes can publish domain events inside the write transaction. Those events may update local projections, feed search indexes or communicate with external systems. Australian geographical scale makes delivery semantics important: a warehouse team near Perth may lose connectivity while a customer in Brisbane completes an order. Retrying, idempotent consumers and an outbox reduce the risk of lost work or duplicate effects when networks are unreliable or teams work in different time zones.

MediatR registration and request pipelines

MediatR keeps dispatch explicit without coupling callers to concrete handlers. Register the assembly containing requests and handlers with the service collection, resolve IMediator or ISender in the caller, and send a request. The caller knows the message, not the implementation. Keep controllers thin by translating HTTP input into a command or query, then map the result to an HTTP response. Background workers can publish the same request types through the mediator.

With a shared persistence model, the write handler may use EF Core to load and save entities, while the query handler selects directly into response records. Separate DbContext instances and read-only queries make the distinction visible. When the workloads diverge, the read handler can target a denormalised projection or cache instead. Each handler should have one clear reason to exist rather than becoming another arbitrary service layer.

MediatR pipeline behaviours provide a cross-cutting place for validation, authorisation, logging, metrics and exception mapping. A validation behaviour can reject malformed commands before a handler runs, while an audit behaviour records who initiated a sensitive change. Register behaviours in dependency-injection order and use scoped services where DbContext or tenant context is required. Cancellation tokens should flow through Send, handlers and database calls so abandoned requests stop consuming resources.

Designing reliable read models

A reliable write path should commit the domain change and any outgoing message atomically. The transactional outbox pattern stores integration events in the same database transaction as the aggregate update. A background publisher then sends pending events to a broker and records their delivery. Consumers must be idempotent because an at-least-once broker can redeliver a message after a timeout. Deduplication keys and versioned projections make replay safe.

Read models can be updated synchronously for simple cases, but asynchronous projection is common when reporting needs differ from transactional data. Consumers apply events in sequence, store a checkpoint and rebuild projections when the model changes. Until the projection catches up, users may see a slightly older state. Product interfaces should make that delay acceptable or offer a freshness indicator, and support staff need a way to inspect lag rather than infer it from user reports.

Performance tuning belongs on both sides. Batch projection updates, avoid unbounded event handlers and keep read queries selective. A read replica or Azure-hosted projection can reduce pressure on the primary database, especially for high-volume dashboards. Choosing the Australia East, Australia Southeast or Australia Central region can keep compute and data closer to users and regulated workloads, although residency does not remove the need for contractual controls, monitoring and a documented recovery strategy.

Testing, security, and operations

Testing CQRS is simpler when each request has a narrow contract. Unit tests can exercise command handlers with a focused test double for the repository, while query tests verify filters, authorisation and DTO mapping. Integration tests using a real database through Testcontainers can catch translation mistakes that mocks miss. Contract tests are valuable for events and external consumers, since a renamed property can otherwise break a projection several releases later.

Security checks belong in the command path and must also constrain read access by tenant, role or purpose. Australian organisations subject to the Privacy Act 1988 must align collection, use, disclosure and security with the Australian Privacy Principles; APP 11 addresses security and APP 12 requires a privacy policy. The ASD Essential Eight provides another practical baseline for patching, access control, logging and backups. Legal and compliance teams should confirm how cloud telemetry, support access and cross-border processing fit those obligations.

Operations need visibility across both paths. Carry a correlation identifier from ASP.NET Core request to handler, database command, outbox message and projection, then export traces and metrics through OpenTelemetry. Alert on command failures, outbox age, projection lag and dead-letter volume. At the edge, apply ASP.NET Core rate limiting before requests reach MediatR, protecting shared infrastructure without embedding throttling rules inside domain handlers.

Adopt the pattern incrementally. A single bounded context can begin with separate command and query handlers over existing tables, then gain projections only when evidence supports them. MediatR provides the dispatch and pipeline mechanics, but sound aggregates, explicit contracts, resilient messaging and disciplined observability determine whether the resulting architecture is dependable.