Configuration - maurosampietro/UltraMapper GitHub Wiki

The Configuration class holds information about mappings and their options.

Tipically, you configure UltraMapper directly while instantiating a mapper like this:

var mapper = new Mapper( cfg =>{...} );

You can also define a Configuration object and pass it to the UltraMapper constuctor:

var configuration = new Configuration( cfg =>{...} );
var mapper = new Mapper( configuration );

UltraMapper provides 3 layers of configuration:

• Global configuration
• Type-mapping level configuration
• Member-mapping level configuration

Member-mapping specific options have priority over type-mapping specific options, that in turn, have priority over global options.

var mapper = new Mapper( cfg =>
{
    cfg.Option1 = true;

    cfg.MapType<SourceType,TargetType>( typeMappingConfig => typeConfig.Option1 = false )
       .MapMember( s => s.SourceMember, t => t.TargetMember, memberMappingConfig => memberMappingConfig.Option1 = true );
} );

In the above example an hypothetical Option1 is enabled globally.
This affects any type-mapping and member-mapping.

SourceType -> TargetType type-mapping overrides the global behavior for all its members by setting Option1 to false.

SourceMember -> TargetMember member-mapping, overrides its declaring type-mapping behavior by setting Option1 back to true.

UltraMapper provides just a few options:

This options is available globally and at type-mapping level.

• If set to true only explicitly user-defined member-mappings are taken into account in the mapping process and members-mappings resolved by convention are ignored. (Convention are disabled)

• if set to False, user-defined and convention resolved mappings are taken into account. (Convention are enabled)

• ReferenceBehavior (Available globally, type-mapping and member-mapping level):

  • if set to CREATE_NEW_INSTANCE, each time a reference type is encountered, a new instance of that type is created and mapped, even if the target instance is not null.

  • If set to USE_TARGET_INSTANCE_IF_NOT_NULL a new instance of the type is created only if the reference is NULL.

• CollectionBehavior (Available globally, type-mapping and member-mapping level):

  CollectionBehaviors are taken into account if ReferenceMappingStrategy is set to USE_TARGET_INSTANCE_IF_NOT_NULL.
  In all the cases, we keep using exactly the same reference available on the target.

  • if set to MERGE, each item of the source collection will be added to the target collection.

  • If set to RESET, the target collection is cleared before adding items.

  • If set to UPDATE:

    • each source item matching a target item is updated

    • each source item non existing in the target collection is added

    • each target item non existing in the source collection is removed.

  • if set to INHERIT, this option is inherited from the parent mapping.

• Ignore (Available at member-mapping level):

  • If set to 'True' the mapping is not taken into account
  • If set to 'False' the mapping is taken into account

If UltraMapper can't map between two types or if you want to provide a custom way to map between two types, you can define a new converter.

For example mapping from bool to string will yield 'True' or 'False', by default;
you can override this behavior to yield, for example, '1' or '0' by providing a custom converter like this:

var mapper = new Mapper( cfg =>
{
    cfg.MapTypes<bool, string>( b => b ? "1" : "0" );       
} );

Custom converters can be applied at type or member level.

In case no convention can figure out the relation between two members, you can set up a mapping manually like this:

public class SourceType
{
    public IEnumerable<int> SourceCollection{ get; set; }
}

public class TargetType
{
    public List<int> TargetList{ get; set; }
}

var mapper = new Mapper( cfg =>
{
    cfg.MapTypes<SourceType, TargetType>()
       .MapMember( s => s.SourceCollection, t => TargetList )        
} );