faysilalshareef/query-handler

Query Handler — IUnitOfWork with Repository Queries

Core Principles

• Query handlers implement IRequestHandler<TQuery, TOutput> via MediatR
• Use IUnitOfWork with named repository properties (e.g., _unitOfWork.Orders)
• Repository methods encapsulate filtering, pagination, and sorting logic
• List queries use record types with pagination and filter parameters
• Output classes have PageSize, CurrentPage, Total, and collection properties
• Single-entity queries use FindAsync then map to output DTO
• Not-found cases throw domain-specific exceptions (e.g., OrderNotFoundException)
• Primary constructor pattern with field assignment

Key Patterns

IUnitOfWork with Named Repositories

namespace {Company}.{Domain}.Query.Application.Contracts.Repositories;

public interface IUnitOfWork : IDisposable
{
    IOrderRepository Orders { get; }
    IProductRepository Products { get; }
    IOrderItemRepository OrderItems { get; }
    ICategoryRepository Categories { get; }
    Task SaveChangesAsync(CancellationToken cancellationToken = default);
}

Generic Repository Base

namespace {Company}.{Domain}.Query.Application.Contracts.Repositories;

public interface IAsyncRepository<TDomain> where TDomain : class
{
    Task AddAsync(TDomain entity);
    Task AddRangeAsync(IEnumerable<TDomain> entities);
    Task RemoveAsync(TDomain entity);
    Task RemoveRangeAsync(IEnumerable<TDomain> entities);
    Task<TDomain?> FindAsync(Guid id, bool includeRelated = false);
    Task<IEnumerable<TDomain>> GetAllAsync();
    Task<IEnumerable<TResult>> GetAllAsync<TResult>(
        Expression<Func<TDomain, TResult>> target);
    IQueryable<TDomain> GetQueryable();
}

Specific Repository with Query Methods

namespace {Company}.{Domain}.Query.Application.Contracts.Repositories;

public interface IOrderRepository : IAsyncRepository<Order>
{
    Task<GetOrdersOutput> GetOrdersAsync(
        GetOrdersQuery query,
        CancellationToken cancellationToken);
}

List Query — Record with Pagination and Filters

namespace {Company}.{Domain}.Query.Application.Features.Queries;

public record GetOrdersQuery(
    int PageSize,
    int CurrentPage,
    DateTime? CreatedFrom,
    DateTime? CreatedTo,
    OrderStatus? Status,
    string? CustomerName
) : IRequest<GetOrdersOutput>;

List Output — PageSize, CurrentPage, Total, Collection

namespace {Company}.{Domain}.Query.Application.Features.Queries;

public class GetOrdersOutput
{
    public int PageSize { get; set; }
    public int CurrentPage { get; set; }
    public int Total { get; set; }
    public List<OrderOutput> Orders { get; set; } = [];
}

Output DTO — Plain Class with Public Setters

namespace {Company}.{Domain}.Query.Application.Features.Queries;

public class OrderOutput
{
    public Guid Id { get; set; }
    public string CustomerName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public decimal Total { get; set; }
    public OrderStatus Status { get; set; }
    public bool IsActive { get; set; }
    public DateTime CreatedAt { get; set; }
}

List Query Handler — Delegates to Repository

namespace {Company}.{Domain}.Query.Application.Features.Queries;

public class GetOrdersHandler(IUnitOfWork unitOfWork)
    : IRequestHandler<GetOrdersQuery, GetOrdersOutput>
{
    private readonly IUnitOfWork _unitOfWork = unitOfWork;

    public async Task<GetOrdersOutput> Handle(
        GetOrdersQuery query,
        CancellationToken cancellationToken)
    {
        return await _unitOfWork.Orders
            .GetOrdersAsync(query, cancellationToken);
    }
}

Single-Entity Query Handler — FindAsync + Map

namespace {Company}.{Domain}.Query.Application.Features.Queries;

public record GetOrderByIdQuery(Guid Id) : IRequest<OrderOutput>;

public class GetOrderByIdHandler(IUnitOfWork unitOfWork)
    : IRequestHandler<GetOrderByIdQuery, OrderOutput>
{
    private readonly IUnitOfWork _unitOfWork = unitOfWork;

    public async Task<OrderOutput> Handle(
        GetOrderByIdQuery query,
        CancellationToken cancellationToken)
    {
        var order = await _unitOfWork.Orders.FindAsync(query.Id)
            ?? throw new OrderNotFoundException();

        return new OrderOutput
        {
            Id = order.Id,
            CustomerName = order.CustomerName,
            Email = order.Email,
            Total = order.Total,
            Status = order.Status,
            IsActive = order.IsActive,
            CreatedAt = order.CreatedAt
        };
    }
}

Query Handler with Additional Service

public class GetOrderDetailsHandler(
    IUnitOfWork unitOfWork,
    IQueriesService queriesService)
    : IRequestHandler<GetOrderDetailsQuery, OrderDetailsOutput>
{
    private readonly IUnitOfWork _unitOfWork = unitOfWork;
    private readonly IQueriesService _queriesService = queriesService;

    public async Task<OrderDetailsOutput> Handle(
        GetOrderDetailsQuery query,
        CancellationToken cancellationToken)
    {
        var order = await _unitOfWork.Orders.FindAsync(query.Id, true)
            ?? throw new OrderNotFoundException();

        var extraInfo = await _queriesService
            .GetAdditionalInfo(order.ExternalId);

        return new OrderDetailsOutput { /* map fields */ };
    }
}

Handler Architecture

| Query Type | Pattern | Returns | |---|---|---| | List with pagination | Delegate to repository method | GetOrdersOutput with Total, PageSize, CurrentPage | | Single by ID | FindAsync + map to output | Output DTO or throw NotFoundException | | Single by field | Repository-specific method | Output DTO or throw NotFoundException | | With external data | Additional service injection | Combined output |

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | ApplicationDbContext injected directly | Use IUnitOfWork with named repositories | | Paginated<T> generic wrapper | Output class with PageSize, CurrentPage, Total, collection | | AsNoTracking() in handlers | Tracking handled at repository/infrastructure level | | Filtering logic in handlers | Repository methods encapsulate all query logic | | Returning entities from queries | Map to output DTOs in handler | | record output types | class output types with { get; set; } properties |

Detect Existing Patterns

# Find query handlers
grep -r "IRequestHandler<.*Query" --include="*.cs" Application/Features/Queries/

# Find IUnitOfWork usage in queries
grep -r "_unitOfWork\." --include="*.cs" Application/Features/Queries/

# Find output classes
grep -r "public class.*Output" --include="*.cs" Application/Features/Queries/

# Find repository interfaces with query methods
grep -r "Task<Get.*Output>" --include="*.cs" Application/Contracts/

Adding to Existing Project

1. Use IUnitOfWork with named repository properties, not DbContext
2. List queries delegate to repository methods that return typed output
3. Single queries use FindAsync then map to output DTO in handler
4. Output classes use class with PageSize, CurrentPage, Total, and collection
5. Query records use record type with filter parameters as nullable
6. Place in Application/Features/Queries/{Area}/{QueryName}/ directory
7. One folder per query containing Query, Handler, Output, and any DTOs