ObjectMap.NET 1.0.6

ObjectMap.NET

A lightweight, convention-based object mapper for modern .NET.

NuGet: ObjectMap.NET
Namespaces: SimpleMapper.*
Target framework: net10.0

ObjectMap.NET is designed for explicit maps — every (source → destination) pair is registered in a profile. Convention handles the common cases; fluent configuration covers the rest.

Installation

dotnet add package ObjectMap.NET

Local project reference:

<ProjectReference Include="path\to\SR.ObjectMapper.NET.csproj" />

Quick start

1. Register the mapper

using SimpleMapper.Mapper.DependencyInjection;
using SimpleMapper.Mapper.Profiles;

services.AddSRSimpleMapper(cfg =>
{
    cfg.RegisterProfile(new MyAppMappingProfile());
});

Optional global settings:

services.AddSRSimpleMapper(cfg =>
{
    cfg.DestinationMemberNaming = NamingConventions.SnakeCaseDestination;
    cfg.EnableAutoFlattening = true;
    cfg.RegisterProfile<MyAppMappingProfile>();
});

2. Define a profile

using SimpleMapper.Mapper.Profiles;

public class MyAppMappingProfile : Profile
{
    protected override void ConfigureMaps()
    {
        CreateMap<OrderDto, OrderEntity>()
            .ForMember(d => d.Total, o => o.MapFrom(s => s.Lines.Sum(l => l.Amount))
            .BeforeMap((dto, entity) => { /* runs before members are assigned */ })
            .AfterMap((dto, entity) => { /* runs after mapping completes */ })
            .ReverseMap();

        CreateMap<LineItemDto, LineItemEntity>();
    }
}

3. Inject and map

public class OrderService(ISRSimpleMapper mapper)
{
    public OrderEntity ToEntity(OrderDto dto) =>
        mapper.Map<OrderDto, OrderEntity>(dto);
}

Core API (ISRSimpleMapper)

Nulls: Map<TSource, TDestination>(source) returns default when source is null.
Map(source, destination) throws ArgumentNullException if either argument is null.

Configuration

MapperConfiguration

Built-in naming conventions (NamingConventions):

• PascalCase — default, same names on both sides.
• SnakeCaseDestination — source PascalCase → destination snake_case (e.g. UserName → user_name).
• SnakeCaseSource — source snake_case → destination PascalCase.

Profile

Override ConfigureMaps() and call CreateMap<TSource, TDestination>() for every pair you map.

Fluent mapping API

CreateMap<TSource, TDestination>()

Registers a one-way map. Matching is by convention (name + compatible types), plus flattening and naming rules below.

ReverseMap()

Registers the inverse map TDestination → TSource.

• Ignored members are mirrored on the reverse map.
• Flattened members are reversed into nested paths (e.g. City → Address.City).
• BeforeMap / AfterMap hooks are copied with swapped (source, destination) arguments so forward hooks run on the correct instances during reverse mapping.

ForMember(dest => dest.Member, opt => { ... })

BeforeMap / AfterMap

CreateMap<Entity, Dto>()
    .BeforeMap((src, dest) => { /* destination exists; members not yet assigned */ })
    .AfterMap((src, dest) => { /* all mapping complete */ });

On create-new maps, BeforeMap runs after an empty destination is created and before any members are assigned.

DisableAutoFlattening()

Disables automatic flattening for a specific map (e.g. when Address.City must not map to City).

Auto-flattening

When enabled, nested scalar properties can populate flat destination members:

// Entity.Address.City  →  FlatDto.City
CreateMap<Entity, FlatDto>();

• Supports multi-level paths (e.g. A.B.C.Name → Name).
• Ambiguous paths (multiple nested matches) throw MappingException — use explicit ForMember or disable flattening.
• Works in runtime mapping, compiled maps, reverse maps, and ProjectTo.

How mapping works

1. Create destination (parameterless constructor, or uninitialized object when none exists).
2. BeforeMap hooks run.
3. Compiled assignment (CompileToExisting) sets scalar and simple custom members.
4. Post-compile runtime handles flatten-reverse members, complex custom MapFrom, nested objects, and collections.
5. AfterMap hooks run.

Collections and nested objects are mapped at runtime using registered element/nested type maps. Flat scalars use compiled expressions for speed.

Collections

• Different element types are mapped element-wise (never copied by reference).
• Register CreateMap<TSourceElement, TDestinationElement> for each element pair.
• Strings are not treated as collections.

CreateMap<OrderDto, OrderEntity>();
CreateMap<LineItemDto, LineItemEntity>();
// OrderDto.Lines → OrderEntity.Lines

Supported targets include List<T>, arrays, ICollection<T>, HashSet<T>, Queue<T>, and Stack<T>.

Mapping into an existing object

mapper.Map(orderDto, trackedEntity);

Use for EF updates: load the entity, map the DTO onto it.

• Flattened reverse members (e.g. City → Address.City) are supported.
• Collection properties are updated via nested mapping (not in the initial convention loop).
• Ignored and explicit ForMember members are respected.

ProjectTo (database projection)

var dtos = dbContext.Orders
    .AsNoTracking()
    .ProjectTo<OrderEntity, OrderDto>(mapper)
    .ToList();

• Builds a cached LINQ expression tree per type map (not per-row Map calls).
• Works with EF Core for convention-based and flattening maps.
• Simple computed MapFrom expressions (e.g. s => s.X * 2) can be included when translatable.
• Throws MappingException at build time when a configured member cannot be translated.
• Arbitrary method calls in MapFrom may build an expression that EF cannot translate to SQL — test your queries.

Prefer ProjectTo for list/query endpoints instead of loading entities and calling Map in memory.

Dependency injection

No changes required beyond registration:

services.AddSRSimpleMapper(cfg => cfg.RegisterProfile(new MyAppMappingProfile>());

ISRSimpleMapper is registered as singleton; MapperConfiguration and compiled maps are built once.

Entity Framework notes

• Updates: Map(dto, trackedEntity) — do not create a new entity and attach.
• Queries: Use ProjectTo with AsNoTracking() for read-only lists.
• Owned types / nested value objects: Ensure your EF model matches flatten paths (e.g. OwnsOne(e => e.Address)).
• Proxies: Nested mapping normalizes Castle.Proxies to base types when resolving nested maps.

Performance guidance

Requirements checklist

1. Register CreateMap<Source, Dest> for every pair you call Map with.
2. Register element maps for collection properties with different element types.
3. Use Ignore() for properties maintained elsewhere (passwords, manual navigations).
4. Use ForMember / MapFrom for computed or renamed members.
5. Use explicit ForMember or DisableAutoFlattening() when flatten paths are ambiguous.

Troubleshooting

License

MIT

Author

Shohanur Rahman
LinkedIn