abp/docs/en/Object-Extensions.md

Object Extensions

ABP Framework provides an object extension system to allow you to add extra properties to an existing object without modifying the related class. This allows to extend functionalities implemented by a depended application module, especially when you want to extend entities and DTOs defined by the module.

Object extension system is not normally not needed for your own objects since you can easily add regular properties to your own classes.

IHasExtraProperties Interface

This is the interface to make a class extensible. It simply defines a Dictionary property:

Dictionary<string, object> ExtraProperties { get; }

Then you can add or get extra properties using this dictionary.

Base Classes

IHasExtraProperties interface is implemented by several base classes by default:

• Implemented by the AggregateRoot class (see entities).
• Implemented by ExtensibleEntityDto, ExtensibleAuditedEntityDto... base DTO classes.
• Implemented by the ExtensibleObject, which is a simple base class can be inherited for any type of object.

So, if you inherit from these classes, your class will also be extensible. If not, you can always implement it manually.

Fundamental Extension Methods

While you can directly use the ExtraProperties property of a class, it is suggested to use the following extension methods while working with the extra properties.

SetProperty

Used to set the value of an extra property:

user.SetProperty("Title", "My Title");
user.SetProperty("IsSuperUser", true);

SetProperty returns the same object, so you can chain it:

user.SetProperty("Title", "My Title")
    .SetProperty("IsSuperUser", true);

GetProperty

Used to read the value of an extra property:

var title = user.GetProperty<string>("Title");

if (user.GetProperty<bool>("IsSuperUser"))
{
    //...
}

• GetProperty is a generic method and takes the object type as the generic parameter.
• Returns the default value if given property was not set before (default value is 0 for int, false for bool... etc).

Non Primitive Property Types

If your property type is not a primitive (int, bool, enum, string... etc) type, then you need to use non-generic version of the GetProperty which returns an object.

HasProperty

Used to check if the object has a property set before.

RemoveProperty

Used to remove a property from the object. Use this methods instead of setting a null value for the property.

Some Best Practices

Using magic strings for the property names is dangerous since you can easily type the property name wrong - it is not type safe. Instead;

• Define a constant for your extra property names
• Create extension methods to easily set your extra properties.

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 easily set or get the Title property:

user.SetTitle("My Title");
var title = user.GetTitle();

Object Extension Manager

While you can set arbitrary properties to an extensible object (which implements the IHasExtraProperties interface), ObjectExtensionManager is used to explicitly define extra properties for extensible classes.

Explicitly defining an extra property has some use cases:

• Allows to control how the extra property is handled on object to object mapping (see the section below).
• Allows to define metadata for the property. For example, you can map an extra property to a table field in the database while using the EF Core.

AddOrUpdate

AddOrUpdate is the main method to define a new extra property or update an extra property definition.