NMapper 2.0.16-pre

NMapper

NMapper is a lightweight, explicit object mapping library for .NET. It favours clear, testable mapping code over configuration and conventions.

Key Features

• Explicit mapping classes written in plain C#
• One-way and two-way mappings.
• Supports nested mappings.
• Automatic mapping of collections and arrays.
• Clear compile-time errors instead of runtime surprises.
• No conventions, no reflection-based property mapping, no magic.
• Designed to use with dependency injection (Microsoft.Extensions.DependencyInjection).

Philosophy

Mapping is application logic. NMapper treats mappings as first-class code rather than configuration. Every mapping is explicit, discoverable, and refactor-safe.

NMapper intentionally avoids automatic property matching and hidden behavior in favor of clarity, control, and debuggability.

Download and Install NMapper

This library is available on NuGet: https://www.nuget.org/packages/NMapper/ Use the following command to install NMapper using the NuGet Package Manager Console:

PM> Install-Package NMapper

You can use this library in any .NET project which is compatible to .NET Standard 2.0 and higher.

API Usage

Define a Mapping

Mappings are defined as simple C# classes by implementing IMapping<TSource, TTarget>. This interface gives you the extra parameter IMappingContext which allows to run further mappings.

public class PersonMapping :
    IMapping<Person, PersonDto>,
    IMapping<PersonDto, Person>
{
    public PersonDto Map(Person source) => new()
    {
        Id = source.Id,
        Name = source.Name
    };

    public Person Map(PersonDto source) => new()
    {
        Id = source.Id,
        Name = source.Name
    };
}

Nested Mappings

If a mapping needs to delegate to other mappings, implement IMappingWithContext<TSource, TTarget>.

public class OrderMapping : IMappingWithContext<Order, OrderDto>
{
    public OrderDto Map(Order source, IMappingContext context) => new()
    {
        Id = source.Id,
        Customer = context.Map<CustomerDto>(source.Customer)
    };
}

Register Mappings

Mappings are typically registered via dependency injection.

services.AddMapping(options =>
{
    options.MapperAssemblies = new[]
    {
        typeof(PersonMapping).Assembly
    };
});

Perform Mappings

Create a new instance of Mapper or inject IMapper via dependency injection and use it to perform mappings.

var personDto = mapper.Map<PersonDto>(person);

Mapping Collections and Arrays

Collections and arrays are mapped automatically as long as an element mapping exists.

var personDtos = mapper.Map<IEnumerable<PersonDto>>(persons);

Exceptions

NMapper uses explicit, strongly typed exceptions to make mapping errors easy to diagnose. All exceptions are thrown at runtime and indicate configuration or mapping logic errors.

Thank You

A big thank you to all the people who have contributed to this project! If you find a bug or want to propose a new feature, feel free to open an issue on GitHub.

We'd also like to thank nabinked for leaving us the project name and working title NMapper.