Query Patterns
Reference for implementing queries with pagination, search, and filtering.
Overview
This skill provides comprehensive guidance for building robust query patterns in enterprise applications. The patterns support efficient data retrieval through pagination, search capabilities, and advanced filtering mechanisms. When implementing GET endpoints that return lists or require sophisticated filtering, these patterns ensure consistent and maintainable code structures.
Usage
The query patterns are designed to work seamlessly with modern .NET frameworks and can be integrated into any application requiring data access operations. The patterns support both single entity retrieval and bulk operations with pagination support.
Implementation Guidelines
- Start with specifications - Define clear query specifications before implementing handlers
- Apply tenant filtering - Ensure all queries respect tenant isolation requirements
- Implement soft delete - Filter out deleted records automatically in all queries
- Use dependency injection - Leverage mediator patterns for clean separation of concerns
- Project to DTOs - Always transform entities to DTOs before returning to clients
Guidelines
Operational Mode
This section outlines the operational guidelines for maintaining query efficiency and data consistency across the application.
Runtime Profile
The following operational principles ensure consistent query performance and data integrity:
- Use specifications - Don't write raw LINQ in handlers
- Tenant filtering is automatic - Framework handles
IHasTenant - Soft delete filtering is automatic - DeletedAt != null filtered out
- Use
[AsParameters]- For query parameters in endpoints - Project to DTOs - Never return entities directly
Examples
List Endpoint
public static RouteHandlerBuilder MapGet{Entities}Endpoint(this IEndpointRouteBuilder endpoints) =>
endpoints.MapGet("/", async (
[AsParameters] Get{Entities}Query query,
IMediator mediator,
CancellationToken ct) => TypedResults.Ok(await mediator.Send(query, ct)))
.WithName(nameof(Get{Entities}Query))
.WithSummary("Get paginated list of {entities}")
.RequirePermission({Module}Permissions.{Entities}.View;
Single Entity Endpoint
public static RouteHandlerBuilder MapGet{Entity}Endpoint(this IEndpointRouteBuilder endpoints) =>
endpoints.MapGet("/{id:guid}", async (
Guid id,
IMediator mediator,
CancellationToken ct) => TypedResults.Ok(await mediator.Send(new Get{Entity}Query(id), ct)))
.WithName(nameof(Get{Entity}Query))
.WithSummary("Get {entity} by ID")
.RequirePermission({Module}Permissions.{Entities}.View;
Key Points
- Use specifications - Don't write raw LINQ in handlers
- Tenant filtering is automatic - Framework handles
IHasTenant - Soft delete filtering is automatic - DeletedAt != null filtered out
- Use
[AsParameters]- For query parameters in endpoints - Project to DTOs - Never return entities directly
=== END ORIGINAL SKILL.md ===