creating-cqrs-query

Creating a New CQRS Query

Overview

This skill guides you through creating a new CQRS Query in the Tactic Management API. Queries represent read operations that retrieve data without modifying system state (GET endpoints).

When to use this skill:

• Adding a new GET endpoint that retrieves data
• Implementing list/search operations with filtering and pagination
• Creating detail views for entities
• Retrieving reference data or lookup tables
• Any operation that reads from the database without changes

Architecture Context:

• Pattern: CQRS (Command Query Responsibility Segregation) with MediatR
• Stack: .NET 8, Entity Framework Core
• Layers: API → Application → Domain → Infrastructure
• Testing: BDD/GWT pattern with xUnit
• Authorization: Read-based authorization service

---

Complete Implementation Checklist

Phase 1: Define Domain Models

1.1 Create Query Class

Location: src/api/src/TacticManagement.Application/Tactics/Queries/

Queries use the record pattern and implement IRequest<TResponse>:

using MediatR;
using TacticManagement.Application.Tactics.DTOs;

namespace TacticManagement.Application.Tactics.Queries;

/// <summary>
/// Query to retrieve [describe what data is retrieved].
/// </summary>
public record GetSomethingQuery(
    Guid Id,
    string UserId
) : IRequest<SomethingDto>;

Naming Convention:

• Pattern: Get{Noun}Query or Get{Noun}{Qualifier}Query
• Examples: GetTacticByIdQuery, GetUserTacticsQuery, GetTacticTypesQuery
• Always include UserId for authorization
• Include filter/pagination parameters as needed

Query Types:

Single entity retrieval:

public record GetTacticByIdQuery(
    Guid TacticId,
    string UserId
) : IRequest<TacticDetailDto>;

List with filtering and pagination:

public record GetUserTacticsQuery(
    string UserId,
    string? Term,              // Search term
    string? Status,            // Filter by status
    List<int>? TacticTypeIds,  // Filter by types
    int Page,                  // Page number (1-based)
    int PageSize,              // Items per page
    string SortBy,             // Sort field
    string SortOrder           // "asc" or "desc"
) : IRequest<PaginatedResponseDto<TacticListItemDto>>;