Getting Started

Getting Started

Welcome to EntityAxis — a set of libraries that simplify building clean, modular, and testable applications using CQRS, MediatR, EF Core, and FluentValidation.

This guide walks you through setting up your project to consume the EntityAxis libraries and use them effectively.

---

📦 Installation

Install the core libraries via NuGet. These are modular, so you can install only what you need:

dotnet add package EntityAxis.Abstractions
dotnet add package EntityAxis.MediatR
dotnet add package EntityAxis.Registration
dotnet add package EntityAxis.EntityFramework

🧱 Project Setup

EntityAxis encourages a layered architecture. Here's a typical structure:

• Domain: Your core domain entities and interfaces.
• Application: Your CQRS commands, queries, and business rules.
• Infrastructure: Your data access (EF Core), service implementations, and integration.
• Presentation: Web API, Blazor, or Console apps consuming application logic.

EntityAxis packages are designed to slot into the Application and Infrastructure layers.

✍️ Defining Your Entity

Create an entity that implements IEntityId<TKey>:

public class Product : IEntityId<Guid>
{
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

✅ Registering Services

You can register all core services using a fluent extension:

services.AddEntityAxisCommandService<IProductCommandService, ProductService, Product, Guid>();
services.AddEntityAxisQueryService<IProductQueryService, ProductService, Product, Guid>();
services.AddEntityAxisHandlers<ProductCreateModel, ProductUpdateModel, Product, Guid>();

For automatic registration by convention:

services.AddEntityAxisCommandAndQueryServicesFromAssembly<ProductService>();

This scans for any service implementing ICommandService<,> or IQueryService<,> and registers all related interfaces.

⚠️ Version Compatibility Notice

Important: EntityAxis packages are tightly versioned and intended to be used together at the same version.

Because each EntityAxis.* package may reference shared internal types or interact through generic extensions, it's essential that all packages come from the same release version.

✅ When upgrading one package (e.g., EntityAxis.EntityFramework), make sure you upgrade all others (e.g., EntityAxis.MediatR, EntityAxis.Registration) to the exact same version:

# Correct
dotnet add package EntityAxis.Abstractions --version 1.2.0
dotnet add package EntityAxis.EntityFramework --version 1.2.0
dotnet add package EntityAxis.MediatR --version 1.2.0
dotnet add package EntityAxis.Registration --version 1.2.0

# Avoid mixing versions
❌ dotnet add package EntityAxis.MediatR --version 1.2.0
❌ dotnet add package EntityAxis.EntityFramework --version 1.1.0

This is especially important during preview or pre-release development cycles where APIs may evolve across packages.