Mapster Documentation

Benchmarks are categorized by the complexity of the object shapes being mapped:

• FlatTypes: Maps Person -> PersonDTO. A simple property-to-property copy with no nested objects or collections. Highlights mapper call overhead and IL quality.
• ComplexTypes: Maps Customer -> CustomerDTO. Includes nested address mapping, array/list shape changes, and flattening rules (e.g., AddressCity <- Address.City). Represents typical DTOs with nested objects and collections.
• RecursiveTypes: Maps Foo -> FooDTO. Uses a self-recursive type where an object can contain itself or collections of itself. Highlights performance in deep mapping graphs.
• TotalAllTypes: A batch scenario that runs FlatTypes, RecursiveTypes, and ComplexTypes sequentially.

To enable injecting services into your mapping configurations, install the Mapster.DependencyInjection NuGet package.

PM> Install-Package Mapster.DependencyInjection

For properties that are truly readonly (no setter at all, only a getter), you can annotate the property with the [UseDestinationValue] attribute. This tells Mapster to use the existing value of the destination object instead of trying to set it.

public class Order {
    public string Id { get; set; }

    [UseDestinationValue]
    public ICollection<OrderItem> Items { get; } = new List<OrderItem>();
}

Mapster's default behavior is to forward property types to their corresponding DTO types (e.g., ICollection<Enrollment> becomes ICollection<EnrollmentDto>). You can override this behavior using the [PropertyType(typeof(Target))] attribute, which can be applied to either a class or a specific property.

[AdaptTo("[name]Dto")]
public class Student {
    public ICollection<Enrollment> Enrollments { get; set; }
}

[AdaptTo("[name]Dto"), PropertyType(typeof(DataItem))]
public class Enrollment {
    [PropertyType(typeof(string))]
    public Grade? Grade { get; set; }
}

Mapster treats C# Records as immutable types. When mapping to a record, Mapster performs a non-destructive mutation, effectively creating a new object with modified properties.

In Mapster v10.0+, all C# Records are treated as record types by default, removing previous limitations regarding constructor counts and parameter matching found in older versions.

When you need to map an object from a POCO to a DTO and back from the DTO to the POCO, you can use the .TwoWays() method. This allows you to define a mapping rule once, and Mapster will automatically apply the reverse mapping.

Important: You must call .TwoWays() before defining specific .Map() rules for them to apply to both directions. Rules defined before calling .TwoWays() will only apply to the initial direction (POCO to DTO).

// This mapping applies to both directions: dto.Code = poco.Id AND poco.Id = dto.Code
TypeAdapterConfig<Poco, Dto>
    .NewConfig()
    .TwoWays()
    .Map(dto => dto.Code, poco => poco.Id);

// Example of order importance:
TypeAdapterConfig<Poco, Dto>
    .NewConfig()
    .Map(dto => dto.Foo, poco => poco.Bar)  // Only applies Poco -> Dto
    .TwoWays()
    .Map(dto => dto.Foz, poco => poco.Baz); // Applies both directions

To generate static extension methods (like AdaptToDto, AdaptTo, and ProjectToDto) for your generated models, you must explicitly call GenerateMapper for each type in your configuration. This works in conjunction with your AdaptFrom, AdaptTo, or AdaptTwoWays declarations.

config.AdaptTo("[name]Dto")
    .ForType<Student>();

config.GenerateMapper("[name]Mapper")
    .ForType<Student>();

Mapster uses standard conversion patterns when mapping to or from strings:

• Type to String: Mapster calls the .ToString() method of the source object.
• String to Type: Mapster calls the .Parse() method of the target type.

var s = 123.Adapt<string>(); //equal to 123.ToString();
var i = "123".Adapt<int>();  //equal to int.Parse("123");

To avoid exceptions caused by re-configuring already compiled configurations, you should separate your configuration logic from your mapping logic.

• Configuration: Define your rules once at the application entry point (e.g., Main, Global.asax.cs, Program.cs, or Startup.cs).
• Mapping: Perform the actual mapping (e.g., using .Adapt<T>()) within your business logic or controllers using the pre-configured instance.

// 1. Configuration (e.g., in Global.asax.cs)
config.ForType<Poco, Dto>().Ignore("Id");

// 2. Mapping (e.g., in a Controller)
var dto1 = poco1.Adapt<Dto>(config);
var dto2 = poco2.Adapt<Dto>(config);

If a type contains no public properties, Mapster may treat it as a primitive type. To ensure non-public members are mapped in such cases, you must both enable non-public members globally (or for the pair) and explicitly declare the type pair configuration.

TypeAdapterConfig.GlobalSettings.Default.EnableNonPublicMembers(true);
TypeAdapterConfig<PrivatePoco, PrivateDto>.NewConfig();

To use run-time data (like the current user's name) during a mapping operation, follow these two steps:

1. Configure the mapping to retrieve the value from MapContext.Current.Parameters using a specific key.
2. Execute the mapping using BuildAdapter() and provide the value via AddParameters(key, value).

This allows you to inject dynamic data that is not present in the source object itself.

// 1. Configuration
TypeAdapterConfig<Poco, Dto>.NewConfig()
                            .Map(dest => dest.CreatedBy,
                                 src => MapContext.Current.Parameters["user"]);

// 2. Execution
var dto = poco.BuildAdapter()
              .AddParameters("user", this.User.Identity.Name)
              .AdaptToType<Dto>();