Coreplex 1.0.2

Coreplex Class Library Documentation

Overview

Coreplex is a .NET 8 class library providing foundational building blocks for clean architecture applications. It focuses on CQRS (Command Query Responsibility Segregation), MediatR integration, validation, authorization, and global exception handling. The library is designed to reduce boilerplate, enforce consistent architectural practices, and make codebases easier to maintain.

Main Components

1. CQRS Abstractions

ICommandHandler Interfaces

• ICommandHandler<TCommand>

  • Handles commands that do not return a result (Unit).
  • Useful for operations that modify state without returning data (e.g., delete, update).

• ICommandHandler<TCommand, TResponse>

  • Handles commands that return a result.
  • Useful for operations that modify state and return data (e.g., create and return ID).
  • Extends MediatR's IRequestHandler.

IQuery and IQueryHandler Interfaces

• IQuery<TResponse>

  • Represents a query request in a CQRS pattern that expects a response of type TResponse.
  • Used for operations that fetch data without modifying the system's state.

• IQueryHandler<TQuery, TResponse>

  • Handles queries that return a result.
  • Extends MediatR's IRequestHandler.
  • Used exclusively for retrieving data without modifying any state.

IRequireAuthorization

• Marker interface to indicate that a request requires authorization.

2. MediatR Pipeline Behaviors

ValidationBehaviour<TRequest, TResponse>

• Validates incoming commands using FluentValidation before they are handled.
• Executes all registered validators for the request.
• Throws ValidationException if any validation rules fail.
• Only applies to commands (ICommand<TResponse>), not queries.

AuthorizationBehavior<TRequest, TResponse>

• Handles authorization logic before processing a command.
• Uses a custom IAuthorizationService<TRequest> to authorize requests.
• Checks if the request implements IRequireAuthorization.
• Validates the user's identity via IHttpContextAccessor.
• Throws UnauthorizedAccessException if authorization fails.

LoggingBehaviour<TRequest, TResponse>

• Logs request processing and measures execution time.
• Warns if a request takes longer than a threshold (e.g., 3 seconds).
• Uses ILogger and a custom ILoggerService<TRequest> for logging.

3. Exception Handling

CustomExceptionHandler

• Provides global exception handling for the application.
• Logs exceptions and maps them to appropriate HTTP status codes using pattern matching.
• Returns structured ProblemDetails as JSON, including validation errors and trace ID.
• Handles specific exceptions: InternalServerException, ValidationException, BadRequestException, ConflictException, NotFoundException.
• Should be registered in Program.cs for global exception handling:
  • builder.Services.AddExceptionHandler<CustomExceptionHandler>();
  • app.UseExceptionHandler();

BadRequestException

• Custom exception for bad requests.
• Supports error message and optional details.

4. Supporting Interfaces

IAuthorizationService<TRequest>

• Abstracts authorization logic for specific request types.
• Method: Task Authorize(TRequest request, CancellationToken cancellationToken);

ILoggerService<TRequest>

• Abstracts logging logic for requests.

5. Pagination Support

PaginateRequest

• Record type for pagination requests.
• Properties: PageIndex (default 0), PageSize (default 10).

Usage

• Validation: Register validators for your commands. The validation behavior will automatically apply them.
• Authorization: Implement IAuthorizationService<TRequest> for your request types and register them in DI.
• Exception Handling: Register CustomExceptionHandler for global error handling.
• CQRS: Implement command and query handlers using the provided interfaces.
• Logging: Use LoggingBehaviour for request/response logging and performance monitoring.
• Pagination: Use PaginateRequest for paginated queries.

Extensibility

• Add custom pipeline behaviors for additional cross-cutting concerns.
• Extend exception handling for more granular error responses.
• Integrate with other libraries (e.g., AutoMapper, Feature Management) as needed.

Best Practices

• Keep handlers focused on a single responsibility.
• Use FluentValidation for all input validation.
• Centralize authorization logic using the provided interfaces.
• Leverage global exception handling for consistent error responses.
• Use logging and performance monitoring for observability.

References

• MediatR Documentation
• FluentValidation Documentation
• .NET Exception Handling

Coreplex provides a robust, extensible foundation for building maintainable, scalable .NET applications using modern architectural patterns.