Enum mappings

An enum mapping can be customized by setting the strategy to use. Apply the MapEnumAttribute and pass the strategy to be used for this enum. It is also possible to set the strategy for the entire mapper via the MapperAttribute. Available strategies:

Name	Description
ByValue	Matches enum entries by their values (default)
ByValueCheckDefined	Matches enum entries by their values, checks if the target value is defined
ByName	Matches enum entries by their exact names

The IgnoreCase property allows to opt in for case insensitive mappings (defaults to false).

Global (mapper level)

Applied to all enums mapped inside this mapper.

[Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName, EnumMappingIgnoreCase = true)]
public partial class CarMapper
{
    ...
}

Enum (mapping method level)

Applied to the specific enum mapped by this method. Attribute is only valid on mapping method with enums as parameters.

[Mapper]
public partial class CarMapper
{
    [MapEnum(EnumMappingStrategy.ByName, IgnoreCase = true)]
    public partial CarMakeDto MapMake(CarMake make);
}

Enum from/to string naming strategies

Enum from/to strings mappings can be customized by setting the enum naming strategy to be used. You can specify the naming strategy using NamingStrategy in MapEnumAttribute or EnumNamingStrategy in MapperAttribute and MapperDefaultsAttribute. Available naming strategies:

Name	Description
MemberName	Matches enum values using their name. (default)
CamelCase	Matches enum values using camelCase.
PascalCase	Matches enum values using PascalCase.
SnakeCase	Matches enum values using snake_case.
UpperSnakeCase	Matches enum values using UPPER_SNAKE_CASE.
KebabCase	Matches enum values using kebab-case.
UpperKebabCase	Matches enum values using UPPER-KEBAB-CASE.
ComponentModelDescriptionAttribute	Matches enum values using the Description property of the System.ComponentModel.DescriptionAttribute. If the attribute is not present or the property is null, the member name is used.
SerializationEnumMemberAttribute	Matches enum values using the Value property of the System.Runtime.Serialization.EnumMemberAttribute. If the attribute is not present or the property is null, the member name is used.

Note that explicit enum mappings (MapEnumValue) and fallback values (FallbackValue in MapEnum) are not affected by naming strategies.

Global (mapper level)

Applied to all enums mapped inside this mapper.

[Mapper(EnumNamingStrategy = EnumNamingStrategy.SnakeCase)]
public partial class CarMapper
{
    ...
}

Enum (mapping method level)

Applied to the specific enum mapped by this method. Attribute is only valid on mapping method with enums as parameters.

[Mapper]
public partial class CarMapper
{
    [MapEnum(EnumMappingStrategy.ByName, NamingStrategy = EnumNamingStrategy.SnakeCase)]
    public partial CarMakeDto MapMake(CarMake make);
}

Manually mapped enum values

To explicitly map enum values the MapEnumValueAttibute can be used. Attribute is only valid on enum-to-enum, enum-to-string and string-to-enum mappings.

Explicit enum mappings are not affected by enum naming strategies.

[Mapper]
public partial class CarMapper
{
    [MapEnum(EnumMappingStrategy.ByName)]
    [MapEnumValue(CarFeature.AWD, CarFeatureDto.AllWheelDrive)]
    public partial CarFeatureDto MapFeature(CarFeature feature);

    [MapEnumValue("AWD", CarFeatureDto.AllWheelDrive)]
    public partial CarFeatureDto MapFeatureFromString(string feature);

    [MapEnumValue(CarFeatureDto.AllWheelDrive, "AWD")]
    public partial string MapFeatureToString(CarFeatureDto feature);
}

Ignore enum values

To ignore an enum value the MapperIgnoreSourceValue or MapperIgnoreTargetValue attributes can be used. This is especially useful when applying strict enum mappings.

[Mapper]
public partial class FruitMapper
{
    [MapperIgnoreSourceValue(Fruit.Apple)]
    [MapperIgnoreTargetValue(FruitDto.Pineapple)]
    public partial FruitDto Map(Fruit source);
}

Fallback value

To map to a fallback value instead of throwing when encountering an unknown value, the FallbackValue property on the MapEnum attribute can be used.

FallbackValue is supported by ByName and ByValueCheckDefined. FallbackValue is not affected by enum naming strategies.

[Mapper]
public partial class CarMapper
{
    [MapEnum(EnumMappingStrategy.ByName, FallbackValue = CarFeatureDto.Unknown)]
    public partial CarFeatureDto MapFeature(CarFeature feature);
}

One side strict enum member mappings

By default Mapperly emits diagnostics with a severity of warning if there are unmapped source or target enum members. To enforce strict enum member mappings on only either the source or the target, the RequiredEnumMappingStrategy can be used. By default this property will inherit the value from RequiredMappingStrategy.

Global (mapper level)

Sets the RequiredEnumMappingStrategy for all methods within the mapper, by default it is Both requiring all members to be mapped. This can be overriden by individual mapping methods using MapperRequiredMappingAttribute.

[Mapper(RequiredEnumMappingStrategy = RequiredMappingStrategy.Source)]
public partial class CarMapper
{
    ...
}

Local (mapping method level)

Applied to the specific mapping method.

[Mapper]
public partial class CarMapper
{
    [MapperRequiredMapping(RequiredMappingStrategy.Source)]
    public partial CarFeatureDto MapCar(CarFeature feature);
}