There are good mapping tools out there already, but ditto was conceived to address a specific need for aggregating multiple source objects into a single instance. This is common for event handlers which all contribute their data to a single view model (ie, an event Denormalizer). From this simple model, it became real easy to extend its usage in other scenarios like mapping from a Form model in a web app to Commands in MVC controller code. Also, because it wires everything up using a IoC container, it is dead simple write resolvers, converters, or replace its behavior just by registering your implementations on your container.
- Convention-based assumptions to minimize configuration as much as possible
- Aggregation of source objects into single destination
- Deep validation checking
- Garrulous
- Fluent configuration without typedsturbating generic parameters
- Fast enough
- IoC, container-based
- Only properties are evaluated by convention right now
- Flattening/Unflattening isn't a concern for me, but it'd be easy to create components to do this without changing Ditto
ditto assumes the objects you are mapping have the same property names. This simple configuration assumes the two objects have the same names:
cfg.Map<MyViewModel>().From<MyEvent>();
ditto leans heavily on an IoC container to do its work. This lets us easily register resolvers and other bits for easy configuration. Castle Windsor integration is the only container integration provided right now, but ditto doesn't really care how services are getting resolved. If you decide to use the Castle Windsor integration you can just add the provided Facility (DittoFacility). Here's the code installing all mapping services for my view model denormalization daemon:
container.AddFacility("mapping.facility", new DittoFacility());
container.RegisterAllConfigurationsIn(new[] { GetType().Assembly });
container.RegisterAllGlobalConventionsIn(new[]{GetType().Assembly});
container.Register(AllTypes.FromThisAssembly()
.BasedOn<IResolveValue>()
.WithService.AllInterfaces()
.Configure(c => c.LifeStyle.Transient));
ditto likes to talk alot for Debug builds, so be sure you use a Release build (the default if you use the provided psake script). log4net is the only logging implementation provider right now (baked into Castle Windsor Integration), but it'd be easy to swap that out since ditto doesn't care who is listening.
To let ditto know what objects you need to map and their respective sources for data, you need to get the singleton implementation of IContainerDestinationConfiguration. The AbstractMappingConfiguration base class can be inherited from to save a few keystrokes. This assumes you can let your hair down about required services being provided without constructor injection.
public class MyViewModelConfiguration : AbstractMappingConfiguration
{
public override void Configure()
{
//'Cfg' is injected by your container
Cfg.Map<MyViewModel>().From<MyEvent>();
}
}
Conventions may be applied globally. Conventions may impact your destination objects in one of two ways:
- The resolution of a value based on the context or metadata of associated objects
- The conversion of a value for across-the-board metamorphosis; ie, conversion of all DateTime's into UTC
Global conventions are applied to every mapping ditto knows about.
To configure Global conventions, you need to add them to IContainGlobalConventions. For this, you may inherit from AbstractGlobalConventionConfiguration:
public class WebAppGlobalMappingConventions : AbstractGlobalConventionConfiguration
{
private readonly MyCustomResolver myCustomResolver;
public WebAppGlobalMappingConventions(MyCustomResolver myCustomResolver)
{
this.myCustomResolver = myCustomResolver;
}
public override void Configure()
{
Conventions.AddConverter(new EntityIdentifierConverter());
Conventions.AddConverter(new DateTimeUtcConverter());
Conventions.AddResolver(new PropertyNameCriterion("ConversationId"),new IgnoreResolver());
Conventions.AddResolver(new PropertyNameCriterion("Id"),myCustomResolver);
}
}
ditto is uptight, so if there are properties on destination objects that are not mapped after everything is bound together, it can let you know. This is done by default if you are using the provided WindsorMappingInitializer. This will throw an exception if there are any properties for which ditto has not been configured, either via global conventions or local mappings.
ditto can be initialized in your bootstrapping code by simply getting your instance of IInitializeDitto and calling its Initialize method. Again, there is a WindsorMappingInitializer that demonstrates the things that ditto needs to do for starting up. These are done, in order:
- Configure all global conventions
- Configure all destination objects from their sources
- Bind all these configurations together
- Cache configuration metadata (optional, but madness to do without)
- Validate/Assert all configuration
Once you have initialized ditto you may now just grab your instance of IMap and call it by either having ditto create the destination object for you, or passing in your own instance:
var myViewModel = mapper.Map<MyViewModel>(mySourceEvent); // => this creates an instance of MyViewModel and maps from your instance of the source
mapper.Map(mySourceEvent,myViewModel); // => this simply maps from the source to your own instance of MyViewModel
Please note that ditto currently assumes a default constructor for its own activation of objects. This would be dead simple to improve upon though since it is container-driven. Just replace IActivator and provide your own strategy(s).
- Fasterflect - ditto developer is lazy so relies on for reflection optimization stuff. It's a great little tool for the toolbox.
- Castle Windsor - Makes it easy to keep concerns split up.