Entities
Entities are one of the core concepts of DDD (Domain Driven Design). Eric Evans describe 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 Framework 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
protectedempty 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 theIGuidGeneratorservice while passing the Id from the code that creates the entity.IGuidGeneratoroptimized 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
}
);
}
}
BookAppServiceinjects the default repository for the book entity and uses itsInsertAsyncmethod to insert aBookto the database.GuidGeneratoris type ofIGuidGeneratorwhich is a property defined in theApplicationServicebase 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.
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 to preserve it's own integrity. This is also true for all entities, but aggregate root has responsibility for it's sub entities too. So, the aggregate root must always be in a valid state.
- An aggregate root can be referenced by it's Id. Do not reference it by it's 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:
Orderhas a public constructor that takes minimal requirements to construct anOrderinstance. 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.OrderLineconstructor is internal, so it is only allowed to be created by the domain layer. It's used inside of theOrder.AddProductmethod.Order.AddProductimplements the business rule to add a product to an order.- All properties have
protectedsetters. This is to prevent the entity from arbitrary changes from outside of the entity. For exmple, it would be dangerous to setTotalItemCountwithout adding a new product to the order. It's value is maintained by theAddProductmethod.
ABP Framework 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.
Base Classes & Interfaces for Audit Properties
There are some properties like CreationTime, CreatorId, LastModificationTime... which are very common in all applications. ABP Framework 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.
IHasCreationTimedefines the following properties:CreationTime
IMayHaveCreatordefines the following properties:CreatorId
ICreationAuditedObjectinherits from theIHasCreationTimeand theIMayHaveCreator, so it defines the following properties:CreationTimeCreatorId
IHasModificationTimedefines the following properties:LastModificationTime
IModificationAuditedObjectextends theIHasModificationTimeand adds theLastModifierIdproperty. So, it defines the following properties:LastModificationTimeLastModifierId
IAuditedObjectextends theICreationAuditedObjectand theIModificationAuditedObject, so it defines the following properties:CreationTimeCreatorIdLastModificationTimeLastModifierId
ISoftDelete(see the data filtering document) defines the following properties:IsDeleted
IHasDeletionTimeextends theISoftDeleteand adds theDeletionTimeproperty. So, it defines the following properties:IsDeletedDeletionTime
IDeletionAuditedObjectextends theIHasDeletionTimeand adds theDeleterIdproperty. So, it defines the following properties:IsDeletedDeletionTimeDeleterId
IFullAuditedObjectinherits from theIAuditedObjectand theIDeletionAuditedObject, so it defines the following properties:CreationTimeCreatorIdLastModificationTimeLastModifierIdIsDeletedDeletionTimeDeleterId
Once you implement any of the interfaces, or derive from a class defined in the next section, ABP Framework automatically manages these properties wherever possible.
Implementing
ISoftDelete,IDeletionAuditedObjectorIFullAuditedObjectmakes 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 theICreationAuditedObjectinterface.AuditedEntity<TKey>andAuditedAggregateRoot<TKey>implement theIAuditedObjectinterface.FullAuditedEntity<TKey>andFullAuditedAggregateRoot<TKey>implement theIFullAuditedObjectinterface.
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> andFullAuditedAggregateRootWithUser<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).
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).
GetPropertyreturnsnullif given property was not set before.- You can store more than one property at the same time by using different property names (like
Titlehere).
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
HasPropertyis used to check if the object has a property set before.RemovePropertyis used to remove a property from the object. You can use this instead of setting anullvalue.
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 nulls.
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
ExtraPropertiesfield as aJSONstring (that means all extra properties stored in a single database table field). Serializing toJSONand deserializing from theJSONare automatically done by the ABP Framework using the value conversions system of the EF Core. - If you want, you can use the
ObjectExtensionManagerto define a separate table field for a desired extra property. Properties those are not configured through theObjectExtensionManagerwill continue to use a singleJSONfield 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 normally don't need to 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.
