feat: add [MapperNoInlining] attribute and MapperAttribute.NoInlining property

[trejjam]

feat: add [MapperNoExpressionInliningAttribute] attribute and MapperAttribute.NoExpressionInlining property

Description

When a mapper referenced via [UseStaticMapper] is used from a mapper that has IQueryable projection methods, Mapperly attempts to inline or rebuild the referenced mapping methods into expression trees. For enum mappings configured with EnumMappingStrategy.ByName where the source and target enums have different underlying types, this rebuild in expression context produces false RMG037/RMG038 diagnostics — reporting all enum members as unmapped even though they match by name.

I understand the rationale behind the expression-context restrictions for the general case, and the 5.x alpha series has been catching up and tightening these rules further, which makes sense. However, in my project I was relying on [UseStaticMapper] with enum-by-name mappings in queryable projections, and the stricter inlining behavior broke that usage. We've discussed the projection + enum + inlining interaction before.

This PR adds a general opt-out mechanism for expression-tree inlining:

• [MapperNoInlining] — method-level attribute to prevent a specific mapping method from being inlined/rebuilt in expression context
• [Mapper(NoInlining = true)] — mapper-level property to prevent all methods of a mapper from being inlined when referenced via [UseStaticMapper]

Both are applied on the callee mapper (the one being referenced), not the consuming mapper.

Example

// Per-method opt-out
[Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName)]
public static partial class EnumMapper
{
    [MapperNoInlining]
    public static partial TargetStatus MapToStatus(this SourceStatus source);
}

// Or per-mapper opt-out
[Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName, NoExpressionInlining = true)]
public static partial class EnumMapper
{
    public static partial TargetStatus MapToStatus(this SourceStatus source);
}

When inlining is disabled, the method call is preserved as-is in the expression tree. The ORM evaluates it client-side instead of attempting to translate it to SQL.

Changes

• New MapperNoExpressionInliningAttribute marker attribute (AttributeTargets.Method)
• New NoExpressionInlining property on MapperAttribute (default: false)
• Check in InlineExpressionMappingBuilderContext.TryInlineMapping() before dispatching to inline/rebuild
• Configuration pipeline wired through MapperConfiguration and MapperConfigurationMerger
• Tests covering: bug repro, method-level attribute, mapper-level property, combined, non-projection (no effect)
• Documentation in queryable projections guide with runtime behavior comparison

Disclosure: This PR was produced with AI assistance. All code has been manually reviewed, verified, and iteratively refined by me to ensure correctness and adherence to project guidelines.

Checklist

• I did not use AI tools to generate this PR, or I have manually verified that the code is correct, optimal, and follows the project guidelines and architecture
• I understand that low-quality, AI-generated PRs will be closed immediately without further explanation
• The existing code style is followed
• The commit message follows our guidelines
• Performed a self-review of my code
• Hard-to-understand areas of my code are commented
• The documentation is updated (as applicable)
• Unit tests are added/updated
• Integration tests are added/updated (as applicable, especially if feature/bug depends on roslyn or framework version in use)

[trejjam]

Rebased on main

[trejjam]

I have created a modified version with configuration on the UseStaticMapper:
trejjam#1
if you would prefer it.

This also let you control not-inlining of not-owned code

[trejjam]

Hi, can I do something to finalize this PR?
While working on it, I found this variant better:

[Mapper]
[UseStaticMapper(typeof(EnumMapper), NoExpressionInlining = true)]
// or:
[UseStaticMapper<EnumMapper>(NoExpressionInlining = true)]
partial class Mapper{}

It replaces the:

[Mapper]
[UseStaticMapper(typeof(EnumMapper))]
partial class Mapper {}

[Mapper(NoExpressionInlining = true)]
partial class EnumMapper {}

What is your opinion?

The code for it is here:
trejjam#1 I can recreate this PR with the [UseStaticMapper(typeof(EnumMapper), NoExpressionInlining = true)] if you also prefer it.

[latonz]

@trejjam, this would only allow the setting to be configured for imported mappers, correct? I think we need to support both: setting it on the mapper itself and overriding it for an imported mapper via UseStaticMapper.

IMO, the biggest issue with the current implementation is that the setting isn’t resolved correctly from imported mappers. Adding it to UseStaticMapper/UseMapper would fix that, but it shouldn’t replace the existing mapper-level setting, should it? This setting is also helpful within the same mapper…

[trejjam]

Hello @latonz
I hope I understand. I will try to create a little specification:

The new [MapperNoExpressionInlining] on methods. This prevents its mapper class from inlining its body:

record Source(ESource Value);
record Target(ETarget Value);

record Source2(ESource Value);
record Target2(ETarget Value);

[Mapper]
partial class MapperWithNoExprInlining
{
  [MapperNoExpressionInlining]
  partial ETarget MapToETarget(ESource source);

  partial Target MapToTarget(Source source); // no - inlining allowed for MapToETarget
}


[Mapper]
[UseStaticMapper(typeof(MapperWithNoExprInlining))]
partial class Mapper
{
  partial Target2 MapToTarget(Source2 source); // inlined - the inlining is blocked only in the owning MapperWithNoExprInlining
}

---

The [Mapper(NoExpressionInlining = true)] blocks inlining for all "owned" methods:

record Source(ESource Value);
record Target(ETarget Value);

record Source2(ESource Value);
record Target2(ETarget Value);

[Mapper(NoExpressionInlining = true)]
partial class MapperWithNoExprInlining
{
  partial ETarget MapToETarget(ESource source);

  partial Target MapToTarget(Source source); // no - inlining allowed for MapToETarget
}


[Mapper]
[UseStaticMapper(typeof(MapperWithNoExprInlining))]
partial class Mapper
{
  partial Target2 MapToTarget(Source2 source); // inlined - the inlining is blocked only in the owning MapperWithNoExprInlining
}

---

The [UseStaticMapper(typeof(...), NoExpressionInlining = true)] blocks inlining for all imported methods:

record Source(ESource Value);
record Target(ETarget Value);

record Source2(ESource Value);
record Target2(ETarget Value);

[Mapper]
partial class SourcedMapper
{
  partial ETarget MapToETarget(ESource source);

  partial Target MapToTarget(Source source); // inlining allowed for MapToETarget
}


[Mapper]
[UseStaticMapper(typeof(SourcedMapper), NoExpressionInlining = true)]
partial class Mapper
{
  partial Target2 MapToTarget(Source2 source); // MapToETarget is not inlined - the inlining is blocked for SourcedMapper imported methods
}

---

Do you like it to work this way? It should fix the not-scoped configuration read

[latonz]

#2240 (comment)

Thanks for writing up the spec. I don’t particularly like this behavior from a user’s perspective, as it feels a bit unintuitive, but I think it’s the only way to support all three scopes and still resolving the configuration correctly…

[trejjam]

I agree, I will modify the PR according to it when I have a spare moment.
Feel free to change the spec in the meantime if you find something better.

[latonz]

Implementation of latest spec proposal…

[trejjam]

Hi, it should be implemented according to the spec above.