extend-objects-with-extra-properties
/extend-objects-with-extra-properties
Add framework-level dynamic properties to any ABP entity or DTO that implements IHasExtraProperties. USE FOR: IHasExtraProperties and ExtraPropertyDictionary; ExtensibleObject and extensible aggregate roots/DTOs; ObjectExtensionManager definitions; GetProperty/SetProperty; EF Core JSON or dedicated-column persistence; MongoDB extra elements; mapping extra properties between entities and DTOs. DO NOT USE FOR: extending an installed Identity, Account, or other pre-built module through its module-specific extension configurator (use customize-application-modules); ordinary object mapping without
- Author
- abpframework ↗
- Repository
- abp-skills ↗
- Licence
- MIT
- Last repository change
- 05.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Add framework-level dynamic properties to any ABP entity or DTO that implements IHasExtraProperties. USE FOR: IHasExtraProperties and ExtraPropertyDictionary; ExtensibleObject and extensible aggregate roots/DTOs; ObjectExtensionManager definitions; GetProperty/SetProperty; EF Core JSON or dedicated-column persistence; MongoDB extra elements; mapping extra properties between entities and DTOs. DO NOT USE FOR: extending an installed Identity, Account, or other pre-built module through its module-specific extension configurator (use customize-application-modules); ordinary object mapping without
Original author description
Add framework-level dynamic properties to any ABP entity or DTO that implements IHasExtraProperties. USE FOR: IHasExtraProperties and ExtraPropertyDictionary; ExtensibleObject and extensible aggregate roots/DTOs; ObjectExtensionManager definitions; GetProperty/SetProperty; EF Core JSON or dedicated-column persistence; MongoDB extra elements; mapping extra properties between entities and DTOs. DO NOT USE FOR: extending an installed Identity, Account, or other pre-built module through its module-specific extension configurator (use customize-application-modules); ordinary object mapping without
How it works
- When to Use
- When Not to Use
- How it works
- Validation
- Common Pitfalls
SKILL.md preview
---
name: extend-objects-with-extra-properties
description: >
Add framework-level dynamic properties to any ABP entity or DTO that implements IHasExtraProperties.
USE FOR: IHasExtraProperties and ExtraPropertyDictionary; ExtensibleObject and extensible aggregate roots/DTOs; ObjectExtensionManager definitions; GetProperty/SetProperty; EF Core JSON or dedicated-column persistence; MongoDB extra elements; mapping extra properties between entities and DTOs.
DO NOT USE FOR: extending an installed Identity, Account, or other pre-built module through its module-specific extension configurator (use customize-application-modules); ordinary object mapping without extra properties (use map-objects-and-dtos); designing aggregate invariants and entity relationships (use model-domain-aggregates).
license: MIT
---
# Extending Objects with Extra Properties
`IHasExtraProperties` gives an object an `ExtraPropertyDictionary`, while `ObjectExtensionManager` defines the names, types, defaults, validation metadata, and persistence/mapping metadata for those entries. This is framework-level object extension, not the module-specific extension API for installed ABP modules.
## When to Use
- Add runtime-defined properties to your own entity, aggregate root, command DTO, or result DTO.
- Read and write typed values without adding CLR properties.
- Persist the dictionary as JSON with EF Core or as MongoDB extra elements.
- Promote selected EF Core extra properties to dedicated columns.
- Copy explicitly defined extra properties between an entity and DTO.
## When Not to Use
- **Customize an installed pre-built module** — use customize-application-modules and its module extension configurator.
- **Map ordinary CLR members** — use map-objects-and-dtos.
- **Design entities, value objects, or aggregate invariants** — use model-domain-aggregates.
## How it works
### Make both ends extensible
`IHasExtraProperties` exposes a read-only `ExtraProperties` property of type `ExtraPropertyDictionary`, which derives from `Dictionary<string, object?>`. ABP aggregate roots already implement it. For a standalone DTO or object, derive from `ExtensibleObject` or implement the interface and initialize the dictionary yourself.
```csharp
using Volo.Abp.Application.Dtos;
using Volo.Abp.Domain.Entities;
using Volo.Abp.ObjectExtending;
public class Product : AggregateRoot<Guid>
{
public string Name { get; private set; }
protected Product()
{
Name = string.Empty;
}
public Product(Guid id, string name) : base(id)
{
Name = name;
}
}
public class ProductDto : ExtensibleObject, IEntityDto<Guid>
{
public Guid Id { get; set; }
public string Name { get; set; } = string.Empty;
}
```
`ExtensibleObject` initializes the dictionary and, by default, fills defaults registered in `ObjectExtensionManager`. `AggregateRoot` and `AggregateRoot<TKey>` do the same.
### Define properties before objects are created or mapped
Define the property for every participating type. Default extra-property mapping checks the source/destination pair, so defining only the entity is not enough for a DTO mapping.
```csharp
using System.ComponentModel.DataAnnotations;
using Volo.Abp.ObjectExtending;
public static class ProductObjectExtensions
{
public const string ManufacturerCode = "ManufacturerCode";
public static void Configure()
{
ObjectExtensionManager.Instance
.AddOrUpdateProperty<Product, string>(
ManufacturerCode,
property => property.Attributes.Add(new StringLengthAttribute(32)))
.AddOrUpdateProperty<ProductDto, string>(
ManufacturerCode,
property => property.Attributes.Add(new StringLengthAttribute(32)));
}
}
```
Run this configuration once during startup and before creating instances that need registered defaults. `ObjectExtensionManager.Instance` is global process state; keep names in constants and make repeated configuration deterministic.
### Read and write values
```csharp
product.SetProperty(ProductObjectExtensions.ManufacturerCode, "ACME-42");
var code = product.GetProperty<string>(
ProductObjectExtensions.ManufacturerCode);
```
- `SetProperty` validates by default through `ExtensibleObjectValidator`; pass `validate: false` only for a deliberate trusted-data path.
- `GetProperty<TProperty>` converts primitive-compatible values through ABP's type helper and returns the supplied/default value when absent.
- `HasProperty` checks dictionary membership; `RemoveProperty` deletes an entry.
### EF Core persistence
`ConfigureByConvention()` includes `TryConfigureExtraProperties()`. For an `IHasExtraProperties` entity, EF Core maps `ExtraProperties` to a column of the same name, converts the dictionary to JSON, and installs a value comparer.
```csharp
builder.ConfigureByConvention();
```
To map one entry to a real column, configure it before model creation:
```csharp
ObjectExtensionManager.Instance.MapEfCoreProperty<Product, string>(
ProductObjectExtensions.ManufacturerCode,
(entityBuilder, propertyBuilder) =>
{
propertyBuilder.HasMaxLength(32);
propertyBuilder.HasColumnName("ManufacturerCode");
});
```
The EF Core JSON converter removes properties mapped to fields/columns from the JSON copy, so the promoted property is not duplicated there. Add a migration after changing the model.
### MongoDB persistence
`BsonClassMap.ConfigureAbpConventions()` calls `AutoMap()` and `TryConfigureExtraProperties()`. For a class that directly declares `ExtraProperties`, ABP maps it as MongoDB extra elements rather than a nested JSON field.
```csharp
classMap.ConfigureAbpConventions();
```
Keep this convention in the MongoDB class-map setup for the entity. The MongoDB implementation deliberately checks the declaring type, so inherited mappings are configured on the declaring class rather than repeatedly on derived maps.
### Map entity extra properties to DTOs
For AutoMapper, opt in on the map:
```csharp
CreateMap<Product, ProductDto>()
.MapExtraProperties();
```
Both types must implement `IHasExtraProperties`. With the default definition checks, the property must be registered for both types unless its `CheckPairDefinitionOnMapping` metadata explicitly relaxes the pair check. Mapperly uses `[MapExtraProperties]` on the mapper class and supports definition checks, ignored names, and mapping to regular CLR properties.
## Validation
- Assert a new extensible object has a non-null `ExtraProperties` dictionary.
- Set and get each property using the expected generic type; verify invalid values fail validation.
- With EF Core, save/reload and inspect the `ExtraProperties` JSON column; for promoted properties, verify the dedicated column and confirm the JSON does not duplicate it.
- With MongoDB, save/reload and verify entries are stored as extra BSON elements.
- Map entity to DTO and back; verify only properties allowed by the definition checks are copied.
## Common Pitfalls
- **Defining the property after constructing objects** — constructor default filling has already run. Configure extensions early.
- **Defining only the entity property** — default entity-to-DTO mapping requires compatible definitions on both sides.
- **Writing directly to the dictionary** — this bypasses `SetProperty` validation. Prefer `SetProperty` for application input.
- **Forgetting `ConfigureByConvention()` in EF Core** — the dictionary converter and object-extension mappings are not applied by that entity configuration.
- **Expecting every extra property to become an EF Core column** — the default is one JSON `ExtraProperties` column; call `MapEfCoreProperty` and add a migration for a dedicated column.
- **Using this generic workflow for a packaged ABP module** — module-specific entity/DTO/UI propagation belongs to customize-application-modules.
Versions
The database has no other skills named extend-objects-with-extra-properties.
Database snapshot: 13.11.2026 · package version 0c2b8c23c38c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100customize-application-modules
Extends or customizes a pre-built ABP module (Identity, Account, etc.) referenced as NuGet packages without editing its source. USE FOR: adding extra entity/DTO properties via the module extension system, mapping extra properties to real EF Core columns, replacing/overriding… - 100map-objects-and-dtos
Maps entities to DTOs (or object-to-object) in an ABP app through the IObjectMapper abstraction. USE FOR: IObjectMapper usage, defining AutoMapper profiles or Mapperly mappers, registering maps with AbpAutoMapperOptions.AddMaps, mapping extra properties, mapping collections,… - 100abp-development-flow
ABP Framework v10.x (10.4–10.6) development flow: adding a new entity end-to-end (Domain → Domain.Shared → repository → EF Core config → migration → Contracts/DTO → object mapping → app service → localization → permission → test). Use when you need the flow for adding a new feature in ABP. - 100abp-object-mapping
ABP Framework v10.x (10.4–10.6) object mapping: IObjectMapper, Mapperly (default since v10.4, MapperBase), AutoMapper profiles, entity↔DTO conversion, AutoMap attributes. Use when you need object mapping or DTO mapping in ABP. - 100dto-and-validation
Use when creating request/response DTOs, applying Symfony Validator constraints, mapping payloads with #[MapRequestPayload]/#[MapQueryString], or mapping DTOs to/from entities. Use when the task mentions DTO, request validation, form input, or the Validator component. - 100laravel-dto
Use when creating a Laravel/PHP DTO with the SimpleDto base class and attribute mapping. For DTOs in other stacks, use the stack-native skill (TypeScript, Python, Rust, Go).