Regular readers of my blog (maybe even both of you) will have seen sporadic references to ‘my pet mapper project’, going back to my first use of NDepend in December 2013. I’ve actually thrown it away and restarted a few times since January 2013, but it’s now - finally! - in a beta stage I’m happy to talk about.

Given AutoMapper and ValueInjecter, why write a mapper? Well…

• I spent the second half of 2012 working on an insurance application which required a lot of mapping between objects with 30 - 50 fields each. We did it all manually because we couldn’t find a way in any of the available mappers to see what would and wouldn’t be mapped

• I thought it would be useful to have a mapper which can map anything to anything without configuration - like ValueInjecter - but with a friendly, fluent API for configuration when necessary - like AutoMapper

• I thought it would be useful to have a mapper which - also without configuration - can pair up and update source and target objects using their identifiers

• It’s a difficult project (seriously - try it), so working on it and solving the problems therein would make me a better programmer

So I’ve written a mapper which solves the above problems.

Highlights

Create new objects from existing objects or perform deep clones

var customer = new Customer { Name = "Barney" };
var customerDto = mapper.Map(customer).ToANew<CustomerDto>();

var clonedCustomerDto = mapper.Clone(customerDto);

Update existing objects in an id-aware manner

var dtos = new[]
{
    new CustomerDto { Id = 1234, Name = "Maggie" },
    new CustomerDto { Id = 5678, Name = "Lisa" }
};
var customers = new[]
{
    new Customer { CustomerId = 5678 }, // Name updated to 'Lisa'
    new Customer { CustomerId = 1234 }  // Name updated to 'Maggie'
};
mapper.Map(dtos).Over(customers);

View (and cache) a mapping execution plan for mapping two types

var plan = mapper.GetPlanFor<PersonViewModel>().ToANew<Person>();

Other Stuff

• You can use it via a static or instance API

• It performs object merges

• It parses and converts numeric types, Guids, DateTimes and strings out of the box

• It maps lists, collections, enumerables and arrays out of the box

• It maps to constructor arguments

• It handles circular references out of the box

• You can configure custom data sources, members to ignore, callbacks at precise points within a mapping, custom object factories, exception handling, [naming patterns]https://agilemapper.readthedocs.io/configuration/Member-Name-Patterns) with which to match members… and more!

Check it out!

AgileMapper is free, MIT licensed, available at version 0.6 on NuGet, and can be installed via the package manager console with:

PM> Install-Package AgileObjects.AgileMapper

It’s hosted on GitHub with pretty decent documentation, and the public API is all documented. I’ll be reporting on and fine-tuning performance over the coming weeks, as well as adding new features like better support for Dictionaries. If you give it a try and find a bug please feel free to add it on GitHub. Enjoy!