abp-ddd

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

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