Jens.EntityMapper 0.1.0

dotnet add package Jens.EntityMapper --version 0.1.0
                    
NuGet\Install-Package Jens.EntityMapper -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Jens.EntityMapper" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Jens.EntityMapper" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Jens.EntityMapper" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Jens.EntityMapper --version 0.1.0
                    
#r "nuget: Jens.EntityMapper, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Jens.EntityMapper@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Jens.EntityMapper&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Jens.EntityMapper&version=0.1.0
                    
Install as a Cake Tool

Jens.EntityMapper

Jens.EntityMapper icon

CI NuGet NuGet downloads License: MIT .NET 8 | 10

A convention-based object-to-object mapper for .NET with mapping profiles and IQueryable projection (ProjectTo) for EF Core.

The API mirrors AutoMapper 14: the types have the same names and signatures, they just live in the Jens.EntityMapper namespace. Existing profiles compile after a change of the using directives and three renames (see Migrating).

  • MIT licensed
  • Targets net8.0 and net10.0
  • One package; the only dependency is Microsoft.Extensions.DependencyInjection.Abstractions

Installation

dotnet add package Jens.EntityMapper

Quick start

using Jens.EntityMapper;

public class EmployeeProfile : Profile
{
    public EmployeeProfile()
    {
        CreateMap<EmployeeDTO, EmployeeModel>()
            .ForMember(m => m.FullName, o => o.MapFrom(d => d.Name))
            .ForMember(m => m.Salary, o => o.MapFrom(d => d.Age > 55 ? d.Salary * 10 : d.Salary))
            .ForMember(m => m.Telephone, o => o.NullSubstitute("Not Available"))
            .ReverseMap();
    }
}
var configuration = new MapperConfiguration(c => c.AddProfile<EmployeeProfile>());
configuration.AssertConfigurationIsValid();

IMapper mapper = configuration.CreateMapper();
EmployeeModel model = mapper.Map<EmployeeModel>(dto);

Dependency injection

// Scans the assembly for profiles, value resolvers and type converters.
services.AddEntityMapper(typeof(EmployeeProfile));

// Or configure explicitly.
services.AddEntityMapper(c => c.AddProfile<EmployeeProfile>());

IConfigurationProvider is registered as a singleton, IMapper as transient (the lifetime can be passed as an argument). Resolvers and converters are created by the container, so they can take constructor dependencies.

Projection with EF Core

using Jens.EntityMapper.QueryableExtensions;

List<OrderDto> orders = await db.Orders
    .Where(o => o.Status == OrderStatus.Shipped)
    .ProjectTo<OrderDto>(mapper.ConfigurationProvider)
    .ToListAsync();

ProjectTo turns the map into a single Select expression, so EF Core reads only the columns the destination type needs. Map and ProjectTo use the same configuration.

In a projection, only configuration that is itself an expression can be used: conventions, flattening, MapFrom(expression), NullSubstitute, Ignore, ConvertUsing(expression), nested maps and collections. Resolvers, converters and function-based MapFrom throw an EntityMapperMappingException when the query is built.

Documentation

The documentation is organised by use case, with code and its real output:

Every snippet comes from a runnable project in samples:

Sample Run it
Basics: mapping objects in memory dotnet run --project samples/Basics
EfCoreProjection: ProjectTo with the generated SQL dotnet run --project samples/EfCoreProjection
WebApi: ASP.NET Core minimal API dotnet run --project samples/WebApi

Features

Area Supported
Configuration Profile, MapperConfiguration, CreateMap (generic and by Type), ReverseMap, AddProfile, AddMaps (assembly scanning), CreateProfile, AllowNullCollections
Member options MapFrom (expression, function, member path, resolver), Ignore, NullSubstitute, Condition, PreCondition, ConvertUsing (value converter)
Null safety A MapFrom expression that runs into a null reference (s => s.Customer.Name + "!" with no customer) yields the default value, as in AutoMapper
Type-level options ConvertUsing (expression, function, ITypeConverter), ValidateMemberList
Conventions Members matched by name (case-insensitive), flattening (Customer.Address.City → CustomerAddressCity), GetX() methods, constructor parameters (records)
Execution Map<TDestination>(source), Map<TSource, TDestination>(source), Map(source, destination), non-generic overloads, per-call options with Items, BeforeMap and AfterMap
Built-in conversions Nullable types, enums (from enum, string or number), ToString, System.Convert, Parse(string), conversion operators, arrays, lists, sets, dictionaries
Projection ProjectTo<T> on IQueryable and on IMapper, non-generic ProjectTo
Extension points IValueResolver, IMemberValueResolver, ITypeConverter, IValueConverter
Validation AssertConfigurationIsValid (unmapped members, duplicate maps, missing nested maps), MemberList.Destination, Source and None
Dependency injection AddEntityMapper with the same overloads as AddAutoMapper

Migrating from AutoMapper

  1. Replace the AutoMapper package reference with Jens.EntityMapper.

  2. Replace using AutoMapper with using Jens.EntityMapper (and AutoMapper.QueryableExtensions with Jens.EntityMapper.QueryableExtensions).

  3. Rename the three identifiers that carry the AutoMapper name. No identifier in this package contains "AutoMapper".

    AutoMapper Jens.EntityMapper
    AutoMapperMappingException EntityMapperMappingException
    AutoMapperConfigurationException EntityMapperConfigurationException
    services.AddAutoMapper(...) services.AddEntityMapper(...)

Behaviour is checked against AutoMapper 14.0.0: the tests in tests/Shared are compiled twice, once against each library, and must pass in both. For ProjectTo, the SQL that EF Core generates for SQL Server is compared with snapshots taken from AutoMapper.

Not supported

This package covers the commonly used core of AutoMapper, not all of it. Code that uses one of the following will not compile or will throw:

  • ForPath, ForSourceMember, ForCtorParam, ConstructUsing
  • BeforeMap / AfterMap on a map (they are available per Map call)
  • Include, IncludeBase, IncludeMembers (a map for a base type is still used for derived source types)
  • PreserveReferences, MaxDepth: circular object graphs are not handled by Map
  • ProjectTo with parameters or membersToExpand: the overloads exist but throw NotSupportedException
  • Open generic maps, value transformers, custom naming conventions, global ignores

Known differences in behaviour:

  • A mapping error is wrapped in an EntityMapperMappingException once, at the member where it happened. AutoMapper adds one wrapper per nesting level.
  • A graph that is nested too deeply for the stack throws InsufficientExecutionStackException (see Security).
  • Type maps are compiled on first use, not when the configuration is created. Call configuration.CompileMappings() at startup to compile them all up front.

Benchmarks

Measured with BenchmarkDotNet 0.15.8 against AutoMapper 14.0.0, using the same models and the same configuration for both libraries (source: benchmarks/Jens.EntityMapper.Benchmarks).

Environment: .NET 10.0.12, X64 RyuJIT, AMD Ryzen 9 9950X3D, Windows 11. Measured on 2026-11-17.

Scenario AutoMapper 14 Jens.EntityMapper Ratio Allocated (AutoMapper → Jens.EntityMapper)
Flat object, 8 members 27.53 ns 15.30 ns 0.56 80 B → 80 B
Flat object onto an existing destination 22.26 ns 13.70 ns 0.62 0 B → 0 B
Flattening (Customer.Address.City) 26.60 ns 15.60 ns 0.59 64 B → 64 B
Object graph: nested object, 10 collection items, MapFrom, NullSubstitute 138.42 ns 118.76 ns 0.86 952 B → 760 B
List of 1,000 flat objects 10.33 µs 10.49 µs 1.02 96.6 KB → 88.1 KB
ProjectTo: building the query (cached projection) 591.8 ns 372.0 ns 0.63 872 B → 616 B
Cold start: create configuration and map two types for the first time 1.566 ms 2.135 ms 1.36 273.6 KB → 271.7 KB

Ratio is Jens.EntityMapper time divided by AutoMapper time; below 1 means faster.

How to read these numbers:

  • They are mean values from one run on one machine. The standard deviation was below 1.4 % of the mean in every scenario.
  • The scenarios use only features both libraries support. AutoMapper has a much larger feature set, and some of the difference per call may be the cost of that.
  • The ProjectTo row measures only the construction of the query expression. Executing the query against a database costs far more and is the same for both, because the generated SQL is the same.
  • Cold start is about a third slower. Jens.EntityMapper compiles a map on first use, AutoMapper compiles all maps when the configuration is created; the benchmark includes both.
  • Every map call checks the remaining stack (see Security). That check is included in these numbers.

To run the benchmarks yourself:

dotnet run -c Release --project benchmarks/Jens.EntityMapper.Benchmarks -- --filter *

Security

AutoMapper 14.0.0 has three known advisories, all for denial of service through uncontrolled recursion: a deeply nested object graph overflows the stack, which terminates the process (CVE-2026-32933, CVE-2026-128081, CVE-2026-128082).

Jens.EntityMapper maps nested objects recursively as well. Every map call, including each nested object, collection element and context.Mapper.Map call, first checks the remaining stack and throws a catchable InsufficientExecutionStackException when it runs low. Graphs 30,000 levels deep through properties, constructor parameters, collections and recursive type converters are covered by tests.

There is no MaxDepth setting and no detection of circular references: mapping an object graph that contains a cycle ends in that exception. If the depth of your input is controlled by a caller, limit it before mapping.

Building

dotnet build Jens.EntityMapper.slnx
dotnet test Jens.EntityMapper.slnx
dotnet pack src/Jens.EntityMapper -c Release -o artifacts

The tests need the .NET 10 SDK. To regenerate the SQL snapshots from AutoMapper, run the reference tests with the environment variable UPDATE_SNAPSHOTS=1.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 50 11/18/2026