Implementing CQRS with MediatR in C# projects

As C# applications grow, a single service layer can become responsible for too many concerns. It may validate incoming data, coordinate several repositories, publish events, enforce permissions and shape responses for different screens. CQRS, or Command Query Responsibility Segregation, offers a clearer arrangement by separating operations that change state from operations that read it.

MediatR provides a lightweight in-process messaging pattern for this architecture. Commands and queries become focused request objects, while handlers contain the application behaviour for each use case. For teams building systems in Sydney, Melbourne, Brisbane or other Australian technology hubs, this approach can improve maintainability without requiring a distributed microservices platform from the first release.

Why CQRS suits growing C# systems

In a conventional CRUD application, a controller often calls a service that performs both reads and writes against the same domain model. This can work well for a small internal tool. As features expand, read models acquire joins and presentation-specific fields, while write operations become constrained by business rules. The resulting classes are difficult to test because a change for one use case can affect several unrelated paths.

CQRS divides those responsibilities. A command expresses an intention, such as RegisterCustomerCommand or ApproveInvoiceCommand, and changes application state. A query expresses a request for information, such as GetCustomerSummaryQuery, and should have no side effects. The separation does not require two databases. Many projects begin with one SQL Server database and separate handlers, then introduce specialised read stores only when performance or scale justifies it.

This structure is useful in Australian organisations where software frequently integrates with banking, logistics, healthcare or government systems. A customer command might enforce consent and audit requirements, while a query can return a fast dashboard projection without exposing the complete domain entity.

Shaping commands and queries

A request should represent a complete use case rather than a generic database operation. UpdateCustomerCommand is often too broad because different screens may be allowed to change different fields. More precise requests such as ChangeCustomerAddressCommand or SuspendAccountCommand make permissions, validation and auditing easier to understand.

A MediatR request commonly implements IRequest<TResponse>. Its handler implements IRequestHandler<TRequest, TResponse>, which gives the application a predictable entry point. The handler should coordinate domain objects and infrastructure through abstractions, rather than becoming a second controller or directly returning an Entity Framework Core entity.

For queries, response records or dedicated DTOs are usually safer than domain objects. They prevent accidental mutation and allow the SQL projection to match the client’s needs. A reporting query might use AsNoTracking() and select only the columns required by a React interface or a mobile application. This is especially valuable when users connect through variable NBN or mobile networks outside the major metropolitan areas.

Building a MediatR request pipeline

MediatR routes a request to one handler, but the pipeline can apply behaviour shared across many use cases. Common behaviours include FluentValidation checks, structured logging, performance timing, transaction management and idempotency. Register these behaviours in a deliberate order so that failures and metrics are consistent.

For example, a validation behaviour can locate all validators for the current request and return a useful error before the handler touches the database. A logging behaviour can record the request type, correlation ID and elapsed time without logging passwords or personal information. In an Australian production environment, this discipline supports responsible handling of personal data under the Privacy Act and helps teams investigate incidents across Azure services.

A transaction behaviour needs careful boundaries. It can wrap a command that writes several related records, but it should not automatically wrap every query or external API call. A transaction cannot roll back an email sent through a provider or a message already published to a third-party service. Where those actions matter, use an outbox record and publish the event after the database transaction succeeds.

Connecting handlers to persistence

A command handler should express application intent and delegate persistence details to suitable components. For example, CreateOrderCommandHandler can load a customer, ask the domain model to create an order, save changes and record an integration event. It should not contain large blocks of controller-style mapping, raw SQL and unrelated notification code.

Queries can use a different data access route from commands. Entity Framework Core is appropriate for many read cases, while Dapper or database views may be preferable for complex reporting. A read model can combine order, delivery and payment data into one response without forcing the domain model to mirror the shape of a screen.

CQRS also works well with analytics features. A retailer may use a query projection to provide customer activity to a machine-learning workflow, while commands continue to protect transactional rules. When planning predictive services, teams can review Azure churn modelling as an example of how customer data can support retention decisions without placing analytical queries inside transactional handlers.

Managing validation, errors and domain rules

Validation belongs at several levels, with each level serving a different purpose. Request validation can check required fields, formats and simple ranges. Domain rules should protect invariants that must hold regardless of the caller, such as preventing an order from being paid twice. Database constraints provide a final safeguard for uniqueness and referential integrity.

Handlers should translate expected failures into stable application results. A missing customer may become a not-found response, while a rejected business operation may produce a domain error with a code that the API can expose safely. Avoid catching every exception and returning a generic success-shaped response; it hides defects and makes operational diagnosis harder.

Australian systems often need to consider time zones and financial precision. Store timestamps in UTC, convert them for presentation in AEST, AEDT or another relevant zone, and use decimal values for money rather than floating-point numbers. For a payments or payroll workflow, explicitly define how daylight-saving changes in states such as New South Wales and Victoria affect scheduled commands.

Testing and operating the application

MediatR handlers are straightforward to unit test because each handler has a narrow input and output. Tests should verify business outcomes, rejected states and important side effects rather than checking every internal method call. Domain tests can run without a database, while integration tests can confirm EF Core mappings, transactions and query projections against a realistic database engine.

Pipeline behaviours deserve their own tests. Confirm that invalid requests do not reach the handler, transactions commit and roll back correctly, and logging omits sensitive fields. Contract tests can verify that API responses remain compatible with front-end clients, particularly when several teams release on different schedules.

Production monitoring should expose useful dimensions such as request type, duration, failure category and correlation ID. Avoid using raw customer identifiers in metric labels, since high-cardinality telemetry can become expensive and create privacy risks. In an Azure-hosted Australian workload, choose an appropriate local region where availability and data-residency requirements permit, and document how backups, failover and support access are handled.

Avoiding common CQRS mistakes

CQRS is not a requirement to create a separate service for every command. A modular monolith is often the most practical starting point: one deployable application, clear feature folders and an internal mediator. This keeps local development and deployment manageable while preserving boundaries that can later support extraction if a team or workload genuinely needs it.

Another mistake is creating handlers that are too thin to be meaningful. If every handler merely calls a generic repository method, the project has added ceremony without gaining useful separation. Conversely, a handler that performs validation, mapping, database access, messaging and five unrelated decisions should be split around explicit application responsibilities.

Avoid sharing one mutable DTO between commands and queries. Shared contracts can accidentally expose fields or permit updates that were never intended. Also avoid hiding every dependency behind a repository abstraction when EF Core already provides the required behaviour; abstractions should clarify a boundary, not obscure a simple query.

Choosing an approach for your project

The right design depends on business complexity, read/write imbalance and the cost of operational change. A small appointment application may need only conventional services. A platform with complex approvals, audit trails, multiple clients and reporting demands can gain substantial value from command-query separation and MediatR pipeline behaviours.

The following comparison helps position the options before implementation begins. It is usually sensible to introduce CQRS by feature, starting with a workflow that has clear business rules or noticeably different read and write needs.

A useful implementation sequence is to define one command and one query for a bounded feature, add request validators, create focused handlers, and test the resulting workflow end to end. Once the boundaries prove valuable, shared pipeline behaviours and read projections can be introduced with evidence rather than assumption. This keeps the architecture aligned with the needs of the product, its users and the Australian operating environment.