8.0 Upgrade Guide

ProjectUsing

The ProjectUsing method consolidated with ConvertUsing:

// IMappingExpression

// Old
void ConvertUsing(Func<TSource, TDestination> mappingFunction);
void ProjectUsing(Expression<Func<TSource, TDestination>> mappingExpression);

// New
void ConvertUsing(Expression<Func<TSource, TDestination>> mappingExpression);

To migrate, replace all usages of ProjectUsing with ConvertUsing.

The ConvertUsing expression-based method will be used for both in-memory mapping and LINQ projections. You cannot have separate configuration for in-memory vs. LINQ projections.

Existing ConvertUsing usages

The change from Func to Expression may break some existing usages. Namely:

• ConvertUsing using lambda statements, method groups, or delegates
• Dual configuration of ProjectUsing and ConvertUsing

For the first case, you may either:

• Convert to a lambda expression
• Move to the Func-based overloads

The Func-based overloads accept more parameters, so you may have to add the parameters to your delegates.

Motivation

Simplify overloads, and to make it clear that you cannot have separate configuration for LINQ projections vs. in-memory mapping.

ConstructProjectionUsing

The ConstructProjectionUsing method consolidated with ConstructUsing:

// IMappingExpression<TSource, TDestination>

// Old
IMappingExpression<TSource, TDestination> ConstructUsing(Func<TSource, TDestination> ctor);
IMappingExpression<TSource, TDestination> ConstructUsing(Func<TSource, ResolutionContext, TDestination> ctor);
IMappingExpression<TSource, TDestination> ConstructProjectionUsing(Expression<Func<TSource, TDestination>> ctorExpression);

// New
IMappingExpression<TSource, TDestination> ConstructUsing(Expression<Func<TSource, TDestination>> ctor);
IMappingExpression<TSource, TDestination> ConstructUsing(Func<TSource, ResolutionContext, TDestination> ctor);

// IMappingExpression

// Old
IMappingExpression ConstructUsing(Func<object, object> ctor);
IMappingExpression ConstructUsing(Func<object, ResolutionContext, object> ctor);
IMappingExpression ConstructProjectionUsing(LambdaExpression ctorExpression);

// New
IMappingExpression ConstructUsing(Expression<Func<object, object>> ctor);
IMappingExpression ConstructUsing(Func<object, ResolutionContext, object> ctor);

To migrate, replace all usages of ConstructProjectionUsing with ConstructUsing.

The ConstructUsing expression-based method will be used for both in-memory mapping and LINQ projections. You cannot have separate configuration for in-memory vs. LINQ projections.

Existing ConstructUsing usages

The change from Func to Expression may break some existing usages. Namely:

• ConstructUsing using lambda statements, method groups, or delegates
• Dual configuration of ConstructProjectionUsing and ConstructUsing

For the first case, you may either:

• Convert to a lambda expression
• Move to the Func-based overload

The Func-based overload accepts more parameters, so you may have to add the parameters to your delegates.

Motivation

Simplify overloads, and to make it clear that you cannot have separate configuration for LINQ projections vs. in-memory mapping.

ResolveUsing

The ResolveUsing method consolidated with MapFrom:

// IMappingExpression

// Old
void ResolveUsing(Func<TSource, TDestination> mappingFunction);
void ResolveUsing(Func<TSource, TDestination, TDestination> mappingFunction);
void ResolveUsing<TResult>(Func<TSource, TDestination, TMember, TResult> mappingFunction);
// Many, many overloads
void MapFrom(Expression<Func<TSource, TDestination>> mapExpression);

// New
void MapFrom(Expression<Func<TSource, TDestination>> mappingExpression);
void MapFrom<TResult>(Func<TSource, TDestination, TResult> mappingFunction);
void MapFrom<TResult>(Func<TSource, TDestination, TMember, TResult> mappingFunction);

To migrate, replace all usages of ResolveUsing with MapFrom.

The MapFrom expression-based method will be used for both in-memory mapping and LINQ projections. You cannot have separate configuration for in-memory vs. LINQ projections.

Existing ResolveUsing usages

The change from Func to Expression may break some existing usages. Namely:

• ResolveUsing using lambda statements, method groups, or delegates
• Dual configuration of ResolveUsing and MapFrom

For the first case, you may either:

• Convert to a lambda expression
• Move to the Func-based overloads

The Func-based overloads accept more parameters, so you may have to add the parameters to your delegates.

Motivation

Simplify overloads, and to make it clear that you cannot have separate configuration for LINQ projections vs. in-memory mapping.

UseValue

Underneath the covers, UseValue called MapFrom. UseValue consolidated with MapFrom.

To migrate, replace all usages of UseValue with MapFrom:

// Old
cfg.CreateMap<Source, Dest>()
    .ForMember(dest => dest.Date, opt => opt.UseValue(DateTime.Now));

// New
cfg.CreateMap<Source, Dest>()
    .ForMember(dest => dest.Date, opt => opt.MapFrom(src => DateTime.Now));

This can be simplified to a global find and replace of UseValue( with MapFrom(src => .

Motivation

To make the underlying configuration more explicit. Historically, MapFrom only allowed mapping from an individual source member. This restriction went away with 5.0, so there is no longer a need for additional redundant configuration options originally meant to work around this restriction.

ForSourceMember Ignore

ISourceMemberConfigurationExpression.Ignore was renamed to DoNotValidate to avoid confusion. It only applies when validating source members, with MemberList.Source. It does not affect the mapping itself or validation for the default case, MemberList.Destination. To migrate, replace all usages of Ignore with DoNotValidate:

// Old
cfg.CreateMap<Source, Dest>()
    .ForSourceMember(source => source.Date, opt => opt.Ignore());

// New
cfg.CreateMap<Source, Dest>()
    .ForSourceMember(source => source.Date, opt => opt.DoNotValidate());

Generic maps validation

Generic maps are now validated. The generic map itself is validated at configuration time for the non generic members, so AssertConfigurationIsValid should catch errors for those. And the closed generic map will be validated when it's used, possibly at runtime. If you don't care about those errors, you need to override them.