Mappa 10.2.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;
• MappaDependencyInjection: Identifies a partial registrar class for which the Mappa source generator emits a method that registers [Mappa] mapper types into an IServiceCollection (same assembly by default; optionally additional assemblies via InjectFromAssemblies — see MappaDependencyInjection);
• 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; TargetPropertyName and SourcePropertyName may be a single name or a dot-separated chain of nested property names (for example "Address.City");
• 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; TargetPropertyName may be a single name or a dot-separated chain of nested property names;
• MappaMustMapTargetProperty: When mapping structured types via an empty constructor (or empty-constructor-like factory), requires that listed non-required target properties—or all of them when no names are provided—are mapped; otherwise generation fails with MP00065;
• MappaAllowInaccessibleSourceMembers: Opt-in to read private/protected source properties via generated UnsafeAccessor methods (flat names, or all when omitted); requires .NET 8+ / C# 12+;
• MappaAllowInaccessibleTargetMembers: Opt-in to write private/protected target properties and/or invoke inaccessible target constructors via generated UnsafeAccessor methods; AllowProperties / AllowConstructors control each kind (defaults true); requires .NET 8+ / C# 12+;
• MappaAssignFromContext: When mapping structured types, allows specifying which value from a MappaContext to use for a target property or constructor parameter; TargetPropertyName may be a single name or a dot-separated chain of nested property names;
• 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; TargetPropertyName may be a single name or a dot-separated chain of nested member names;
• 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; both TargetPropertyName and SourcePropertyName may be a single name or a dot-separated chain of nested property names;
• MappaAssignFromConstant: When mapping structured types, allows specifying a constant value for a target property or constructor parameter; TargetPropertyName may be a single name or a dot-separated chain of nested property names;
• MappaBeforeMap: Invokes a named hook immediately before the generated root mapping body; applies to mapper classes and mapping methods;
• MappaAfterMap: Invokes a named hook immediately after the generated root mapping body and before returning the target; applies to mapper classes and mapping methods;
• MappaObjectFactory: Forces construction of a target type via a named factory method instead of new; applies to mapper classes and mapping methods;
• MappaTypeMapping: When mapping structured types or interfaces, allows defining the target type depending on the source type; also available as MappaTypeMapping<TTarget, TSource>;
• MappaTypeMappingDefault: Describes the default behaviour for polymorphic methods defined via MappaTypeMapping; also available as MappaTypeMappingDefault<TDefault> for MapSourceType with an explicit target type.
• MappaMapEnumMember: Configures explicit enum↔integral, enum↔string, or enum↔enum member pairings;
• MappaMapEnumIgnore: Excludes a specific enum member from mapping;
• MappaMapEnumDefault: Configures fallback behaviour when an enum value cannot be mapped;

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, supply context to methods invoked via the MappaInvokeMethodAttribute attribute, supply context to before/after map hooks, or supply context to object factory methods. When ReferenceReusing or MaxRuntimeDepth is enabled, MappaContext also owns a private MappaReferenceManager used by generated code to track mapped references (keyed by source identity and typeof(TTarget)) and nesting depth. MappaContext is not thread-safe: use one instance per logical mapping operation and do not share a single instance across concurrent mappings without external synchronization.

Queryable projection: map methods with signature IQueryable<TSource> → IQueryable<TTarget> are handled by the generator as deferred Select projections for ORM providers. This is signature-driven and does not require a new attribute in this package. Generated projection methods are annotated with [RequiresDynamicCode] and are not compatible with Native AOT. See the tutorial and IQueryableProjectionMapper.cs.

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;
• PreventEnumerableCount: when enabled, avoids calling Enumerable.Count when mapping from a source without Count or Length to fixed-size targets such as T[], Span<T>, ReadOnlySpan<T>, Memory<T>, or ReadOnlyMemory<T>; a growable List<T> buffer is used so the source is enumerated only once;
• EnumerableConcreteType: selects whether mappings to sequence-like collection interfaces (for example IEnumerable<T>) use List<T> (default) or T[] as the concrete buffer;
• DictionaryAssignment: selects whether dictionary mappings insert entries via the indexer (Indexer, default) or IDictionary<TKey,TValue>.Add (Add);
• PolymorphicMapMethodWithMatchingDefaultAttribute: when enabled, MappaTypeMappingDefault can be used to locate an appropriate polymorphic method when looking for the mapping between two types;
• CompatibleMapMethod: when enabled, nested existing-method reuse may invoke a map method whose parameter is a base type or interface of the required source and whose return type is a derived type of the required target (disabled by default);
• 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).
• ReferenceReusing: when enabled, reuses already-mapped reference-type instances when the same source appears again (cycles / shared DAGs), keyed by source identity and declared TTarget. Requires MappaContext. Disabled by default.
• MaxRuntimeDepth: maximum runtime nesting depth (short; negative/-1 = unset/inherit; effective default 0 = unlimited). Requires MappaContext. Overflow throws MappaException.
• MaxCompileTimeDepth: maximum generator strategy-discovery depth (short; negative/-1 = unset/inherit; effective default 50; 0 disables). Generator-only.
• BreakCompileTimeCycles: when enabled, synthesizes private map methods at compile-time mapping-cycle edges instead of MP00077; reports MP00078. Generator-only; disabled by default. Pair with ReferenceReusing for runtime object cycles.

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.

Via MappaMapEnumDefaultBehavior the following settings can be tweaked:

• Throw: throws ArgumentOutOfRangeException when an enum value cannot be mapped (default);
• UseDefaultValue: returns the default value provided via [MappaMapEnumDefault] when an enum value cannot be mapped.

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.