ABP Application Layer Patterns

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

Anti-Patterns to Avoid

Entity name in method: use GetAsync not GetBookAsync
ID inside UpdateDto: pass id as a separate parameter, not inside the DTO
Calling other app services in the same module: use domain services or repositories directly
Using IFormFile/Stream in app service: accept byte[] from controllers instead
Business logic in app service: put it in domain entities or domain services

Application Service Structure

Interface (Application.Contracts)

csharp

public interface IBookAppService : IApplicationService
{
    Task<BookDto> GetAsync(Guid id);
    Task<PagedResultDto<BookListItemDto>> GetListAsync(GetBookListInput input);
    Task<BookDto> CreateAsync(CreateBookDto input);
    Task<BookDto> UpdateAsync(Guid id, UpdateBookDto input);
    Task DeleteAsync(Guid id);
}

Implementation (Application)

csharp

public class BookAppService : ApplicationService, IBookAppService
{
    private readonly IBookRepository _bookRepository;
    private readonly BookManager _bookManager;
    private readonly BookMapper _bookMapper;

    public BookAppService(
        IBookRepository bookRepository,
        BookManager bookManager,
        BookMapper bookMapper)
    {
        _bookRepository = bookRepository;
        _bookManager = bookManager;
        _bookMapper = bookMapper;
    }

    public async Task<BookDto> GetAsync(Guid id)
    {
        var book = await _bookRepository.GetAsync(id);
        return _bookMapper.MapToDto(book);
    }

    [Authorize(BookStorePermissions.Books.Create)]
    public async Task<BookDto> CreateAsync(CreateBookDto input)
    {
        var book = await _bookManager.CreateAsync(input.Name, input.Price);
        await _bookRepository.InsertAsync(book);
        return _bookMapper.MapToDto(book);
    }

    [Authorize(BookStorePermissions.Books.Edit)]
    public async Task<BookDto> UpdateAsync(Guid id, UpdateBookDto input)
    {
        var book = await _bookRepository.GetAsync(id);
        await _bookManager.ChangeNameAsync(book, input.Name);
        book.SetPrice(input.Price);
        await _bookRepository.UpdateAsync(book);
        return _bookMapper.MapToDto(book);
    }
}

Application Service Best Practices

Don't repeat entity name in method names (GetAsync not GetBookAsync)
Accept/return DTOs only, never entities
ID not inside UpdateDto - pass separately
Use custom repositories when you need custom queries, generic repository is fine for simple CRUD
Call UpdateAsync explicitly (don't assume change tracking)
Don't call other app services in same module
Don't use IFormFile/Stream - pass byte[] from controllers
Use base class properties (Clock, CurrentUser, GuidGenerator, L) instead of injecting these services

DTO Naming Conventions

Purpose	Convention	Example
Query input	`Get{Entity}Input`	`GetBookInput`
List query input	`Get{Entity}ListInput`	`GetBookListInput`
Create input	`Create{Entity}Dto`	`CreateBookDto`
Update input	`Update{Entity}Dto`	`UpdateBookDto`
Single entity output	`{Entity}Dto`	`BookDto`
List item output	`{Entity}ListItemDto`	`BookListItemDto`

DTO Location

Define DTOs in *.Application.Contracts project
This allows sharing with clients (Blazor, HttpApi.Client)

Validation

Data Annotations

csharp

public class CreateBookDto
{
    [Required]
    [StringLength(100, MinimumLength = 3)]
    public string Name { get; set; }

    [Range(0, 999.99)]
    public decimal Price { get; set; }
}

Custom Validation with IValidatableObject

Before adding custom validation, decide if it's a domain rule or application rule:

Domain rule: Put validation in entity constructor or domain service (enforces business invariants)
Application rule: Use DTO validation (input format, required fields)

Only use IValidatableObject for application-level validation that can't be expressed with data annotations:

csharp

public class CreateBookDto : IValidatableObject
{
    public string Name { get; set; }
    public string Description { get; set; }

    public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
    {
        if (Name == Description)
        {
            yield return new ValidationResult(
                "Name and Description cannot be the same!",
                new[] { nameof(Name), nameof(Description) }
            );
        }
    }
}

FluentValidation

csharp

public class CreateBookDtoValidator : AbstractValidator<CreateBookDto>
{
    public CreateBookDtoValidator()
    {
        RuleFor(x => x.Name).NotEmpty().Length(3, 100);
        RuleFor(x => x.Price).GreaterThan(0);
    }
}

Error Handling

Business Exceptions

csharp

throw new BusinessException("BookStore:010001")
    .WithData("BookName", name);

Entity Not Found

csharp

var book = await _bookRepository.FindAsync(id);
if (book == null)
{
    throw new EntityNotFoundException(typeof(Book), id);
}

User-Friendly Exceptions

csharp

throw new UserFriendlyException(L["BookNotAvailable"]);

HTTP Status Code Mapping

Status code mapping is configurable in ABP (do not rely on a fixed mapping in business logic).

Exception	Typical HTTP Status
`AbpValidationException`	400
`AbpAuthorizationException`	401/403
`EntityNotFoundException`	404
`BusinessException`	403 (but configurable)
Other exceptions	500

Auto API Controllers

ABP automatically generates API controllers for application services:

Interface must inherit IApplicationService (which already has [RemoteService] attribute)
HTTP methods determined by method name prefix (Get, Create, Update, Delete)
Use [RemoteService(false)] to disable auto API generation for specific methods

Object Mapping (Mapperly / AutoMapper)

ABP supports both Mapperly and AutoMapper integrations. But the default mapping library is Mapperly. You need to first check the project's active mapping library.

Prefer the mapping provider already used in the solution (check existing mapping files / loaded modules).
In mixed solutions, explicitly setting the default provider may be required (see docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md).

Mapperly (compile-time)

Define mappers as partial classes:

csharp

[Mapper]
public partial class BookMapper
{
    public partial BookDto MapToDto(Book book);
    public partial List<BookDto> MapToDtoList(List<Book> books);
}

csharp

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.AddSingleton<BookMapper>();
}

Usage in application service:

csharp

public class BookAppService : ApplicationService
{
    private readonly BookMapper _bookMapper;

    public BookAppService(BookMapper bookMapper)
    {
        _bookMapper = bookMapper;
    }

    public BookDto GetBook(Book book)
    {
        return _bookMapper.MapToDto(book);
    }
}

Note: Mapperly generates mapping code at compile-time, providing better performance than runtime mappers.

AutoMapper (runtime)

If the solution uses AutoMapper, mappings are typically defined in Profile classes and registered via ABP's AutoMapper integration.