Mappa 10.1.0

Mappa

This package contains all the attributes that can be used to drive the behaviour of the Mappa source generator. This is the list of attributes provided:

• Mappa: Identifies partial classes that are meant to be source generated by the Mappa source generator;
• MappaIgnore: Identifies methods that should not be used for mapping;
• MappaDependency: Identifies a property or field inside a mapper class that can be used when identifying suitable mappings between two types; fields and properties tagged on accessible base classes of the mapper are also considered; methods on the dependency type and its base classes are considered when the field or property type is that type or a derived type;
• MappaStaticDependency: Defines a static class whose methods can be used as dependencies while performing mappings;
• MappaSettings: Allows specifying mapping behaviour (for example, culture when parsing or formatting date/time, Guid, and numeric types, and format when converting numeric types to string);
• MappaUseProperty: When mapping structured types (class, struct, and records) allows specifying which source property to use for a target property or constructor parameter;
• MappaIgnoreTargetProperty: When mapping structured types via an empty constructor, excludes a target property from property-initializer mapping; has no effect when mapping uses a constructor with parameters;
• MappaAssignFromContext: When mapping structured types, allows specifying which value from a MappaContext to use for a target property or constructor parameter;
• MappaAssignToContext: When mapping structured types via the constructor-map strategy, stores the value of a target property or field in MappaContext after the target object has been fully constructed;
• MappaInvokeMethodAttribute: When mapping structured types via the constructor-map strategy, forces a target property or constructor parameter to be mapped by invoking a named method; supports an optional SourcePropertyName named parameter to select the source property passed to the invoked method;
• MappaAssignFromConstant: When mapping structured types, allows specifying a constant value for a target property or constructor parameter;
• MappaTypeMapping: When mapping structured types or interfaces, allows defining the target type depending on the source type;
• MappaTypeMappingDefault: Describes the default behaviour for polymorphic methods defined via MappaTypeMapping.

This package also provides the MappaContext class that can be used to pass contextual values to mappers via the MappaAssignFromContext attribute, store mapped values via the MappaAssignToContext attribute, or supply context to methods invoked via the MappaInvokeMethodAttribute attribute.

Via MappaSettings the following settings can be tweaked:

• DateTimeFormat: the format to use when mapping strings to and from System.DateTime;
• DateTimeOffsetFormat: the format to use when mapping strings to and from System.DateTimeOffset;
• DateOnlyFormat: the format to use when mapping strings to and from System.DateOnly;
• TimeOnlyFormat: the format to use when mapping strings to and from System.TimeOnly;
• DateTimeStyle: the DateTimeStyles to use when parsing strings to System.DateTime (unset values inherit; does not affect ToString);
• DateTimeOffsetStyle: the DateTimeStyles to use when parsing strings to System.DateTimeOffset (unset values inherit; does not affect ToString);
• DateOnlyStyle: the DateTimeStyles to use when parsing strings to System.DateOnly (unset values inherit; does not affect ToString);
• TimeOnlyStyle: the DateTimeStyles to use when parsing strings to System.TimeOnly (unset values inherit; does not affect ToString);
• GlobalDateTimeStyle: the default DateTimeStyles for parsing date/time types when the type-specific style is unset (type-specific styles override when both are set; does not affect ToString);
• TimeSpanFormat: the format to use when mapping strings to and from System.TimeSpan;
• GuidFormat: the format to use when mapping strings to and from System.Guid;
• ByteFormat, SByteFormat, ShortFormat, UShortFormat, IntFormat, UIntFormat, LongFormat, ULongFormat, DecimalFormat, FloatFormat, DoubleFormat: the format to use when converting the corresponding numeric type to string (numeric formats apply to ToString only);
• ByteStyle, SByteStyle, ShortStyle, UShortStyle, IntStyle, UIntStyle, LongStyle, ULongStyle, DecimalStyle, FloatStyle, DoubleStyle: the NumberStyles to use when parsing strings to the corresponding numeric type (unset values inherit; does not affect ToString);
• GlobalNumberStyle: the default NumberStyles for parsing numeric types when the type-specific style is unset (type-specific styles override when both are set; does not affect ToString);
• CultureInfoSetting: defines which culture to use when mapping any of the above types and numeric types (current culture, invariant culture, or user-defined culture);
• CultureName: defines the culture to use when user-defined culture is selected by CultureInfoSetting;
• ProtobufOptional: enables or disables the ability of the Mappa source generator to handle optional fields in protobuf models;
• PragmaWarning: allows surrounding the generated methods with a #pragma warning disable block;
• FastCollections: uses Span<T> to make mappings involving arrays and System.Collections.Generic.List<T> faster;
• ContainerCapacityConstructors: supports mapping custom containers using (if available) a constructor accepting an integer value representing the initial capacity of the container;
• EnumerableConcreteType: selects whether mappings to sequence-like collection interfaces (for example IEnumerable<T>) use List<T> (default) or T[] as the concrete buffer;
• PolymorphicMapMethodWithMatchingDefaultAttribute: when enabled, MappaTypeMappingDefault can be used to locate an appropriate polymorphic method when looking for the mapping between two types;
• CaseInsensitivePropertyMap: when enabled, source property names are matched case-insensitively when pairing a target property or constructor parameter with a source property by name;
• IgnoreUnderscoreForPropertyMap: when enabled, underscore characters are stripped from names before comparing a target property or constructor parameter with a source property by name;
• CaseInsensitiveEnumMap: when enabled, enum member names or [Description] values are matched case-insensitively when mapping between enums or from string to an enum;
• EnumStringMapSetting: selects whether enum and string mappings match members by name (default) or by [Description] attribute value;
• EnumToEnumMapSetting: selects whether enum-to-enum mappings match members by name (default), by underlying numeric value, or by [Description] attribute value;
• IdentityMapDeepCopy: selects whether identity mappings return the original reference, clone via MemberwiseClone, or recursively copy nested fields (see Mappa.MappaCloning.MemberwiseClone).

Via MappaTypeMappingDefault the following settings can be tweaked:

• Undefined: this setting should never be used;
• Throw: if the source type is not defined by any of the MappaTypeMapping attributes, throws ArgumentOutOfRangeException or the exception defined in the MappaTypeMappingDefault attribute;
• Default: returns default;
• Null: returns null;
• MapSourceType: maps the source type to the target type of the method or the type specified in the MappaTypeMappingDefault attribute;
• InvokeMethod: invokes a method in the mapper with the name specified in MappaTypeMappingDefault to perform the mapping; MappaTypeMappingDefault can also specify the type on which the method is defined—in that case the method must be static. The method can optionally accept a MappaContext parameter.

Relevant packages:

• Mappa source generator: source generator that automatically generates mappings between classes and value types;
• Mappa Protobuf: methods to map Google.Protobuf.WellKnownTypes objects from the 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 the 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.