5.0 Upgrade Guide

Jimmy Bogard edited this page Dec 6, 2016 · 14 revisions


You now must use either Mapper.Initialize or new MapperConfiguration() to initialize AutoMapper. If you prefer to keep the static usage, use Mapper.Initialize.

If you have a lot of Mapper.CreateMap calls everywhere, move those to a Profile, or into Mapper.Initialize, called once at startup.

For examples see Static-and-Instance-API.


Instead of overriding a Configure method, you configure directly via the constructor:

public class MappingProfile : Profile {
    public MappingProfile() {
        CreateMap<Foo, Bar>();

IgnoreAllNonExisting extension

A popular Stack Overflow post introduced the idea of ignoring all non-existing members on the destination type. It used things that don't exist anymore in the configuration API. This functionality is really only intended for configuration validation.

In 5.0, you can use ReverseMap or CreateMap passing in the MemberList enum to validate against the source members (or no members). Any place you have this IgnoreAllNonExisting extension, use the CreateMap overload that validates against the source or no members:

cfg.CreateMap<ProductDto, Product>(MemberList.None);

Resolution Context things

ResolutionContext used to capture a lot of information, source and destination values, along with a hierarchical parent model. For source/destination values, all of the interfaces (value resolvers and type converters) along with config options now include the source/destination values, and if applicable, source/destination members.

If you're trying to access some parent object in your model, you will need to add those relationships to your models and access them through those relationships, and not through AutoMapper's hierarchy. The ResolutionContext was pared down for both performance and sanity reasons.

Value resolvers

The signature of a value resolver has changed to allow access to the source/destination models. Additionally, the base class is gone in favor of interfaces. For value resolvers that do not have a member redirection, the interface is now:

public interface IValueResolver<in TSource, in TDestination, TDestMember>
    TDestMember Resolve(TSource source, TDestination destination, TDestMember destMember, ResolutionContext context);

You have access now to the source model, destination model, and destination member this resolver is configured against.

If you are using a ResolveUsing and passing in the FromMember configuration, this is now a new resolver interface:

public interface IMemberValueResolver<in TSource, in TDestination, in TSourceMember, TDestMember>
    TDestMember Resolve(TSource source, TDestination destination, TSourceMember sourceMember, TDestMember destMember, ResolutionContext context);

This is now configured directly as ForMember(dest => dest.Foo, opt => opt.ResolveUsing<MyCustomResolver, string>(src => src.Bar)

Type converters

The base class for a type converter is now gone in favor of a single interface that accepts the source and destination objects and returns the destination object:

public interface ITypeConverter<in TSource, TDestination>
    TDestination Convert(TSource source, TDestination destination, ResolutionContext context);

Circular references

Previously, AutoMapper could handle circular references by keeping track of what was mapped, and on every mapping, check a local hashtable of source/destination objects to see if the item was already mapped. It turns out this tracking is very expensive, and you need to opt-in using PreserveReferences for circular maps to work. Alternatively, you can configure MaxDepth:

// Self-referential mapping
cfg.CreateMap<Category, CategoryDto>().MaxDepth(3);

// Circular references between users and groups
cfg.CreateMap<User, UserDto>().PreserveReferences();


UseDestinationValue tells AutoMapper not to create a new object for some member, but to use the existing property of the destination object. It used to be true by default. Consider whether this applies to your case. Check recent issues.

cfg.CreateMap<Source, Destination>()
   .ForMember(d => d.Child, opt => opt.UseDestinationValue());