Logical mutators trimming and AOT improvements by danielmarbach · Pull Request #7925 · Particular/NServiceBus

danielmarbach · 2026-09-03T09:29:13Z

Summary

Short version: logical mutators can now replace the incoming or outgoing message with a declared logical type instead of relying on the runtime type, and the migration analyzer from #7889 steers existing setter-based mutators toward those APIs.

Today a mutator that replaces the message instance assigns the plain context property (mutatorContext.Message = ... or mutatorContext.OutgoingMessage = ...). When the replacement switches types, the logical message type comes from newInstance.GetType() downstream, which the trimmer and NativeAOT cannot analyze. The object-only UpdateMessageInstance(object) on the incoming pipeline context has the same problem.

This PR adds typed replacement APIs on both mutator contexts and the incoming pipeline context, threads the declared type through the mutator behaviors, and extends the migration analyzer so the legacy pattern gets the same NSB0039/NSB0040 diagnostics the Send/Publish/Reply/UpdateMessage family already has. With #7918 merged, the declared type resolves through the registered metadata cache, so the new path is compatible with strict registered-only mode.

This continues the migration family tracked in #7906 and completes the logical-mutator half of the proposal deferred from #7889. The three commits are separate review seams: the runtime and API change, the analyzer extension for property assignment, and analyzer symmetry for UpdateMessageInstance invocations.

Compatibility boundary

All new members are additive. Ordinary calls keep binding to the object members because the generic overloads carry [OverloadResolutionPriority(-1)]. Existing code behaves exactly as before.
IIncomingLogicalMessageContext.UpdateMessageInstance(object) remains available and is marked [PreObsolete] and [RequiresUnreferencedCode], mirroring IOutgoingLogicalMessageContext.UpdateMessage(object) from Add trimming-safe messaging overloads and migration analyzer #7889. Default interface method fallbacks delegate to the object member for binary compatibility; third-party implementations keep working unchanged.
New interface members carry the DAM annotation DynamicMemberTypeAccess.Message on the generic type parameter and the explicit Type parameter, the same contract the other typed existing-message overloads use.
MessageTypeValidator rejects replacement instances that are not assignable to the declared type, both in the pipeline contexts and the mutator contexts.
Under strict registered-only metadata mode, the declared type must be registered up front through handlers, sagas, or AddMessageType<T>(). A strict cache miss fails with the existing actionable exception instead of silently falling back to hierarchy reflection.
The declared type flows from the mutator context to the pipeline context through an internal property that carries the same DAM annotation, so the trimmer preserves the member requirements across that handoff.

What changed

Typed replacement on the incoming pipeline context

IIncomingLogicalMessageContext gains two members: the generic UpdateMessageInstance<T>(T) and the explicit UpdateMessageInstance(object, Type). The concrete IncomingLogicalMessageContext resolves replacement metadata through LogicalMessageFactory.Create(messageType, instance) without reflecting over the instance, and keeps the existing object overload untouched.

The replacement also carries the conservative same-instance semantics from UpdateMessage: re-supplying the same instance with the same logical type is a metadata no-op, while a different declared type rebuilds metadata even when the instance has not changed. TestableIncomingLogicalMessageContext mirrors the typed members as virtual members, following the outgoing fake from #7889.

Declared-type replacement on the mutator contexts

MutateIncomingMessageContext.UpdateMessageInstance and MutateOutgoingMessageContext.UpdateMessage accept either a typed instance or an instance plus an explicit annotated Type. The declared type is stored on an internal DAM-annotated carrier property. When a mutator supplied a declared type, the behaviors call the typed pipeline overloads; otherwise they fall back to the legacy object path. The required IL2026 for that fallback is recorded in the trimmability-approval file, as the outgoing behavior already did.

The plain property setters are deprecated with warning as part of this PR: the set accessors carry the Particular obsoletion pair ([ObsoleteMetadata] + [Obsolete], treated as an error from version 11, removed in version 12). Accessor-level obsoletion warns only on assignments and leaves the getter untouched, which matters because in-place mutation of the current message remains supported. The analyzer diagnostics and fixers still apply on top: NSB0039 rewrites safe assignments to the typed calls and NSB0040 flags the risky ones without a fix, so users get risk-graded guidance plus the compile-time warning signal. Setter removal joins the object-overload removal batch in the next major; the scope is now recorded in #7906.

Migration analyzer coverage

MessagingMigrationAnalyzer now recognizes assignment to the mutator context setters through simple-assignment analysis, matched by symbol rather than by property name. Safe assignments (direct creation, sealed types, non-nullable value types) report NSB0039 and the fixer rewrites them to the typed calls; unprovable assignments report NSB0040 without a fix, since replacing the logical type is a routing decision. Assignments use the conservative UpdateMessage classification because the setter path preserves the previous logical type when the same instance is re-assigned. Object-typed assignments and NSB0041 do not apply here.

The object-only UpdateMessageInstance(object) invocation is now diagnosed like UpdateMessage(object) was, including calls against the testing fake. The existing invocation fixer covers it unchanged.

Follow-ups

Remove the object-only UpdateMessageInstance and the mutator context setters with the rest of the family in the next major, as described in Remove legacy object-only messaging overloads in NServiceBus 11 #7906.
Document the typed replacement APIs in the mutator migration guidance for trimming and NativeAOT users.

Please challenge the compatibility assumptions, especially the chosen escalation for the newly deprecated setters (warn in 10.3, error from 11, removed in 12) and the interaction with the analyzer diagnostics on the same assignment.

danielmarbach · 2026-09-03T09:35:46Z

    public object OutgoingMessage
    {
        get => outgoingMessage;
        set


Should we go ahead and obsolete the setter with a warning (see PR description)?

danielmarbach · 2026-09-03T09:36:01Z

    public object Message
    {
        get => message;
        set


Should we go ahead and obsolete the setter with a warning (see PR description)?

I would vote yes. The methods are much more intention revealing anyway.

Add typed replacement APIs so incoming and outgoing instance mutators can declare the logical message type instead of relying on runtime type discovery: - IIncomingLogicalMessageContext gains UpdateMessageInstance<T>(T) and UpdateMessageInstance(object, Type) following the typed UpdateMessage precedent on IOutgoingLogicalMessageContext, with PreObsolete and RequiresUnreferencedCode on the runtime-type-routing object overload - IncomingLogicalMessageContext resolves replacement metadata through LogicalMessageFactory without reflection over the instance, preserving strict registered-only metadata mode - MutateIncomingMessageContext.UpdateMessageInstance and MutateOutgoingMessageContext.UpdateMessage accept typed or explicitly typed replacements and carry the declared type via a DAM-annotated internal property - Mutator behaviors pass the declared type into the pipeline contexts, keeping the legacy object path untouched - TestableIncomingLogicalMessageContext mirrors the typed members

The legacy mutator pattern assigns an object to the Message or OutgoingMessage property of a mutator context, which routes by the runtime type. Analyze SimpleAssignment operations on those two setters and reuse the existing NSB0039/NSB0040 classification (direct creation and value types are provably safe; everything else is a runtime-type routing warning), gated by the same trimming/AOT build properties. The code fixer rewrites a safe assignment to the typed replacement API: - context.Message = new MyMessage() -> context.UpdateMessageInstance<MyMessage>(new MyMessage()) - context.OutgoingMessage = new MyEvent() -> context.UpdateMessage<MyEvent>(new MyEvent())

danielmarbach · 2026-09-03T09:45:58Z

I think this is the last "edge"

DavidBoike · 2026-09-03T14:00:03Z

    public object Message
    {
        get => message;
        set


I would vote yes. The methods are much more intention revealing anyway.

The Message and OutgoingMessage setters on the logical mutator contexts route by the runtime type, which the trimmer cannot analyze. The typed UpdateMessage/UpdateMessageInstance APIs added in this branch are the replacement, so the setters now warn on assignment using the Particular.Obsoletes authoring pair (error from 11, removed in 12). The setter-level attribute leaves the getter silent, verified on the current compiler. The typed methods assign the backing field directly to avoid self-triggered warnings, and deliberate legacy-path test coverage is pragma-suppressed until the setters are removed with the object-overload batch tracked in #7906.

…ther RequiresUnreferencedCode is used (#7928)

danielmarbach added this to the 10.3.0 milestone Sep 3, 2026

danielmarbach added the Improvement label Sep 3, 2026

internalautomation Bot assigned danielmarbach Sep 3, 2026

danielmarbach commented Sep 3, 2026

View reviewed changes

danielmarbach force-pushed the logical_mutators branch from b4a9c4b to 816183f Compare September 3, 2026 09:41

danielmarbach added 3 commits September 3, 2026 11:44

Add incoming UpdateMessageInstance coverage to the migration analyzer

ccfc991

danielmarbach force-pushed the logical_mutators branch from 816183f to ccfc991 Compare September 3, 2026 09:44

danielmarbach requested review from DavidBoike and andreasohlund September 3, 2026 09:45

DavidBoike reviewed Sep 3, 2026

View reviewed changes

danielmarbach and others added 5 commits September 3, 2026 17:28

Simplify

1d7b442

Simplify interface method

165451a

Suppress mutator warnings because code path only reachable if using o…

a31329d

…ther RequiresUnreferencedCode is used (#7928)

Fix property name in outgoing mutator suppression justification

75a4fa1

danielmarbach requested a review from DavidBoike September 3, 2026 20:10

DavidBoike approved these changes Sep 3, 2026

View reviewed changes

danielmarbach merged commit 7bb5a57 into master Sep 4, 2026
4 checks passed

danielmarbach deleted the logical_mutators branch September 4, 2026 09:48

Navigation Menu

Uh oh!

Logical mutators trimming and AOT improvements - #7925

Logical mutators trimming and AOT improvements#7925
danielmarbach merged 8 commits into
masterfrom
logical_mutators

danielmarbach commented Sep 3, 2026 •

edited

Loading

Uh oh!

danielmarbach Sep 3, 2026

Uh oh!

danielmarbach Sep 3, 2026

Uh oh!

DavidBoike Sep 3, 2026

Uh oh!

danielmarbach commented Sep 3, 2026

Uh oh!

DavidBoike Sep 3, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

danielmarbach commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Compatibility boundary

What changed

Typed replacement on the incoming pipeline context

Declared-type replacement on the mutator contexts

Migration analyzer coverage

Follow-ups

Uh oh!

danielmarbach Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

danielmarbach Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

DavidBoike Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

danielmarbach commented Sep 3, 2026

Uh oh!

DavidBoike Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

danielmarbach commented Sep 3, 2026 •

edited

Loading