ElBruno.AotMapper.EntityFramework 0.6.0

ElBruno.AotMapper

AOT-friendly compile-time DTO mapper for .NET 🗺️

ElBruno.AotMapper is a Roslyn-based source-generator library that creates compile-time DTO mapping code for .NET. No runtime reflection, no dynamic IL emission—just fast, AOT-safe, and predictable generated mappers. Perfect for NativeAOT deployments, trimmed applications, and cloud-native workloads.

Why ElBruno.AotMapper?

• Compile-time generation — All mapping logic is generated during build; zero runtime reflection in the happy path
• AOT & Trimming safe — Works seamlessly with NativeAOT and assembly trimming
• Strong diagnostics — Clear compile-time errors for incomplete or ambiguous mappings
• Performance parity — Generated code stays within 5–15% of hand-written mapping
• EF Core friendly — Optional projection helpers for supported query patterns
• ASP.NET Core ready — Dependency injection helpers for easy service registration

Packages

Package	NuGet	Downloads	Description
ElBruno.AotMapper			Core attributes and abstractions
ElBruno.AotMapper.Generator			Roslyn incremental source generator (dev dependency)
ElBruno.AotMapper.AspNetCore			DI registration and ASP.NET Core extensions
ElBruno.AotMapper.EntityFramework			EF Core integration and projection helpers

Why ElBruno.AotMapper vs AutoMapper / Mapperly?

Choosing a mapper depends on your scenario. Here's how we compare:

Choose ElBruno.AotMapper if:

• You need NativeAOT deployment or strict trimming
• You want compile-time safety with strong diagnostics
• You're building cloud-native or serverless workloads (less startup time, smaller memory footprint)
• You appreciate minimal dependencies for simple scenarios

Choose AutoMapper if:

• You need maximum configurability (convention-based mapping, conditional mapping, etc.)
• Your codebase is not targeting NativeAOT
• You want battle-tested maturity and extensive plugin ecosystem

Choose Mapperly if:

• You want compile-time generation like ElBruno.AotMapper but don't need EF projection helpers
• You prefer attribute-free or profile-based mapping rules

Quick Start

Installation

Install the core package and the generator (as a dev dependency):

dotnet add package ElBruno.AotMapper
dotnet add package ElBruno.AotMapper.Generator

Define a Mapping

Annotate your destination DTO class with [MapFrom]:

using ElBruno.AotMapper;

// Source entity
public class Customer
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Tier { get; set; }
}

// Destination DTO with mapping attribute
[MapFrom(typeof(Customer))]
public sealed partial record CustomerDto(string Id, string Name, string Tier);

Build & Use

Just build your project—the generator creates extension methods automatically:

var customer = new Customer { Id = "123", Name = "Alice", Tier = "Gold" };

// Generated extension method
CustomerDto dto = customer.ToCustomerDto();

// Also works with LINQ queries (when using ElBruno.AotMapper.EntityFramework)
IQueryable<CustomerDto> dtos = context.Customers.ProjectToCustomerDto();

For more details, see Getting Started Guide.

Supported Mappings

ElBruno.AotMapper supports:

• Classes, records, and structs — All reference and value types
• Nested objects — Recursive mapping of complex object graphs
• Collections — Arrays, List<T>, IEnumerable<T>, and other collection types
• Enums — Enum-to-string and string-to-enum conversion helpers
• Nullable reference types — Full nullability awareness and validation
• Custom property rules — Remap properties, set defaults, and ignore fields
• Partial method hooks — Optional pre/post-mapping customization
• EF Core projections — Safe query translation for supported patterns

See Supported Mappings for complete details and examples.

Core Package: ElBruno.AotMapper

The core package provides the mapping attributes and lightweight abstractions.

dotnet add package ElBruno.AotMapper

Key attributes:

• [MapFrom(Type)] — Mark destination type as mappable from a source type
• [MapProperty(sourceProperty, destinationProperty)] — Remap a property
• [MapIgnore] — Skip a property in the mapping
• [MapConverter] — Specify a custom type converter

No runtime dependencies; works standalone in any .NET project.

Generator Package: ElBruno.AotMapper.Generator

The Roslyn incremental source generator that creates mapping code at compile time. Install as a dev dependency:

dotnet add package ElBruno.AotMapper.Generator --prerelease

The generator:

• Scans for [MapFrom] attributes during build
• Generates strongly-typed extension methods (e.g., ToCustomerDto())
• Emits compile-time diagnostics for incomplete or invalid mappings
• Works with incremental builds for fast iteration

ASP.NET Core Package: ElBruno.AotMapper.AspNetCore

Streamline dependency injection and ASP.NET Core integration:

dotnet add package ElBruno.AotMapper.AspNetCore

Usage:

Register mappers in your service collection:

var builder = WebApplication.CreateBuilder(args);

// Add AOT mapper services
builder.Services.AddAotMapper();

var app = builder.Build();
// ... your endpoints

Generated mappers are then available as extension methods or injected services.

Entity Framework Core Package: ElBruno.AotMapper.EntityFramework

Simplify EF Core query projections with AOT-safe mappers:

dotnet add package ElBruno.AotMapper.EntityFramework

Usage:

Use generated extension methods for in-memory mapping, or manual Select for projections:

[MapFrom(typeof(Customer))]
public sealed partial record CustomerDto(string Id, string Name, string Tier);

// In-memory mapping (generated extension method)
var dtos = customers.Select(c => c.ToCustomerDto()).ToList();

// EF Core projection (manual Select for SQL translation)
var projected = context.Customers
    .Select(c => new CustomerDto(c.Id, c.Name, c.Tier.ToString()))
    .ToListAsync();

Important: EF projection support is limited to patterns that translate safely to SQL. See EF Integration Guide for supported and unsupported scenarios.

Building from Source

Clone the repository and build with .NET 8 SDK or later:

git clone https://github.com/elbruno/ElBruno.AotMapper.git
cd ElBruno.AotMapper

# Restore dependencies
dotnet restore ElBruno.AotMapper.slnx

# Build
dotnet build ElBruno.AotMapper.slnx

# Run tests
dotnet test ElBruno.AotMapper.slnx

The solution file (ElBruno.AotMapper.slnx) includes all library, test, and sample projects.

Documentation

• Quick Start Guide — Installation, basic usage, first mapping
• Supported Mappings — Complete feature matrix and examples
• Known Limitations — Current constraints and workarounds
• Diagnostics Reference — All diagnostic IDs and remediation steps
• EF Core Integration — Projection helpers and query translation
• Migration Guide — Migrating from AutoMapper or manual mapping

License

This project is licensed under the MIT License. See LICENSE for details.

👋 About the Author

Made with ❤️ by Bruno Capuano (ElBruno)

• 📝 Blog: elbruno.com
• 📺 YouTube: youtube.com/elbruno
• 🔗 LinkedIn: linkedin.com/in/elbruno
• 𝕏 Twitter: twitter.com/elbruno
• 🎙️ Podcast: notienenombre.com

Acknowledgments

This library is built on Roslyn and inspired by the .NET ecosystem's move toward compile-time solutions for NativeAOT and trimmed applications. Special thanks to the .NET community for feedback and contributions.