Skip to main content

Introduction

Codecov GitHub license GitHub stars GitHub last commit GitHub issues

High-Level Purpose​

The main goal is to provide a set of reusable, opinionated building blocks that solve common problems in web API development. By using these packages, you can:

  • Reduce Boilerplate Code: Automate repetitive tasks like setting up logging, authentication, API documentation, and error handling.
  • Enforce Consistency: Ensure that all parts of your application follow the same patterns for logging, configuration, and API responses.
  • Promote Clean Architecture: The packages are designed to guide you toward a Vertical Slice Architecture using the CQRS (Command Query Responsibility Segregation) pattern. This helps you build features that are self-contained and easier to maintain.
  • Improve Developer Experience: Simplify complex configurations and provide clear, injectable services for common needs.

Solution Structure​

RA.Utilities/
├── 📄 RA.sln
├── 📄 .editorconfig
├── 📄 Directory.Build.props
├── 📄 Directory.Build.targets
├── 📄 Directory.Packages.props
│
├── 📁 Api/
│   ├── 📁 RA.Utilities.Api/
│   ├── 📁 RA.Utilities.Api.Middlewares/
│   ├── 📁 RA.Utilities.Api.Results/
│   ├── 📁 RA.Utilities.Authentication.JwtBearer/
│   ├── 📁 RA.Utilities.Authorization/
│   └── 📁 RA.Utilities.OpenApi/
│
├── 📁 Application/
│   └── 📁 RA.Utilities.Feature/
│
├── 📁 Core/
│   ├── 📁 RA.Utilities.Core/
│   ├── 📁 RA.Utilities.Core.Constants/
│   └── 📁 RA.Utilities.Core.Exceptions/
│
├── 📁 Data/
│   ├── 📁 RA.Utilities.Data.Abstractions/
│   ├── 📁 RA.Utilities.Data.Entities/
│   └── 📁 RA.Utilities.Data.EntityFramework/
│
├── 📁 Infrastructure/
│   └── 📁 RA.Utilities.Integrations/
│
├── 📁 Logging/
│   ├── 📁 RA.Utilities.Logging.Core/
│   └── 📁 RA.Utilities.Logging.Shared/
│
└── 📁 documentation/

Here’s how the folders map to architectural layers:

  • Api/: This solution folder contains all projects related to the web layer. This includes the main API setup, custom middlewares, authentication/authorization helpers, and OpenAPI (Swagger) configuration. This aligns perfectly with the API & Web concern.

  • Application/: This holds the RA.Utilities.Feature project, which is the core of your application logic. As your documentation states, this is where the CQRS pattern is implemented, promoting a Vertical Slice Architecture.

  • Core/: This contains the foundational building blocks of your application that have minimal dependencies. Projects for shared exceptions and constants reside here, which can be referenced by any other project in the solution.

  • Data/: This is your data access layer. It's well-organized with abstractions (RA.Utilities.Data.Abstractions) and a concrete implementation using Entity Framework (RA.Utilities.Data.EntityFramework).

  • Infrastructure/: This folder is for projects that interact with external systems. The A.Utilities.Integrations project is a good example, standardizing how you call other APIs.

  • Logging/: You've correctly isolated logging as a cross-cutting concern into its own set of projects, making it easy to manage and configure.

  • documentation/: It's great to see documentation treated as a first-class citizen within the solution structure.

Overall, this is a robust structure for a reusable utilities library. It's clean, scalable, and easy for other developers to understand.

How the Pieces Fit Together​

The solution is broken down into several NuGet packages, each addressing a specific concern:

Layer/ConcernRA.Utilities Package(s)Purpose
API & WebRA.Utilities.Api, RA.Utilities.Api.Middlewares, RA.Utilities.Api.Results, RA.Utilities.OpenApi, RA.Utilities.Authentication.JwtBearer, RA.Utilities.AuthorizationProvides middleware for logging and header validation, automates OpenAPI/Swagger documentation, and simplifies access to authenticated user data.
Application LogicRA.Utilities.FeatureThis is the heart of the CQRS implementation. It provides base classes for your feature "handlers" and a validation pipeline to automatically validate incoming requests.
Core Building BlocksRA.Utilities.Core.Constants, RA.Utilities.Core.ExceptionsOffers shared constants (like HTTP status codes) and a set of standardized exceptions (NotFoundException, ConflictException) to create clear, semantic error handling.
Data AccessRA.Utilities.Data.Abstractions, RA.Utilities.Data.EntityFrameworkProvides abstractions and implementations for talking to the database.
IntegrationsRA.Utilities.IntegrationsSimplifies and standardizes HTTP client calls to external APIs, with built-in support for configuration, logging, and resilience policies.
Core Building BlocksRA.Utilities.Core.Constants, RA.Utilities.Core.ExceptionsOffers shared constants (like HTTP status codes) and a set of standardized exceptions (NotFoundException, ConflictException) to create clear, semantic error handling.
LoggingRA.Utilities.Logging.Core, RA.Utilities.Logging.SharedProvides a one-line setup for production-ready structured logging with Serilog.

In short, RA.Utilities is a "batteries-included" framework for building modern .NET APIs. It provides the foundation for a clean architecture so you can focus more on writing business logic and less on setting up infrastructure.