XForge.AutoMapper.Testing 0.23.0

XForge.AutoMapper

<p align="center"> <img src="manual/assets/XForge.png" alt="XForge.AutoMapper" width="128" height="128" /> </p>

Source-generator-first .NET object mapping library — zero reflection, NativeAOT safe, Blazor WASM friendly.

Quick Start

using XForge.AutoMapper;

// Option A: Explicit partial methods
[Mapper]
public partial class CustomerMapper
{
    public partial CustomerDto ToDto(Customer source);
}

// Option B: AutoMapper-style
[Mapper]
[Map(typeof(Customer), typeof(CustomerDto))]
[Map(typeof(Order), typeof(OrderDto))]
public partial class AppMapper { }

// Usage:
var mapper = new AppMapper();
CustomerDto dto = mapper.Map<CustomerDto>(customer);

// Via strongly-typed interface:
IMapper<Customer, CustomerDto> iMapper = mapper;
CustomerDto dto2 = iMapper.Map(customer);

Features

• Source Generation — Primary code generation path, zero reflection on critical path
• NativeAOT & Trimming — Fully compatible with AOT compilation and IL trimming
• Blazor WASM — First-class support for WebAssembly scenarios
• Compile-time Diagnostics — XAM-prefixed warnings and errors before runtime
• AutoMapper-style API — [Map<S,D>] attribute for class-level declarations
• Open Generics Mapping — Generic mapper classes with closed-form generation per type pair
• Multi-Source Mapping — [MapFrom] for merging multiple sources into one destination
• Reverse Mapping — [MapReverse] and GenerateReverse for bidirectional mapping
• Value Converters — [ValueConverter] for property transformation during mapping
• Value Resolvers — [ResolveUsing] for computing destination values from the entire source object
• Conditional Mapping — [MapWhen] to map only when source property is non-null
• Null Substitution — [NullSubstitute] for fallback values on null source properties
• Before/After Hooks — [BeforeMap]/[AfterMap] for side effects and auditing
• LINQ Projection — ProjectTo for IQueryable/EF Core-safe expression trees
• Flattening — Automatic nested-to-flat property mapping via PascalCase matching
• Unflattening — Automatic nested object construction from flat source properties, supports multi-level deep nesting (CustomerAddressStreet → Customer.Address.Street)
• Records & Init-only — Full support for C# records and init-only properties
• Collections — Automatic collection iteration and element mapping
• DI Integration — Optional IServiceCollection registration via assembly scanning
• Testable — MapperAssert helpers for unit testing without DI container

Performance

Benchmarks on .NET 10.0, Windows 11, x64 RyuJIT AVX2. See full results.

• 50,000x faster cold start than AutoMapper (14 ns vs 710 μs)
• 6-8x faster than AutoMapper in steady state
• On par with Mapperly (both source-generated)
• Zero extra allocations vs manual mapping
• NativeAOT safe — no reflection, no runtime code emit

dotnet run --project benchmarks/XForge.AutoMapper.Benchmarks/XForge.AutoMapper.Benchmarks.csproj -c Release -- --filter "*" --job short --memory

Packages

Package	NuGet	Description
XForge.AutoMapper.Abstractions		Contracts, attributes, and interfaces
XForge.AutoMapper		Minimal runtime and mapper base
XForge.AutoMapper.SourceGeneration		Roslyn incremental source generator
XForge.AutoMapper.Analyzers		Roslyn analyzers and code fixes
XForge.AutoMapper.Queryable		IQueryable projection support
XForge.AutoMapper.Extensions.DependencyInjection		DI extensions and assembly scanning
XForge.AutoMapper.Testing		Test helpers (MapperAssert)

Installation

dotnet add package XForge.AutoMapper
dotnet add package XForge.AutoMapper.SourceGeneration

Optional packages:

dotnet add package XForge.AutoMapper.Extensions.DependencyInjection
dotnet add package XForge.AutoMapper.Queryable
dotnet add package XForge.AutoMapper.Testing

Diagnostics

Compile-time diagnostics with the XAM prefix:

Documentation

Complete enterprise-grade manual with examples from basic to advanced:

• Manual Completo (pt-br)
• Full Manual (en-us)

License

MIT