Skip to content
Skills Library
Programming · Building & coding

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

Repository
abp-skills ↗
Licence
MIT
Last repository change
05.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.

Licence

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

  1. When to Use
  2. When Not to Use
  3. How it works
  4. Validation
  5. Common Pitfalls
Original SKILL.md headings · 154 lines, 853 words
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).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.