Mappa.Generator 10.0.0

Mappa.Generator

This source generator generates code for partial methods in partial classes tagged with the [Mappa] attribute defined in the Mappa package. The generated code allow to map from a source type to a target type.

Assuming you have a partial method like the following

[Mappa]
public partial class Mapper
{
    public partial TTarget Map(TSource input);
}

where TSource is the source type of the mapping and TTarget is the target type of the mapping, the source generator works by applying the following set of strategies in the order they are defined (see TypeMapIdentifierAlgorithm.cs):

1. <u>Polymorphic mapping</u>
   • When:
     • The method has one or multiple [MappaTypeMapping] attributes
   • What:
     • The input type will determine how the mapping from TSource to TTarget will happen,
     • For every [MappaTypeMapping] attributes a mapping is created,
     • The default mapping in case the actual parameter type does not match any of the source type from the [MappaTypeMapping] attributes is determined by the [MappaTypeMappingDefault] attribute - if the attribute is not present the default behaviour will throw an exception.
2. <u>Existing method strategy</u>
   • When:
     • A method in the same class or a base class of the mapper from TSource to TTarget exists OR,
     • A method from a property or field marked with the [MappaDependency] on the mapper or an accessible base class of the mapper, or from a base class of the dependency type from TSource to TTarget exists OR,
     • A method from a type defined via the [MappaStaticDependency] attribute exists OR,
     • A polymorphic method where one of the [MappaTypeMapping] attributes matches TSource and TTarget OR,
     • Settings PolymorphicMapMethodWithMatchingDefaultAttribute is Enable and a polymorphic method with attribute [MappaTypeMappingDefault] and behaviour MappaTypeMappingDefaultBehavior.MapSourceType and TTarget is matching the target type defined by the attribute and TSource the source type of the method exists;
   • What:
     • the method is invoked;
     • Notes:
       • This strategy is usually used when mapping element of an array, keys or values of dictionaries, elements of tuples, properties of class/struct/record.
3. <u>Identity strategy</u>:
   • When:
     • TSource and TTarget are the same type (e.g. TSource => int and TTarget => int) OR,
     • TSource can be implicitly converted into TTarget (e.g. TSource => int and TTarget => long);
   • What:
     • the input value is simply assigned to the target;
4. <u>Nullable strategy</u>:
   • When:
     • TSource is the Nullable<T> value type (e.g. int?) OR,
     • TSource is a nullable reference type when #nullable enable (e.g. string?) OR,
     • TSource is a reference type when #nullable disable (e.g. string),
     • AND a mapping exists from source to target when stripped of the nullablity;
   • What:
     • if TTarget can be null the mapper will return null OR,
     • if TTarget cannot be null the mapper will throw a NullReferenceException;
5. <u>enum strategy</u>:
   • When:
     • TSource is an enum and TTarget is a different enum, an integral numeric type compatible with the enum or a string OR,
     • TSource is a different enum, an integral numeric type compatible with the enum and TTarget is an enum;
   • What:
     • a switch statement is introduced to quickly map TSource to TTarget using all the possible values of the enum,
6. <u>string strategy</u>:
   • When:
     • TSource is a string and TTarget is any of the numeric types OR,
     • TSource is a string and TTarget is any of the following types DateTime, DateTimeOffset, DateOnly, TimeOnly, Guid, Uri OR,
     • TTarget is a string OR
     • TSource is a string and TTarget is any type with an accessible static Parse method;
   • What:
     • TSource is a string and TTarget is any of the numeric types then the relevant Parse method will be invoked, possibly with the culture identified by the MappaSettings attribute, if any is provided on the class or on the method;
     • TSource is a string and TTarget is any of the following types DateTime, DateTimeOffset, DateOnly, TimeOnly, Guid then their TTarget.Parse method will be used, possibly with the format and culture identified by the MappaSettings attribute, if any is provided on the class or on the method;
     • TSource is a string and TTarget is Uri then the System.UriBuilder will be used for the mapping;
     • TTarget is a string and TSource is any of the following types DateTime, DateTimeOffset, DateOnly, TimeOnly, Guid then their TSource.ToString() method will be used, possibly with the format and culture identified by the MappaSettings attribute, if any is provided on the class or on the method;
     • TTarget is a string and TSource is any of the numeric types then the relevant ToString overload will be used, possibly with the format and culture identified by the MappaSettings attribute, if any is provided on the class or on the method;
     • TTarget is a string then the TSource.ToString method will be used;
     • TSource is a string and TTarget is any type with an accessible static Parse method then the Parse method is invoked (note: an existing constructor accepting only a single string parameter will take priority over this);
7. <u>Date & Time strategy</u>:
   • When:
     • TSource is a DateTime and TTarget is long or,DateTime or, TimeOnly OR,
     • TSource is a DateTimeOffset and TTarget is long or, DateTime or, DateTime or, TimeOnly OR,
     • TSource is a DateOnly and TTarget is long or, DateTime OR,
     • TSource is a long and TTarget is DateTime or, DateTimeOffset OR,
     • TSource is a TimeSpan and TTarget is double OR,
     • TSource is a double and TTarget is TimeSpan OR,
   • What:
     • The usual mapping conversions are used;
     • When mapping from DateOnly to DateTime or DateTimeOffset the TimeOnly.Zero is used;
     • When mapping to or from long the Unix time is used;
     • When a timezone is required UTC is implied;
   • Notes:
     • The mapping from DateTime to DateTimeOffset is handled by the identify strategy;
8. <u>Container strategy</u>:
   • When:
     • TSource and TTarget are both either dictionaries or collections,
     • For dictionaries, mappings exist from source key type to the target key type and from the source value type to the target value type,
     • For collections, a mapping exists from the source element type to the target element type,
     • TSource dictionary types accepted:
       • any type implementing IDictionary<TKey, TValue>;
       • any type implementing IReadOnlyDictionary<TKey, TValue>;
       • any type implementing IEnumerable<KeyValuePair<<TKey, TValue>>;
     • TTarget dictionary types accepted:
       • any type implementing IDictionary<TKey, TValue> that has a constructor with zero arguments;
       • the following interfaces: IDictionary<TKey, TValue>, IReadOnlyDictionary<TKey, TValue>, IImmutableDictionary<TKey, TValue>;
       • the following classes: ImmutableDictionary<TKey, TValue>, ImmutableSortedDictionary<TKey, TValue>, FrozenDictionary<TKey, TValue>, ConcurrentDictionary<TKey, TValue>;
     • TSource collection types accepted: any type implementing IEnumerable<T>, arrays, Span<T>, ReadOnlySpan<T>, Memory<T> and ReadOnlyMemory<T>;
     • TTarget collection types accepted:
       • any type implementing ICollection<T> or ISet<T> that has a constructor with zero arguments (or one constructor with one integer argument of type int and MappaSettings.ContainerCapacityConstructors is enabled);
       • any type derived from Stack<T> or Queue<T> or BlockingCollection<T> that has a constructor with zero arguments (or one constructor with one integer argument of type int and MappaSettings.ContainerCapacityConstructors is enabled);
       • the following interfaces: IEnumerable<T>, ICollection<T>, IReadOnlyCollection<T>, ISet<T>, IList<T>, IReadOnlyList<T>, IReadOnlySet<T>, IImmutableSet<T>, IImmutableList<T>, IImmutableQueue<T>, IImmutableStack<T>, IProducerConsumerCollection<T>;
       • the following classes: arrays, List<T>, ReadOnlyCollection<T>, Span<T>, ReadOnlySpan<T>, Memory<T>, ReadOnlyMemory<T>, Stack<T>, Queue<T>, ReadOnlySet<T>, HashSet<T>, SortedSet<T>, FrozenSet<T>, ImmutableHashSet<T>, ImmutableSortedSet<T>, ImmutableArray<T>, ImmutableList<T>, ImmutableQueue<T>, ImmutableStack<T>, ConcurrentBag<T>, ConcurrentQueue<T>, ConcurrentStack<T>;
   • What:
     • A for loop or foreach loop is added to the code;
     • In the loop, each element from the source collection is mapped in an element of the target collection and then added to the target collection;
   • Notes:
     • When possible for some types (e.g. List<T>) the usage of the constructor accepting capacity is preferred to reduce the number of allocations;
     • Explicit interface implementation is supported;
     • Type with an empty constructor are supported if they are derived from any of the supported interfaces or classes;
9. <u>Tuples strategy</u>:
   • When:
     • TSource and TTarget are both tuple types,
     • The number of the elements in the tuple is the same,
     • For each element of the tuple there exists a mapping from source element to target element;
   • What:
     • Each element of the source tuple is mapped into a new element of the target tuple;
     • The target tuple is created by combining the elements mapped;
   • Notes:
     • Both named and un-named tuples are supported
     • The type Tuple<T> (and its variations with more elements) are supported;
10. <u>Guid strategy</u>:
    • When:
      • TSource is Guid and TTarget is byte[] or Span<byte> or ReadOnlySpan<byte> or Memory<byte> or ReadOnlyMemory<byte>, OR
      • TSource is byte[] or Span<byte> or ReadOnlySpan<byte> or Memory<byte> or ReadOnlyMemory<byte> and TTarget is Guid;

• What:
  • A mapping from Guid to byte[]/Span<byte> is defined using the relevant Guid constructors or the Guid.ToByteArray() method

11. <u>Constructor strategy</u>:
    • When:
      • TTarget type has one constructor with no parameters and each property with a setter can be assigned from a TSource property with the same name (case-sensitive by default, configurable via ForceCaseInsensitivePropertyMap and IgnoreUnderscoreForPropertyMap in MappaSettings) OR,
      • TTarget type has one constructor with parameters and each constructor argument can be assigned from a TSource property with the same name (case-insensitive by default, with optional underscore-insensitive matching via IgnoreUnderscoreForPropertyMap in MappaSettings);
    • What:
      • Each property or constructor argument is mapped and a new instance of TTarget is generated;
      • Get-only dictionary or collection properties for which a mapper exists are filled with mapped values from the corresponding source;
    • Notes:
      • Explicit interface implementation is supported for get-only dictionary and collection properties;
      • Get-only Stack<T>, Queue<T>, ConcurrentStack<T>, ConcurrentQueue<T>, ConcurrentBag<T>, and BlockingCollection<T> properties are filled post-construction using Push, Enqueue, or Add respectively;
      • Multiple Mappa attributes can change the behaviour of the mapping;

Currently unsupported features are:

• Generic type parameters on map methods (for example, TTarget Map<TSource, TTarget>(TSource input)).

Other relevant packages:

• Mappa: attributes and MappaContext used to drive the source generator;
• Mappa Protobuf: methods to map Google.Protobuf.WellKnownTypes objects from Google.Protobuf package into common objects.
• Mappa Protobuf dependency: utility methods to register the Protobuf mapper.
• Mappa Bson: methods to map MongoDB.Bson objects from MongoDB.Bson package into common objects.
• Mappa Bson dependency: utility methods to register the Bson mapper.

You can find samples here. Visit the Mappa documentation to learn more.