Skip to main content

Core

Namespace: RA.Utilities.Core

The the projects within the Core solution folder (RA.Utilities.Core, RA.Utilities.Core.Constants, and RA.Utilities.Core.Exceptions) serve as the foundational, innermost layer of your Clean Architecture. They are designed to have zero dependencies on any other layer in your solution, which is a critical principle for creating a decoupled and maintainable system.

Here’s how they support the rest of the solution:

1. RA.Utilities.Core - The Heart of Business Logic Communication​

This package contains the fundamental building blocks for your application's logic.

  • Purpose: It provides a way to handle expected operational outcomes (both success and failure) without resorting to throwing exceptions. This is a powerful pattern for distinguishing between predictable failures (e.g., "user not found," "invalid input") and true, unexpected errors.
  • How it Supports Other Layers:
    • Application Layer (RA.Utilities.Feature): Your business logic (CQRS handlers) will create and return Result<T> objects. This allows a handler to clearly communicate "The operation succeeded and here is the data" or "The operation failed for this specific business reason."
    • API Layer (RA.Utilities.Api): The API endpoints receive the Result<T> object from the application layer. As shown The endpoint can then use the .Match() method to transform the result into the appropriate HTTP response (200 OK on success, or a 400 Bad Request/404 Not Found on a predictable failure). This cleanly separates business logic from API concerns.

2. RA.Utilities.Core.Exceptions - Standardizing Unexpected Errors​

This package defines a set of custom, semantic exceptions that represent exceptional, unrecoverable application states.

  • Purpose: To create a standardized vocabulary for exceptional events. When your application logic encounters a situation it cannot recover from (e.g., trying to retrieve an entity that must exist but doesn't), it can throw a specific exception like NotFoundException or ConflictException.
  • How it Supports Other Layers:
    • Application & Data Layers: These layers can throw these exceptions without needing any knowledge of HTTP status codes. For example, a repository can throw NotFoundException("Product", 123) if a product with that ID is not found.
    • API Layer (RA.Utilities.Api): The GlobalExceptionHandler middleware in this layer is specifically designed to catch these custom exceptions. It acts as a translator, converting a NotFoundException into an HTTP 404 Not Found response, and a ConflictException into an HTTP 409 Conflict. This is a perfect example of the API layer adapting core business exceptions into web-specific responses.

3. RA.Utilities.Core.Constants - Eliminating Magic Strings​

This is the simplest but arguably one of the most important packages for maintaining consistency.

  • Purpose: It centralizes shared, static values like configuration keys, header names (X-Request-Id), or policy names.
  • How it Supports Other Layers: Any project that needs to reference a common value can depend on this package. For example:
    • The DefaultHeadersMiddleware in RA.Utilities.Api.Middlewares needs to know the exact string for the X-Request-Id header. Instead of hardcoding it, it can reference a constant from this package.
    • If you have specific claim types or authorization policy names, they would live here and be used by both the RA.Utilities.Authorization package (to define the policy) and the application layer (to require the policy).

Summary​

In essence, the Core packages form the stable, central foundation of your entire ecosystem. They enforce the Dependency Rule of Clean Architecture: all dependencies flow inwards.

  • Api, Data, and Infrastructure all depend on Core.
  • Core depends on nothing.

This structure makes your solution incredibly robust, testable, and easy to reason about. Your business logic remains pure and independent of external details like databases, web frameworks, or logging providers.