Transformations.Mapping 3.0.0

Transformations.Mapping

Zero-reflection, NativeAOT-safe object mapper powered by Roslyn source generators. Annotate your partial class and the compiler generates typed To{Target}(), From{Target}(), MapTo(), ToList(), and ProjectTo() methods — no runtime reflection, no IoC wiring.

📖 Overview

Transformations.Mapping replaces runtime reflection mappers with compile-time Roslyn source generators. Annotate your partial class once; the compiler emits typed mapping methods directly into your assembly — no runtime cost, no IoC wiring, no cold-start overhead.

🚀 Why Transformations.Mapping?

Runtime mappers like AutoMapper resolve mappings through reflection at startup: slow on first use, incompatible with NativeAOT/trimming, and silent about broken mappings until production. By shifting all mapping work to the compiler, Transformations.Mapping gives you zero runtime overhead, build-time errors when types fall out of sync, and generated .g.cs files you can actually inspect and debug. The generated code is plain C# — no proxies, no expression trees, nothing magic.

📦 Install

<PackageReference Include="Transformations.Mapping" Version="3.0.0.0" />

The source generator (Transformations.Mapping.Generator) is bundled in the package and activated automatically — no separate installation needed.

🚀 Quick Start

[MapTo<UserDto>]
public partial class User
{
    public int    Id       { get; set; }
    public string Name     { get; set; }
    public DateTime Birthday { get; set; }  // auto-converted to string

    [IgnoreMap]
    public string PasswordHash { get; set; }
}

// Generated at compile time — no reflection, no runtime cost:
UserDto dto        = user.ToUserDto();          // map to new instance
user.MapTo(dto);                                 // update existing instance
User back          = User.FromUserDto(dto);      // reverse map
List<UserDto> dtos = users.ToUserDtoList();      // map a collection
IQueryable<UserDto> q = db.Users.ProjectToUserDto(); // server-side projection

💡 Attributes

Rename example

public partial class User
{
    [MapProperty("DisplayName")]
    public string GlobalName { get; set; }

    [MapProperty("CityName", SourcePath = "Address.City")]
    public Address Address { get; set; }
}

Custom converter example

public partial class User
{
    [MapProperty("StatusLabel", Converter = nameof(FormatStatus))]
    public UserStatus Status { get; set; }

    private static string FormatStatus(UserStatus s) => s.GetEnumDescription();
}

A non-public converter on the [MapTo] source is called through an accessor the generator adds to the partial class (that, and the From<Target>() factory, is why the source must be partial).

🔁 What it converts

Beyond identical and implicitly convertible types, the generator maps: enums (cast, by member name, to and from numbers and strings), nested objects (property by property, including self-referencing types), and collections (arrays, lists, sets and dictionaries, element by element). ProjectTo inlines nested objects and collections so EF Core translates them to SQL. See MAPPING_GUIDE.md for the full rules.

🛠 Diagnostics

The bundled Roslyn analyzer runs at build time and flags mapping problems before they reach production:

Escalate TXMAP001 from warning to build error via MSBuild:

<PropertyGroup>
  <TransformationsMappingUnmappedMembersAsErrors>true</TransformationsMappingUnmappedMembersAsErrors>
</PropertyGroup>

Why Not AutoMapper?

See MAPPING_GUIDE.md for flattening, converters, query projection, and AutoMapper migration notes.
See MAPPING_BENCHMARKS.md for BenchmarkDotNet comparisons.

📦 Dependencies

• Transformations.Core
• Transformations.Mapping.Generator (source generator — bundled, not a runtime dependency)

License

PolyForm Strict 1.0.0 — Copyright © 2026 opentail.net