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
andConvertUsing
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
andConstructUsing
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
andMapFrom
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.