ABP DDD Patterns

Docs: https://abp.io/docs/latest/framework/architecture/domain-driven-design

Anti-Patterns to Avoid

Anemic entities: public setters with no behavior — use private setters + methods that enforce invariants
Repository for child entities: only aggregate roots get repositories — access child entities through their root
Generating GUID in entity constructor: use IGuidGenerator from outside and pass id parameter
Navigation properties to other aggregates: reference by Id only, never add full navigation properties across aggregates
Domain service depending on current user: accept values from the application layer instead

Rich Domain Model vs Anemic Domain Model

ABP promotes Rich Domain Model pattern where entities contain both data AND behavior:

Anemic (Anti-pattern)	Rich (Recommended)
Entity = data only	Entity = data + behavior
Logic in services	Logic in entity methods
Public setters	Private setters with methods
No validation in entity	Entity enforces invariants

Encapsulation is key: Protect entity state by using private setters and exposing behavior through methods.

Entities

Entity Example (Rich Model)

csharp

public class OrderLine : Entity<Guid>
{
    public Guid ProductId { get; private set; }
    public int Count { get; private set; }
    public decimal Price { get; private set; }

    protected OrderLine() { } // For ORM

    internal OrderLine(Guid id, Guid productId, int count, decimal price) : base(id)
    {
        ProductId = productId;
        SetCount(count); // Validates through method
        Price = price;
    }

    public void SetCount(int count)
    {
        if (count <= 0)
            throw new BusinessException("Orders:InvalidCount");
        Count = count;
    }
}

Aggregate Roots

Aggregate roots are consistency boundaries that:

Own their child entities
Enforce business rules
Publish domain events

csharp

public class Order : AggregateRoot<Guid>
{
    public string OrderNumber { get; private set; }
    public Guid CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public ICollection<OrderLine> Lines { get; private set; }

    protected Order() { } // For ORM

    public Order(Guid id, string orderNumber, Guid customerId) : base(id)
    {
        OrderNumber = Check.NotNullOrWhiteSpace(orderNumber, nameof(orderNumber));
        CustomerId = customerId;
        Status = OrderStatus.Created;
        Lines = new List<OrderLine>();
    }

    public void AddLine(Guid lineId, Guid productId, int count, decimal price)
    {
        // Business rule: Can only add lines to created orders
        if (Status != OrderStatus.Created)
            throw new BusinessException("Orders:CannotModifyOrder");

        Lines.Add(new OrderLine(lineId, productId, count, price));
    }

    public void Complete()
    {
        if (Status != OrderStatus.Created)
            throw new BusinessException("Orders:CannotCompleteOrder");

        Status = OrderStatus.Completed;

        // Publish events for side effects
        AddLocalEvent(new OrderCompletedEvent(Id));           // Same transaction
        AddDistributedEvent(new OrderCompletedEto { OrderId = Id }); // Cross-service
    }
}

Domain Events

AddLocalEvent() - Handled within same transaction, can access full entity
AddDistributedEvent() - Handled asynchronously, use ETOs (Event Transfer Objects)

Entity Best Practices

Encapsulation: Private setters, public methods that enforce rules
Primary constructor: Enforce invariants, accept id parameter
Protected parameterless constructor: Required for ORM
Initialize collections: In primary constructor
Virtual members: For ORM proxy compatibility
Reference by Id: Don't add navigation properties to other aggregates
Don't generate GUID in constructor: Use IGuidGenerator externally

Repository Pattern

When to Use Custom Repository

Generic repository (IRepository<T, TKey>): Sufficient for simple CRUD operations
Custom repository: Only when you need custom query methods

Interface (Domain Layer)

csharp

// Define custom interface only when custom queries are needed
public interface IOrderRepository : IRepository<Order, Guid>
{
    Task<Order> FindByOrderNumberAsync(string orderNumber, bool includeDetails = false);
    Task<List<Order>> GetListByCustomerAsync(Guid customerId, bool includeDetails = false);
}

Repository Best Practices

One repository per aggregate root only - Never create repositories for child entities
Child entities must be accessed/modified only through their aggregate root
Creating repositories for child entities breaks data consistency (bypasses aggregate root's business rules)
In ABP, use AddDefaultRepositories() without includeAllEntities: true to enforce this
Define custom repository only when custom queries are needed
ABP handles CancellationToken automatically; add parameter only for explicit cancellation control
Single entity methods: includeDetails = true by default
List methods: includeDetails = false by default
Don't return projection classes
Interface in Domain, implementation in data layer

csharp

// ✅ Correct: Repository for aggregate root (Order)
public interface IOrderRepository : IRepository<Order, Guid> { }

// ❌ Wrong: Repository for child entity (OrderLine)
// OrderLine should only be accessed through Order aggregate
public interface IOrderLineRepository : IRepository<OrderLine, Guid> { } // Don't do this!

Domain Services

Use domain services for business logic that:

Spans multiple aggregates
Requires repository queries to enforce rules

csharp

public class OrderManager : DomainService
{
    private readonly IOrderRepository _orderRepository;
    private readonly IProductRepository _productRepository;

    public OrderManager(
        IOrderRepository orderRepository,
        IProductRepository productRepository)
    {
        _orderRepository = orderRepository;
        _productRepository = productRepository;
    }

    public async Task<Order> CreateAsync(string orderNumber, Guid customerId)
    {
        // Business rule: Order number must be unique
        var existing = await _orderRepository.FindByOrderNumberAsync(orderNumber);
        if (existing != null)
        {
            throw new BusinessException("Orders:OrderNumberAlreadyExists")
                .WithData("OrderNumber", orderNumber);
        }

        return new Order(GuidGenerator.Create(), orderNumber, customerId);
    }

    public async Task AddProductAsync(Order order, Guid productId, int count)
    {
        var product = await _productRepository.GetAsync(productId);
        order.AddLine(productId, count, product.Price);
    }
}

Domain Service Best Practices

Use *Manager suffix naming
No interface by default (create only if needed)
Accept/return domain objects, not DTOs
Don't depend on authenticated user - pass values from application layer
Use base class properties (GuidGenerator, Clock) instead of injecting these services

Domain Events

Local Events

csharp

// In aggregate
AddLocalEvent(new OrderCompletedEvent(Id));

// Handler
public class OrderCompletedEventHandler : ILocalEventHandler<OrderCompletedEvent>, ITransientDependency
{
    public async Task HandleEventAsync(OrderCompletedEvent eventData)
    {
        // Handle within same transaction
    }
}

Distributed Events (ETO)

For inter-module/microservice communication:

csharp

// In Domain.Shared
[EventName("Orders.OrderCompleted")]
public class OrderCompletedEto
{
    public Guid OrderId { get; set; }
    public string OrderNumber { get; set; }
}

Specifications

Reusable query conditions:

csharp

public class CompletedOrdersSpec : Specification<Order>
{
    public override Expression<Func<Order, bool>> ToExpression()
    {
        return o => o.Status == OrderStatus.Completed;
    }
}

// Usage
var orders = await _orderRepository.GetListAsync(new CompletedOrdersSpec());