dclucas/moo

Object-to-object mapper

Moo: an object-to-object multimapper

Moo allows you to compose multiple mapping strategies into one for your object-to-object mapping.

Mapping strategies

Out-of-box, the following strategies are available, but you can also create your own:

1. Convention: matches by name and type, with property unfolding;
2. Attributes: mark your classes (source and/or target) with mapping attributes;
3. Configuration: add a mapping section to your .config file and this mapper will follow it;
4. Manual: explicit code calls do the mapping;

Download

The recommended approach is to download the binaries through Nuget (version 0.8.0) is available now:

To install Moo through Nuget, run the following command in the Package Manager Console

PM> Install-Package Moo

You can also use the nightly builds output, available at TeamCity: http://teamcity.codebetter.com/viewLog.html?buildId=lastSuccessful&buildTypeId=bt641&tab=artifacts

Usage

Simple usage

Mapping can be as simple as this:

var result = source.MapTo<PersonEditModel>();

This extension method does all the work under the hood, creating a mapper, a repository, etc.

Mapping collections

Mapping enumerables can be done this way:

var result = source.MapAll<Person, PersonEditModel>();

Once again, using the extension method leaves Moo in charge of creating all required inner objects.

Fluent API

The code below shows how a mapper can be extended with additional mapping actions:

MappingRepository.Default
   .AddMapping<Person, PersonEditModel>()
   .From(p => p.FirstName + p.LastName)
   .To(pe => pe.Name);

var result = source.MapTo<PersonEditModel>();

A fluent API is provided for explicit code mappings. Advantages over "pure" by-hand mapping is a) a consistent approach to mapping and handling errors and b) the ability to still combine explicit mappings with other strategies.

Instructions like the ones above are carried by the ManualMapper class, which in term can be configured to have bigger or smaller precedence in comparison to other mappers.

Using auxiliary mappers

You can use additional mappers for internal properties. The code below is instructing Moo to map property Person.Account to PersonDetailsDataContract.PersonAccount through a mapper.

MappingRepository.Default
    .AddMapping<Person, PersonDetailsDataContract>()
    .UseMapperFrom(p => p.Account)
    .To(pd => pd.Account)
    .From(p => p.FirstName + p.LastName)
    .To(pd => pd.Name);

var result = source.MapTo<PersonDetailsDataContract>();

Defining mapper precedence

In the example below, the added rule (of associating 111 to PersonEditModel.Id) will just run in case there is no convention rule stating otherwise.

var repo = new MappingRepository(o =>
    o.MapperOrder
        .Use<ConventionMapper<object, object>>()
        .Then<ManualMapper<object, object>>()
        .Finally<AttributeMapper<object, object>>());

repo.AddMapping<Person, PersonEditModel>()
    .From(s => 111)
    .To(t => t.Id);

var mapper = repo.ResolveMapper<Person, PersonEditModel>();

var result = mapper.Map(source);

Error handling

When mapping, Moo will wrap all internal exceptions into a MappingException, with details on what mapping it was working on:

try
{
    var result = source.MapTo<PersonEditModel>();
}
catch (MappingException ohno)
{
    // Do your exception handling here -- mapping exception will 
	// contain source and target information (their types, 
	// properties being mapped, etc). The Trace code below is just
	// a (bad) example.
    Trace.TraceError(
        "Got an error when mapping. Source: {0}. Target: {1}. Error: {1}",
        ohno.SourceType,
        ohno.TargetType,
        ohno.Message);
}

Handling IEnumerable properties

Mappers will be happy to map between properties when they are easily convertible, such as:

• T[] to T[]: as in int[] to int[], string[] to string[], etc
• IEnumerable<T> to IEnumerable<T>;
• DerivedType[] to BaseType[];
• T[] to IEnumerable;
• All combinations above;

The convention mapper will not automatically convert from int[] to object[]. Internally, the framework does not consider the latter to be assignable from the former.

In case you need an inner mapper for a given IEnumerable property, the syntax below will create and handle one for you:

MappingRepository.Default
    .AddMapping<Person, PersonDetailsDataContract>()
    .UseMapperFrom(p => p.Contacts)
    .To(pe => pe.PersonContacts);

var result = source.MapTo<PersonDetailsDataContract>();

Future features

• Planned: Set factory methods in Repo (as in repo.CreateObjects.With(t => Activator.CreateInstance(t)).Create.With(() => new MyClass))

moo's Issues

Moo .net core support

Diogo, are you planning on supporting .net core?

Issue: Convention mapper should prioritize direct conversion over property unfolding

Given the classes:
public class SampleClassA
{
public OtherClass Other { get; set }
public int OtherId { get; set; }
}

public class SampleClassB
{
public int OtherId { get; set; }
}

public class OtherClass
{
public int Id { get; set; }
}

A call to sampleObjA.Map() should map the two OtherId properties, instead of Other.Id to OtherId, as sometimes happens in the current code.

Current workaround is to create a manual mapping to override the convention.

Feature: Create base mapper class, for custom mapping extension

Keep BaseMapper for coders who are expanding the library, but provide developers a way to inherit mapping functionality and specialize it through code.

As in:

public class CustomerMVMMapper : Mapper<Customer, CustomerMVVM)
{
    public CustomerMVMMapper()
    {
        // this guy should inherit from composite mapper and upon this constructor call already have all the mapper stack ready.
        AddMapping( /* magic mapping here */);
    }
}

Feature: Add unit-test friendly features

Add features to help on client code unit tests. For example:

1. Add events to:

• When a property mapping is discovered;
• When an object mapping begins/ends;
• When a property is mapped;
  1. Add auxiliary methods to help determine:
• Which source and target properties have been touched by the mapper;
• Which haven't.

For the time being, this issue is a placeholder for the functionalities we can think of. Once we figure out which ones we want to implement, specific items will be created for them.

Task: verify dynamic support

Check which level of coverage for dynamic objects Moo already has, through TDD. If functionalities are lacking, comment the tests and add defects for each one.

Feature: extend existing (relevant) mappers to allow inner mapper inclusion

Extend behavior of AttributeMapper and ConfigurationMapper to allow inner mappers for specific properties.

AttributeBehavior:

[Mapping(MappingDirection.From, "TargetProperty", UseMapper=true)]

Similar idea for configuration.

Feature: Create mapping provider interface and handling code

A user should be able to provide custom mapping for a given Source/Target combination by implementing a simple interface:

public class PersonPersonEditModelMappingProvider : MappingProvider<Person, PersonEditModel>
{
      public void AddMappings()
      {
            this.AddMapping()
               .From(s => s.Name + s.LastName)
               .To(t => t.FullName)
      }
}

The design needs to either have a base class that provides an AddMapping method or to provide an interface that receives a repo (or a new MappingAdder class or such) and uses it. While the interface is more easily testable, the base class enforces a segregation by source/target more easily.

Task: modify nuget package to open README.md after the installation.

This way, whenever an Install-Package is made, the user will have the README right in front of their eyes.

Feature: allow usage of additional independent mappers for relationships

Add support to add secondary mappers to a mapper, to deal with specific internal properties.

Issue with Mapping DateTime? to DateTime?

I have a source object with a DateTime? and trying to map to a similar object with DateTime? I am getting this error.

Moo.MappingException : Error mapping from MatchManagement.Data.DomainEntities.Registration.MatchesAndEvents.EventEndDate to MatchManagement.UX.Models.Admin.MatchAndEvents.MatchAndEventViewModel.EventEndDate
----> System.InvalidOperationException : Operation is not valid due to the current state of the object.

Feature: Create IEnumerable<T> (and similar) property support

Suport for mappings such as:

public class SourceClass
{
public IEnumerable<SourceItemClass> Items { get; set; }
}

to

public class TargetClass
{
public IEnumerable<TargetItemClass> Items { get; set; }
}

Mapping from object with nullable to non nullable throws exception

I have a ViewModel that has a nullable int (int? Year), and I am trying to map it to a Model with the same property as an int (int Year).

Moo throws an exception in this instance. Is there any way to tell moo to map the nullable to the int?

Feature: Async Support

I would love to see support for handling async, like Foo.MapToAsync