Messaging changes in Version 6

Component: NServiceBus

Using a custom correlation id

Custom correlation Id's for outgoing messages should now be set using the new Send/Reply or Publish options instead of being passed into bus.Send.

Remove WinIdName Header

The WinIdName existed to enable the Principal Replacement feature (RunHandlersUnderIncomingPrincipal in Version 4 and ImpersonateSender in Version 3).

See the Appending username using headers sample for usage of this API.

This feature was removed in Version 5 and the WinIdName header will no longer be added to outgoing messages.

To re-add this header to outgoing messages a mutator can be used.

6.x NServiceBus
public class WinIdNameMutator :
    public Task MutateOutgoing(MutateOutgoingTransportMessageContext context)
        var currentIdentity = Thread.CurrentPrincipal.Identity;
        context.OutgoingHeaders["WinIdName"] = currentIdentity.Name;
        return Task.CompletedTask;

Another option is to use a custom header as illustrated in Appending username using headers sample.


Requirements to throttling mechanisms are very different. While some 3rd party services (e.g. GitHub, Twitter, Google, etc.) enforce rate limits on certain time periods, other services may have entirely different usage limitations. The previous throttling API offered a very limited, messages per second based, throttling mechanism which only works for very few scenarios. Therefore, the throttling API has been removed with Version 6 without a built-in alternative.

The MaximumMessageThroughputPerSecond on the TransportConfig class has been marked as obsolete. Using a configuration based approach, the endpoint will fail to start when using the MaximumMessageThroughputPerSecond attribute on the <TransportConfig> element.

Immediate dispatch

Using a suppressed transaction scope to request sends to be dispatched immediately is still supported. However it is recommend to switch to the new explicit API for immediate dispatch.

Batched dispatch

Version 6 introduced the concept of Batched dispatch which means that outgoing operations won't dispatch to the transport until all the handlers of the current message have completed successfully. This helps reduce inconsistencies, in the form of "ghost" messages, being emitted due to exceptions during processing.

Deprecated Address

Version 5 represents addresses with an Address class. The Address class maintains addresses in the queue@host format. This format was originally developed for the MSMQ transport but does not meet the needs of other transports. In Version 6, addresses are represented as opaque strings.

Any usages of Address should be replaced by string.

Native sends via MSMQ

MsmqMessageSender and MsmqSettings are no longer available. Refer to native sends for other ways of sending raw messages via MSMQ.

Delayed Delivery

With the deprecation of IBus, message delivery can no longer be delayed with bus.Defer(). To delay a message, use the DelayDeliveryWith(TimeSpan) and DoNotDeliverBefore(DateTime) methods on SendOptions passed into Send().

6.x NServiceBus
var sendOptions = new SendOptions();
// OR
sendOptions.DoNotDeliverBefore(new DateTime(2016, 12, 25));

await handlerContext.Send(message, sendOptions)
5.x NServiceBus
bus.Defer(TimeSpan.FromMinutes(30), message);
// OR
bus.Defer(new DateTime(2016, 12, 25), message);

Message forwarding

The forwarded messages no longer contain additional auditing headers, such as processing start and end times, processing host id and name and processing endpoint.

Audit InvokedSagas Header

The InvokedSagas header added to audited messages populated with the name of the saga classes invoked along with their unique identifiers.

This functionality has been moved from the NServiceBus core to the SagaAudit plugin compatible with Version 6.

Last modified