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)
- Local (mapping method 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
{
...
}
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.
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):
[*.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)]