Entities
Entities are one of the core concepts of DDD (Domain Driven Design). Eric Evans describes it as "An object that is not fundamentally defined by its attributes, but rather by a thread of continuity and identity".
An entity is generally mapped to a table in a relational database.
Entity Class
Entities are derived from the Entity<TKey>
class as shown below:
public class Book : Entity<Guid>
{
public string Name { get; set; }
public float Price { get; set; }
}
If you do not want to derive your entity from the base
Entity<TKey>
class, you can directly implementIEntity<TKey>
interface.
Entity<TKey>
class just defines an Id
property with the given primary key type, which is Guid
in the example above. It can be other types like string
, int
, long
, or whatever you need.
Entities with GUID Keys
If your entity's Id type is Guid
, there are some good practices to implement:
- Create a constructor that gets the Id as a parameter and passes to the base class.
- If you don't set a GUID Id, ABP sets it on save, but it is good to have a valid Id on the entity even before saving it to the database.
- If you create an entity with a constructor that takes parameters, also create a
private
orprotected
empty constructor. This is used while your database provider reads your entity from the database (on deserialization). - Don't use the
Guid.NewGuid()
to set the Id! Use theIGuidGenerator
service while passing the Id from the code that creates the entity.IGuidGenerator
optimized to generate sequential GUIDs, which is critical for clustered indexes in the relational databases.
An example entity:
public class Book : Entity<Guid>
{
public string Name { get; set; }
public float Price { get; set; }
protected Book()
{
}
public Book(Guid id)
: base(id)
{
}
}
Example usage in an application service:
public class BookAppService : ApplicationService, IBookAppService
{
private readonly IRepository<Book> _bookRepository;
public BookAppService(IRepository<Book> bookRepository)
{
_bookRepository = bookRepository;
}
public async Task CreateAsync(CreateBookDto input)
{
await _bookRepository.InsertAsync(
new Book(GuidGenerator.Create())
{
Name = input.Name,
Price = input.Price
}
);
}
}
BookAppService
injects the default repository for the book entity and uses itsInsertAsync
method to insert aBook
to the database.GuidGenerator
is type ofIGuidGenerator
which is a property defined in theApplicationService
base class. ABP defines such frequently used base properties as pre-injected for you, so you don't need to manually inject them.- If you want to follow the DDD best practices, see the Aggregate Example section below.
Entities with Composite Keys
Some entities may need to have composite keys. In that case, you can derive your entity from the non-generic Entity
class. Example:
public class UserRole : Entity
{
public Guid UserId { get; set; }
public Guid RoleId { get; set; }
public DateTime CreationTime { get; set; }
public UserRole()
{
}
public override object[] GetKeys()
{
return new object[] { UserId, RoleId };
}
}
For the example above, the composite key is composed of UserId
and RoleId
. For a relational database, it is the composite primary key of the related table. Entities with composite keys should implement the GetKeys()
method as shown above.
Notice that you also need to define keys of the entity in your object-relational mapping (ORM) configuration. See the Entity Framework Core integration document for example.
Also note that Entities with Composite Primary Keys cannot utilize the
IRepository<TEntity, TKey>
interface since it requires a single Id property. However, you can always useIRepository<TEntity>
. See repositories documentation for more.
EntityEquals
Entity.EntityEquals(...)
method is used to check if two Entity Objects are equals.
Example:
Book book1 = ...
Book book2 = ...
if (book1.EntityEquals(book2)) //Check equality
{
...
}
AggregateRoot Class
"Aggregate is a pattern in Domain-Driven Design. A DDD aggregate is a cluster of domain objects that can be treated as a single unit. An example may be an order and its line-items, these will be separate objects, but it's useful to treat the order (together with its line items) as a single aggregate." (see the full description)
AggregateRoot<TKey>
class extends the Entity<TKey>
class. So, it also has an Id
property by default.
Notice that ABP creates default repositories only for aggregate roots by default. However, it's possible to include all entities. See the repositories documentation for more.
ABP does not force you to use aggregate roots, you can in fact use the Entity
class as defined before. However, if you want to implement the Domain Driven Design and want to create aggregate root classes, there are some best practices you may want to consider:
- An aggregate root is responsible for preserving its own integrity. This is also true for all entities, but the aggregate root has responsibility for its sub-entities too. So, the aggregate root must always be in a valid state.
- An aggregate root can be referenced by its
Id
. Do not reference it by its navigation property. - An aggregate root is treated as a single unit. It's retrieved and updated as a single unit. It's generally considered as a transaction boundary.
- Work with sub-entities over the aggregate root- do not modify them independently.
See the entity design best practice guide if you want to implement DDD in your application.
Aggregate Example
This is a full sample of an aggregate root with a related sub-entity collection:
public class Order : AggregateRoot<Guid>
{
public virtual string ReferenceNo { get; protected set; }
public virtual int TotalItemCount { get; protected set; }
public virtual DateTime CreationTime { get; protected set; }
public virtual List<OrderLine> OrderLines { get; protected set; }
protected Order()
{
}
public Order(Guid id, string referenceNo)
{
Check.NotNull(referenceNo, nameof(referenceNo));
Id = id;
ReferenceNo = referenceNo;
OrderLines = new List<OrderLine>();
}
public void AddProduct(Guid productId, int count)
{
if (count <= 0)
{
throw new ArgumentException(
"You can not add zero or negative count of products!",
nameof(count)
);
}
var existingLine = OrderLines.FirstOrDefault(ol => ol.ProductId == productId);
if (existingLine == null)
{
OrderLines.Add(new OrderLine(this.Id, productId, count));
}
else
{
existingLine.ChangeCount(existingLine.Count + count);
}
TotalItemCount += count;
}
}
public class OrderLine : Entity
{
public virtual Guid OrderId { get; protected set; }
public virtual Guid ProductId { get; protected set; }
public virtual int Count { get; protected set; }
protected OrderLine()
{
}
internal OrderLine(Guid orderId, Guid productId, int count)
{
OrderId = orderId;
ProductId = productId;
Count = count;
}
internal void ChangeCount(int newCount)
{
Count = newCount;
}
public override object[] GetKeys()
{
return new Object[] {OrderId, ProductId};
}
}
If you do not want to derive your aggregate root from the base
AggregateRoot<TKey>
class, you can directly implement theIAggregateRoot<TKey>
interface.
Order
is an aggregate root with Guid
type Id
property. It has a collection of OrderLine
entities. OrderLine
is another entity with a composite primary key (OrderId
and ProductId
).
While this example may not implement all the best practices of an aggregate root, it still follows some good practices:
Order
has a public constructor that takes minimal requirements to construct anOrder
instance. So, it's not possible to create an order without an id and reference number. The protected/private constructor is only necessary to deserialize the object while reading from a data source.OrderLine
constructor is internal, so it is only allowed to be created by the domain layer. It's used inside of theOrder.AddProduct
method.Order.AddProduct
implements the business rule to add a product to an order.- All properties have
protected
setters. This is to prevent the entity from arbitrary changes from outside of the entity. For example, it would be dangerous to setTotalItemCount
without adding a new product to the order. Its value is maintained by theAddProduct
method.
ABP does not force you to apply any DDD rule or patterns. However, it tries to make it possible and easier when you do want to apply them. The documentation also follows the same principle.
Aggregate Roots with Composite Keys
While it's not common (and not suggested) for aggregate roots, it is in fact possible to define composite keys in the same way as defined for the mentioned entities above. Use non-generic AggregateRoot
base class in that case.
BasicAggregateRoot Class
AggregateRoot
class implements the IHasExtraProperties
and IHasConcurrencyStamp
interfaces which brings two properties to the derived class. IHasExtraProperties
makes the entity extensible (see the Extra Properties section below) and IHasConcurrencyStamp
adds a ConcurrencyStamp
property that is managed by the ABP to implement the optimistic concurrency. In most cases, these are wanted features for aggregate roots.
However, if you don't need these features, you can inherit from the BasicAggregateRoot<TKey>
(or BasicAggregateRoot
) for your aggregate root.
Base Classes & Interfaces for Audit Properties
There are some properties like CreationTime
, CreatorId
, LastModificationTime
... which are very common in all applications. ABP provides some interfaces and base classes to standardize these properties and also sets their values automatically.
Auditing Interfaces
There are a lot of auditing interfaces, so you can implement the one that you need.
While you can manually implement these interfaces, you can use the base classes defined in the next section to simplify it.
IHasCreationTime
defines the following properties:CreationTime
IMayHaveCreator
defines the following properties:CreatorId
ICreationAuditedObject
inherits from theIHasCreationTime
and theIMayHaveCreator
, so it defines the following properties:CreationTime
CreatorId
IHasModificationTime
defines the following properties:LastModificationTime
IModificationAuditedObject
extends theIHasModificationTime
and adds theLastModifierId
property. So, it defines the following properties:LastModificationTime
LastModifierId
IAuditedObject
extends theICreationAuditedObject
and theIModificationAuditedObject
, so it defines the following properties:CreationTime
CreatorId
LastModificationTime
LastModifierId
ISoftDelete
(see the data filtering document) defines the following properties:IsDeleted
IHasDeletionTime
extends theISoftDelete
and adds theDeletionTime
property. So, it defines the following properties:IsDeleted
DeletionTime
IDeletionAuditedObject
extends theIHasDeletionTime
and adds theDeleterId
property. So, it defines the following properties:IsDeleted
DeletionTime
DeleterId
IFullAuditedObject
inherits from theIAuditedObject
and theIDeletionAuditedObject
, so it defines the following properties:CreationTime
CreatorId
LastModificationTime
LastModifierId
IsDeleted
DeletionTime
DeleterId
Once you implement any of the interfaces, or derive from a class defined in the next section, ABP automatically manages these properties wherever possible.
Implementing
ISoftDelete
,IDeletionAuditedObject
orIFullAuditedObject
makes your entity soft-delete. See the data filtering document to learn about the soft-delete pattern.
Auditing Base Classes
While you can manually implement any of the interfaces defined above, it is suggested to inherit from the base classes defined here:
CreationAuditedEntity<TKey>
andCreationAuditedAggregateRoot<TKey>
implement theICreationAuditedObject
interface.AuditedEntity<TKey>
andAuditedAggregateRoot<TKey>
implement theIAuditedObject
interface.FullAuditedEntity<TKey>
andFullAuditedAggregateRoot<TKey>
implement theIFullAuditedObject
interface.
All these base classes also have non-generic versions to take AuditedEntity
and FullAuditedAggregateRoot
to support the composite primary keys.
All these base classes also have ...WithUser
pairs, like FullAuditedAggregateRootWithUser<TUser>
and FullAuditedAggregateRootWithUser<TKey, TUser>
. This makes possible to add a navigation property to your user entity. However, it is not a good practice to add navigation properties between aggregate roots, so this usage is not suggested (unless you are using an ORM, like EF Core, that well supports this scenario and you really need it - otherwise remember that this approach doesn't work for NoSQL databases like MongoDB where you must truly implement the aggregate pattern). Also, if you add navigation properties to the AppUser class that comes with the startup template, consider to handle (ignore/map) it on the migration dbcontext (see the EF Core migration document).
Caching Entities
ABP provides a Distributed Entity Cache System for caching entities. It is useful if you want to use caching for quicker access to the entity rather than repeatedly querying it from the database.
It's designed as read-only and automatically invalidates a cached entity if the entity is updated or deleted.
See the Entity Cache documentation for more information.
Versioning Entities
ABP defines the IHasEntityVersion
interface for automatic versioning of your entities. It only provides a single EntityVersion
property, as shown in the following code block:
public interface IHasEntityVersion
{
int EntityVersion { get; }
}
If you implement the IHasEntityVersion
interface, ABP automatically increases the EntityVersion
value whenever you update your entity. The initial EntityVersion
value will be 0
, when you first create an entity and save to the database.
ABP can not increase the version if you directly execute SQL
UPDATE
commands in the database. It is your responsibility to increase theEntityVersion
value in that case. Also, if you are using the aggregate pattern and change sub-collections of an aggregate root, it is your responsibility if you want to increase the version of the aggregate root object.
Extra Properties
ABP defines the IHasExtraProperties
interface that can be implemented by an entity to be able to dynamically set and get properties for the entity. AggregateRoot
base class already implements the IHasExtraProperties
interface. If you've derived from this class (or one of the related audit class defined above), you can directly use the API.
GetProperty & SetProperty Extension Methods
These extension methods are the recommended way to get and set data for an entity. Example:
public class ExtraPropertiesDemoService : ITransientDependency
{
private readonly IIdentityUserRepository _identityUserRepository;
public ExtraPropertiesDemoService(IIdentityUserRepository identityUserRepository)
{
_identityUserRepository = identityUserRepository;
}
public async Task SetTitle(Guid userId, string title)
{
var user = await _identityUserRepository.GetAsync(userId);
//SET A PROPERTY
user.SetProperty("Title", title);
await _identityUserRepository.UpdateAsync(user);
}
public async Task<string> GetTitle(Guid userId)
{
var user = await _identityUserRepository.GetAsync(userId);
//GET A PROPERTY
return user.GetProperty<string>("Title");
}
}
- Property's value is object and can be any type of object (string, int, bool... etc).
GetProperty
returnsnull
if given property was not set before.- You can store more than one property at the same time by using different property names (like
Title
here).
It would be a good practice to define a constant for the property name to prevent typo errors. It would be even a better practice to define extension methods to take the advantage of the intellisense. Example:
public static class IdentityUserExtensions
{
private const string TitlePropertyName = "Title";
public static void SetTitle(this IdentityUser user, string title)
{
user.SetProperty(TitlePropertyName, title);
}
public static string GetTitle(this IdentityUser user)
{
return user.GetProperty<string>(TitlePropertyName);
}
}
Then you can directly use user.SetTitle("...")
and user.GetTitle()
for an IdentityUser
object.
HasProperty & RemoveProperty Extension Methods
HasProperty
is used to check if the object has a property set before.RemoveProperty
is used to remove a property from the object. You can use this instead of setting anull
value.
How it is Implemented?
IHasExtraProperties
interface requires to define a Dictionary<string, object>
property, named ExtraProperties
, for the implemented class.
So, you can directly use the ExtraProperties
property to use the dictionary API, if you like. However, SetProperty
and GetProperty
methods are the recommended ways since they also check for null
s.
How is it Stored?
The way to store this dictionary in the database depends on the database provider you're using.
- For Entity Framework Core, here are two type of configurations;
- By default, it is stored in a single
ExtraProperties
field as aJSON
string (that means all extra properties stored in a single database table field). Serializing toJSON
and deserializing from theJSON
are automatically done by the ABP using the value conversions system of the EF Core. - If you want, you can use the
ObjectExtensionManager
to define a separate table field for a desired extra property. Properties those are not configured through theObjectExtensionManager
will continue to use a singleJSON
field as described above. This feature is especially useful when you are using a pre-built application module and want to extend its entities. See the EF Core integration document to learn how to use theObjectExtensionManager
.
- By default, it is stored in a single
- For MongoDB, it is stored as a regular field, since MongoDB naturally supports this kind of extra elements system.
Discussion for the Extra Properties
Extra Properties system is especially useful if you are using a re-usable module that defines an entity inside and you want to get/set some data related to this entity in an easy way.
You typically don't need to use this system for your own entities, because it has the following drawbacks:
- It is not fully type safe since it works with strings as property names.
- It is not easy to auto map these properties from/to other objects.
Extra Properties Behind Entities
IHasExtraProperties
is not restricted to be used with entities. You can implement this interface for any kind of class and use the GetProperty
, SetProperty
and other related methods.