abp-ddd

name	abp-ddd
license	UNLICENSED
description	Use when designing domain layer, creating entities, repositories, or domain services in ABP projects. Covers Entities, Aggregate Roots, value objects, Repositories, Domain Services, Domain Events, and Specifications.

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)

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

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)

// 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

// ✅ 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

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

// 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:

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

Specifications

Reusable query conditions:

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());