dotnet-cqrs/.claude/rules/commands-queries.md

---
paths:
  - "*Command*.cs"
  - "*Query*.cs"
  - "*Handler*.cs"
  - "**/Program.cs"
  - "**/ServiceCollectionExtensions.cs"
---

# Commands & Queries

## Commands Are Domain Actions, Not CRUD

Commands express **user intent**. Name them as the business action being performed.

- `PlaceOrderCommand` not `CreateOrderCommand`
- `ApproveExpenseCommand` not `UpdateExpenseCommand`
- `DeactivateAccountCommand` not `DeleteAccountCommand`

One CRUD "Update" often becomes multiple distinct commands, each with its own validation and side effects.

## File Structure

Command, handler, and validator live in the **same file**, organized by feature:

```csharp
// File: Features/Orders/PlaceOrderCommand.cs
public record PlaceOrderCommand
{
    public string CustomerId { get; set; } = string.Empty;
    public List<OrderItem> Items { get; set; } = [];
}

public class PlaceOrderCommandValidator : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
    }
}

public class PlaceOrderCommandHandler : ICommandHandler<PlaceOrderCommand, int>
{
    public Task<int> HandleAsync(PlaceOrderCommand command, CancellationToken cancellationToken = default)
    {
        // implementation
    }
}
```

## Handler Interfaces

```csharp
// Command with no result
ICommandHandler<TCommand>
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default)

// Command with result
ICommandHandler<TCommand, TResult>
    Task<TResult> HandleAsync(TCommand command, CancellationToken cancellationToken = default)

// Query (always returns result) — only for single-entity lookups or non-queryable data
IQueryHandler<TQuery, TResult>
    Task<TResult> HandleAsync(TQuery query, CancellationToken cancellationToken = default)
```

## Registration

```csharp
// Command without result
services.AddCommand<DeactivateAccountCommand, DeactivateAccountCommandHandler>();

// Command with result
services.AddCommand<PlaceOrderCommand, int, PlaceOrderCommandHandler>();

// Command with result + validator (from Svrnty.CQRS.FluentValidation)
services.AddCommand<PlaceOrderCommand, int, PlaceOrderCommandHandler, PlaceOrderCommandValidator>();

// Regular query — ONLY for single-entity lookups or non-queryable results
services.AddQuery<FetchOrderByIdQuery, Order, FetchOrderByIdQueryHandler>();
```

## When to Use Regular IQueryHandler vs Dynamic Query

**Use `IQueryHandler`** (rare):
- Single entity by ID: `FetchOrderByIdQuery`
- Non-entity results: `GetDashboardStatsQuery`
- Complex aggregation not expressible as IQueryable

**Use Dynamic Query** (default — see dynamic-query.md rule):
- Any list/collection query
- Anything that needs pagination, filtering, or sorting

## Rules

- Always use `CancellationToken` — never omit it
- Commands/queries are `record` types with `{ get; set; }` properties
- Default string properties to `string.Empty`, collections to `[]`
- Naming: endpoint name is auto-derived by stripping `Command`/`Query` suffix and converting to lowerCamelCase