Mapper configuration

The MapperAttribute provides options to customize the generated mapper class.

Copy behavior

By default, Mapperly does not create deep copies of objects to improve performance. If an object can be directly assigned to the target, it will do so (eg. if the source and target type are both Car[], the array and its entries will not be cloned). To create deep copies, set the UseDeepCloning property on the MapperAttribute to true.

[Mapper(UseDeepCloning = true)]
public partial class CarMapper
{
  ...
}

Properties / fields

On each mapping method declaration, property and field mappings can be customized. If a property or field on the target has a different name than on the source, the MapPropertyAttribute can be applied. See also the documentation on flattening / unflattening.

[Mapper]
public partial class CarMapper
{
    [MapProperty(nameof(Car.Model), nameof(CarDto.ModelName))]
    public partial CarDto ToDto(Car car);
}

Ignore properties / fields

To ignore a property or field, the MapperIgnoreTargetAttribute or MapperIgnoreSourceAttribute can be used.

[Mapper]
public partial class CarMapper
{
    [MapperIgnoreTarget(nameof(CarDto.MakeId))]
    [MapperIgnoreSource(nameof(Car.Id))]
    public partial CarDto ToDto(Car car);
}

Ignore obsolete members

By default, Mapperly will map source/target members marked with ObsoleteAttribute. This can be changed by setting the IgnoreObsoleteMembersStrategy of a method with MapperIgnoreObsoleteMembersAttribute, or by setting the IgnoreObsoleteMembersStrategy option of the MapperAttribute.

Name	Description
None	Will map members marked with the Obsolete attribute (default)
Both	Ignores source and target members with the Obsolete attribute
Source	Ignores source members with the Obsolete attribute
Target	Ignores target members with the Obsolete attribute

Global (mapper level)

Sets the IgnoreObsoleteMembersStrategy for all methods within the mapper, by default it is None allowing obsolete source and target members to be mapped. This can be overriden by individual mapping methods using MapperIgnoreObsoleteMembersAttribute.

[Mapper(IgnoreObsoleteMembersStrategy = IgnoreObsoleteMembersStrategy.Both)]
public partial class CarMapper
{
    ...
}

Local (mapping method level)

Method will use the provided ignore obsolete mapping strategy, otherwise the MapperAttribute property IgnoreObsoleteMembersStrategy will be used.

[Mapper]
public partial class CarMapper
{
    [MapperIgnoreObsoleteMembers(IgnoreObsoleteMembersStrategy.Both)]
    public partial CarMakeDto MapMake(CarMake make);
}

Property name mapping strategy

By default, property and field names are matched using a case sensitive strategy. If all properties/fields differ only in casing, for example ModelName on the source and modelName on the target, the MapperAttribute can be used with the PropertyNameMappingStrategy option.

[Mapper(PropertyNameMappingStrategy = PropertyNameMappingStrategy.CaseInsensitive)]
public partial class CarMapper
{
    public partial CarDto ToDto(Car car);
}

public class Car
{
    public string ModelName { get; set; }
}

public class CarDto
{
    public string modelName { get; set; }
}

null values

Mapperly allows the customization of how null values are handled when mapping properties.

AllowNullPropertyAssignment allows to configure whether null values are assigned to nullable target properties. If it is true and the source value is null, the target property is explicitly set to null. If it is false, the property mapping is ignored or an exception is thrown, depending on the value of ThrowOnPropertyMappingNullMismatch. AllowNullPropertyAssignment is true by default.

ThrowOnPropertyMappingNullMismatch controls how null source values are handled, if the target property is not nullable or AllowNullPropertyAssignment is set to false. If ThrowOnPropertyMappingNullMismatch is enabled, an ArgumentNullException is thrown. If ThrowOnPropertyMappingNullMismatch is disabled, the property mapping is ignored. ThrowOnPropertyMappingNullMismatch is false by default.

For mapping methods the behaviour can be specified via ThrowOnMappingNullMismatch. When the mapper tries to return a null value from a mapping method with a non-nullable return type, and ThrowOnMappingNullMismatch is set to false, Mapperly tries to return a default value. For strings the default value is the empty string, for value types, it is default, for reference types with a public parameterless constructor, a new instance is created. If no such constructor exists an ArgumentNullException is thrown. If ThrowOnMappingNullMismatch is true (default), an ArgumentNullException is thrown.

info

AllowNullPropertyAssignment, ThrowOnPropertyMappingNullMismatch and ThrowOnMappingNullMismatch are ignored for required init properties and IQueryable<T> projection mappings.

Strict property mappings

To enforce strict mappings (all source members have to be mapped to a target member and all target members have to be mapped from a source member, except for ignored members) set the following two EditorConfig settings (see also analyzer diagnostics):

.editorconfig

[*.cs]
dotnet_diagnostic.RMG012.severity = error # Unmapped target member
dotnet_diagnostic.RMG020.severity = error # Unmapped source member

Strict enum mappings

To enforce strict enum mappings set RMG037 and RMG038 to error, see strict enum mappings.

Default Mapper configuration

The MapperDefaultsAttribute allows to set default configurations applied to all mappers on the assembly level.

[assembly: MapperDefaults(EnumMappingIgnoreCase = true)]