AgileMapper Documentation

Because the Instance API uses IMapper, you can register different mapper instances for different controllers or services within your DI container (e.g., StructureMap). This allows you to have specialized mapping rules for different parts of your application.

public class OrderMapperRegistry : Registry
{
    public OrderMapperRegistry()
    {
        var mapperOne = Mapper.CreateNew();
        // Do mapperOne.WhenMapping configuration...

        // Register mapperOne as the instance to pass to OrderOneController:
        For<OrderOneController>().Use<OrderOneController>()
            .Ctor<IMapper>().Is(mapperOne);

        var mapperTwo = Mapper.CreateNew();
        // Do mapperTwo.WhenMapping configuration...

        // Register mapperTwo as the instance to pass to OrderTwoController:
        For<OrderTwoController>().Use<OrderTwoController>()
            .Ctor<IMapper>().Is(mapperTwo);
    }
}

AgileMapper supports 'meta' members, which are destination properties that contain information derived from other source members. AgileMapper automatically populates these members based on naming conventions without requiring explicit mapping configuration. Meta members are also supported in query projections.

class Account
{
    public int Id { get; set; }
    public ICollection<Order> Orders { get; set; }
    public ICollection<Address> DeliveryAddresses { get; set; }
}

class AccountDto
{
    public int Id { get; set; }
    public bool HasOrders { get; set; }
    public int DeliveryAddressCount { get; set; }
    public bool FirstDeliveryAddressHasPostcode { get; set; }
}

// AgileMapper will automatically populate:
// - HasOrders: true if Orders is non-null and has count > 0
// - DeliveryAddressCount: the count of DeliveryAddresses
// - FirstDeliveryAddressHasPostcode: true if the first element in DeliveryAddresses has a non-default Postcode

AgileMapper supports automatic discovery and mapping of derived types based on naming conventions. For example, if you have a base type Person and a derived type Customer, and corresponding view models PersonViewModel and CustomerViewModel, AgileMapper will automatically pair Customer to CustomerViewModel even if the source variable is typed as the base Person.

When mapping, use .ToANew<TTarget>() to ensure the mapper identifies and instantiates the correct derived target type.

public class Person {}
public class Customer : Person
{
    public float Discount { get; set; }
}

public class PersonViewModel {}
public class CustomerViewModel : PersonViewModel
{
    public double Discount { get; set; }
}

// Usage:
var person = new Customer { Discount = 0.1f } as Person;
var viewModel = Mapper.Map(person).ToANew<PersonViewModel>();
// viewModel is of type CustomerViewModel and Discount is 0.1

If multiple configuration classes define settings for the same types in an object graph, you may need to control the order in which they are applied.

Use the [ApplyAfter(typeof(ConfigurationType))] attribute on your MapperConfiguration class to specify that it should be applied after a specific configuration. AgileMapper will follow chains of ApplyAfter attributes to ensure the correct sequence.

Note: Defining circular references between configuration types will result in a MappingConfigurationException.

// Configure aspects of Parent -> Parent mapping, which includes 
// mapping Child -> Child. Automatically apply ChildMapperConfiguration,
// then apply this configuration afterwards.
[ApplyAfter(typeof(ChildMapperConfiguration))]
public class ParentMapperConfiguration : MapperConfiguration
{
}

// Configure aspects of Child -> Child mapping:
public class ChildMapperConfiguration : MapperConfiguration
{
}