Logical message stage(s) should be "split"

[boblangley]

Describe the suggested improvement

Is your improvement related to a problem? Please describe.

When inserting a behavior into a stage sometimes there is a need to order the behaviors in order for the inserted behavior to work correctly. This is much more common in the incoming logical message stages, especially surrounding messages that further manipulate the data in the logical message such as databus receive/send or encryption/decryption.

In these cases, a behavior that acts on the logical message, but relies on one of those other messages to "finalize" the message, must be executed before (incoming)/after (outgoing). We have an undocumented "InsertAfter" API to help control that, but this becomes unwieldy when using multiple features that must be executed before (or after in the case of outgoing) the new behavior.

A practical example of when this is important would be with the persisters such as CosmosDB that operation on partitioned data, where the user can provide a func against the incoming message to determine the partition key to use. In these cases that func, which is run by a behavior injected by the persister, must be run before all behaviors that further manipulate the values of the message properties, so the func can act on those property values.

Describe the suggested solution

There is a distinction between behaviors that "finalize" a message post-deserialization, and behaviors that act on the message data (a common place customers would create a new behavior for). By "splitting" the logical message stages, either by renaming both or adding a new stage after the incoming logical stage or before the outgoing logical message stage this would semantically be better and may remove most, if not all, use-cases for the "InsertBefore" or "InsertAfter" APIs.

Describe alternatives you've considered

None.

Additional Context

No response