ExIgniter.ObjectMapper 2.0 Documentation

Overview

ExIgniter.ObjectMapper 2.0 is a complete redesign of our popular object mapping library, offering:

3x performance improvements through optimized reflection caching
Enhanced property matching algorithms
Support for constructor initialization
Attribute-based configuration
Improved null handling strategies
Backward compatibility with v1.x APIs

Getting Started

Installation

Install via NuGet Package Manager:

Install-Package ExIgniter.ObjectMapper

Or via .NET CLI:

dotnet add package ExIgniter.ObjectMapper

Basic Usage

Simple object mapping:

// Basic mapping
var userDto = userEntity.MapTo<UserDto>();

// Collection mapping
List<UserDto> dtos = entities.MapAllTo<UserDto>().ToList();

API Reference

Core Methods

TResult MapTo<TResult>()

Maps the source object to a new instance of the specified type.

Parameters: None

Returns: New instance of TResult

var dto = entity.MapTo<UserDto>();

TResult MapTo<TResult>(MapConfig config)

Maps with custom configuration.

Parameters:

config: MapConfig instance

var config = new MapConfig()
    .Ignore(x => x.PasswordHash);
    
var dto = entity.MapTo<UserDto>(config);

MapConfig Class

Configuration options for mapping behavior.

Methods:

Method	Description
`Ignore<T>(Expression<Func<T, object>> expr)`	Ignores specified property
`MapAs<TSource, TDest>(Func<TSource, TDest> converter)`	Custom type converter
`WithNullHandling(NullHandlingStrategy strategy)`	Sets null handling behavior

Mapping Attributes

Attribute	Description
`[MapIgnore]`	Excludes property from mapping
`[MapAs("PropertyName")]`	Maps to different target property
`[MapConstructor]`	Marks constructor for auto-mapping

Migration Guide

Breaking Changes

Note: While v2.0 maintains backward compatibility, these changes might affect edge cases.

Map<T>() is now MapTo<T>() (old version still supported)
Default null handling now throws exceptions (was silent in v1.x)
Collection mapping now returns IEnumerable<T> instead of concrete List

Deprecated Features

The following v1.x features are deprecated but still functional:

FasterMap() - Use MapTo() with performance config
ComplexMap() - Use MapTo() with deep mapping config
String-based property exclusion - Use lambda expressions

Advanced Usage

Performance Tuning

For maximum performance:

// Reuse config instances
var config = new MapConfig()
    .WithNullHandling(NullHandlingStrategy.UseDefaultValue)
    .CacheMappings(); // Enable type cache

// For hot paths
var fastMapper = config.CreateMapper<Source, Dest>();
var result = fastMapper.Map(source);

Custom Mappings

Implement complex transformations:

var config = new MapConfig()
    .MapAs<DateTime, string>(d => d.ToString("yyyy-MM-dd"))
    .MapAs<Address, string>(a => $"{a.Street}, {a.City}");

var result = source.MapTo<Destination>(config);