Repository Best Practices & Conventions

This document offers best practices for implementing Repository classes in your modules and applications based on Domain-Driven-Design principles.

Ensure you've read the Repositories document first.

Repository Interfaces

  • Do define repository interfaces in the domain layer.
  • Do define a repository interface (like IIdentityUserRepository) and create its corresponding implementations for each aggregate root.
    • Do always use the created repository interface from the application code.
    • Do not use generic repository interfaces (like IRepository<IdentityUser, Guid>) from the application code.
    • Do not use IQueryable<TEntity> features in the application code (domain, application... layers).

For the example aggregate root:

public class IdentityUser : AggregateRoot<Guid>
{
    //...
}
C#

Define the repository interface as below:

public interface IIdentityUserRepository : IBasicRepository<IdentityUser, Guid>
{
    //...
}
C#
  • Do not inherit the repository interface from the IRepository<TEntity, TKey> interface. Because it inherits the IQueryable and the repository should not expose IQueryable to the application.
  • Do inherit the repository interface from IBasicRepository<TEntity, TKey> (as normally) or a lower-featured interface, like IReadOnlyRepository<TEntity, TKey> (if it's needed).
  • Do not define repositories for entities those are not aggregate roots.

Repository Methods

  • Do define all repository methods as asynchronous.
  • Do add an optional cancellationToken parameter to every method of the repository. Example:
Task<IdentityUser> FindByNormalizedUserNameAsync(
    [NotNull] string normalizedUserName,
    CancellationToken cancellationToken = default
);
C#
  • Do add an optional bool includeDetails = true parameter (default value is true) for every repository method which returns a single entity. Example:
Task<IdentityUser> FindByNormalizedUserNameAsync(
    [NotNull] string normalizedUserName,
    bool includeDetails = true,
    CancellationToken cancellationToken = default
);
C#

This parameter will be implemented for ORMs to eager load sub collections of the entity.

  • Do add an optional bool includeDetails = false parameter (default value is false) for every repository method which returns a list of entities. Example:
Task<List<IdentityUser>> GetListByNormalizedRoleNameAsync(
    string normalizedRoleName, 
    bool includeDetails = false,
    CancellationToken cancellationToken = default
);
C#
  • Do not create composite classes to combine entities to get from repository with a single method call. Examples: UserWithRoles, UserWithTokens, UserWithRolesAndTokens. Instead, properly use includeDetails option to add all details of the entity when needed.
  • Avoid to create projection classes for entities to get less property of an entity from the repository. Example: Avoid to create BasicUserView class to select a few properties needed for the use case needs. Instead, directly use the aggregate root class. However, there may be some exceptions for this rule, where:
    • Performance is so critical for the use case and getting the whole aggregate root highly impacts the performance.

See Also

Contributors


Last updated: December 23, 2024 Edit this page on GitHub

Was this page helpful?

Please make a selection.

To help us improve, please share your reason for the negative feedback in the field below.

Please enter a note.

Thank you for your valuable feedback!

Please note that although we cannot respond to feedback, our team will use your comments to improve the experience.

Community Talks

Deep Dive #1: Identity&Account Modules

17 Apr, 17:00
Online
Watch the Event
Boost Your Development
ABP Live Training
Packages
See Trainings
Mastering ABP Framework Book
Do you need assistance from an ABP expert?
Schedule a Meeting
Mastering ABP Framework Book
The Official Guide
Mastering
ABP Framework
Learn More
Mastering ABP Framework Book