Mapperly Documentation

Mapperly is a .NET source generator designed to automate object-to-object mappings. Instead of writing tedious boilerplate code by hand, you only need to define the method signature for the mapping, and Mapperly generates the implementation at build time.

Key characteristics:

• Build-time generation: Code is generated during compilation, resulting in minimal runtime overhead.
• No Reflection: Because it avoids reflection, it is fully trimming-safe and AoT (Ahead-of-Time) friendly.
• Readable & Debuggable: The generated code is standard C# that you can inspect and debug.
• Zero Runtime Dependency: Mapperly does not require a runtime library to function.
• Pluggable: You can implement specific mappings manually, and Mapperly will pick them up and use them during the generation process.

Mapperly is distributed through two channels:

• Stable Channel: Production-ready releases subject to semantic versioning. Use this for production environments.
• Next Channel: Preview releases containing upcoming features. These may contain breaking changes and are not subject to semantic versioning. Use this for testing and early access.

Mapperly supports IQueryable<T> projections, which is highly effective for optimizing ORM performance (e.g., with Entity Framework). Only the fields present in the target class are retrieved from the database.

To implement this, define a partial method in your mapper that extends IQueryable<TSource> and returns IQueryable<TTarget>.

[Mapper]
public static partial class CarMapper
{
    public static partial IQueryable<CarDto> ProjectToDto(this IQueryable<Car> q);
}

// Usage
var dtos = await DbContext.Cars
    .Where(...)
    .ProjectToDto()
    .ToListAsync();

To execute custom code during a mapping process, wrap the generated mapping method inside a manual method. Use the [UserMapping(Default = true)] attribute on your manual method to ensure Mapperly uses this wrapper instead of calling the generated partial method directly when a conversion is required.

[Mapper]
public partial class CarMapper
{
    private partial CarDto CarToCarDto(Car car);

    // Default ensures Mapperly uses this mapping whenever a conversion
    // from Car to CarDto is needed instead of the `CarToCarDto` method.
    [UserMapping(Default = true)]
    public CarDto MapCarToCarDto(Car car)
    {
        // custom before map code...
        var dto = CarToCarDto(car);
        // custom after map code...
        return dto;
    }
}

To define a mapper, create a partial class and decorate it with the [Mapper] attribute from Riok.Mapperly.Abstractions. Define your mapping logic as partial methods. Mapperly will generate the implementation for these methods at build time.

// Mapper declaration
[Mapper]
public partial class CarMapper
{
    public partial CarDto CarToCarDto(Car car);
}

// Mapper usage
var mapper = new CarMapper();
var car = new Car { NumberOfSeats = 10, ... };
var dto = mapper.CarToCarDto(car);
dto.NumberOfSeats.ShouldBe(10);

To install Mapperly, add a NuGet reference to the Riok.Mapperly package.

To ensure Mapperly does not add unnecessary runtime dependencies to your project, it is recommended to use ExcludeAssets="runtime" and PrivateAssets="all" in your project file.

If the target type of a mapping is unknown at compile time, you can define a mapping method that accepts a Type parameter. Mapperly will implement this by using the user-defined mappings available in the mapper.

[Mapper]
public static partial class ModelMapper
{
    public static partial object Map(object source, Type targetType);

    private static partial BananaDto MapBanana(Banana source);
    private static partial AppleDto MapApple(Apple source);
}

class Banana {}
class Apple {}

class BananaDto {}
class AppleDto {}

When mapping between API models and domain objects, use separate mappers for different directions to correctly apply RequiredMappingStrategy:

• API Requests → Domain Objects: Use RequiredMappingStrategy.Source to ensure all fields in the request are consumed.
• Domain Objects → API Responses: Use RequiredMappingStrategy.Target to ensure all fields in the response are populated.

[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Source)]
public partial class RequestMapper
{
    public partial CreateOrderCommand MapRequest(CreateOrderRequest source);
}

[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)]
public partial class ResponseMapper
{
    public partial GetOrderResponse MapResponse(Order source);
}