Overview

AgileMapper is a zero-configuration, highly-configurable object-object mapper with viewable execution plans, targetting .NET Standard 1.0+ and .NET 3.5+. It performs query projections, object creation, deep clones, id-aware updates and merges, and can be used via extension methods, or a static or instance API.

Mapping functions are created and cached the first time two types are mapped - no up-front configuration is necessary. You can cache up-front if you prefer, though.

Available via NuGet and licensed with the MIT licence, you can install it via the package manager console:

PM> Install-Package AgileObjects.AgileMapper

NuGet version

Basic Use

Object Creation

Create an object from another using:

var customer = Mapper.Map(customerViewModel).ToANew<Customer>();
// Or:
var customer = customerViewModel.Map().ToANew<Customer>();

Query Projection

Project entities to another Type using:

var customerVm = await dbContext
    .Customers
    .Project().To<CustomerViewModel>()
    .FirstAsync(c => c.Id == customerId);

Deep Cloning

Deep-clone an object using:

var clonedCustomer = Mapper.DeepClone(customerToBeCloned);
// Or:
var clonedCustomer = customerToBeCloned.DeepClone();

Updating

Update an object's members with values from another using:

Mapper.Map(customerSaveRequest).Over(customer);
// Or:
customerSaveRequest.Map().Over(customer);

Merging

Merge an object's unpopulated members with values from another using:

Mapper.Map(customerDto).OnTo(customer);
// Or:
customerDto.Map().OnTo(customer);

View a Mapping Execution Plan

View an execution plan to see how two object types will be mapped; this also caches the plan, so you can use it to choose when to incur that cost. Use:

// For object creation:
string mappingPlan = Mapper.GetPlanFor<Customer>().ToANew<CustomerViewModel>();
// For updates:
string mappingPlan = Mapper.GetPlanFor<Customer>().Over<CustomerViewModel>();
// For merges:
string mappingPlan = Mapper.GetPlanFor<Customer>().OnTo<CustomerViewModel>();

// For all three in one call:
string mappingPlans = Mapper.GetPlansFor<Customer>().To<CustomerViewModel>();

// For query projection:
string mappingPlan = Mapper
    .GetPlanForProjecting(context.Customers)
    .To<CustomerViewModel>();

// For everything in the mapping cache:
var allPlans = Mapper.GetPlansInCache();