Upgrade Version 3 to 4

Component: NServiceBus

Upgrading a major dependency like NServiceBus requires careful planning, see the general recommendations article to learn more about the optimal upgrade process.

Selecting transports

configure.MsmqTransport() is obsolete; use configure.UseTransport<Msmq>() instead.


Enabling sagas

The API for enabling sagas has changed.

// --- NServiceBus 3.x ---
// configure.Sagas();

// --- NServiceBus 4.x ---


The API for configuring how to map a message to a saga has changed.

public class OrderSaga :
    public override void ConfigureHowToFindSaga()
        // --- NServiceBus 3.x ---
        // ConfigureMapping<CompleteOrder>(
        //     sagaData => sagaData.OrderId,
        //     message => message.OrderId);

        // --- NServiceBus 4.x ---
        ConfigureMapping<CompleteOrder>(message => message.OrderId)
            .ToSaga(sagaData => sagaData.OrderId);

Change in behavior when no handler found

When a message is received for which there are no message handlers, it is now considered an error and the received message will be forwarded to the configured error queue.

For more information, see Handling a Message.

Critical errors

The API for defining critical errors has changed. See Critical Errors for more information.

Setting outgoing message headers

The API for setting outgoing message headers has changed:

var myMessage = new MyMessage();

// --- NServiceBus 3.x ---
// myMessage.SetHeader("SendingMessage", "ValueSendingMessage");

// --- NServiceBus 4.x ---
                msg: myMessage,
                key: "SendingMessage",
                value: "ValueSendingMessage");


See also Header Manipulation.


Enabling a distributor

The API for enabling an endpoint to behave as a distributor has changed:

// --- NServiceBus 3.x ---
// configure.RunDistributor();

// --- NServiceBus 4.x ---

Enlisting with a distributor

The API for enlisting with a distributor has changed:

// --- NServiceBus 3.x ---
// configure.EnlistWithDistributor();

// --- NServiceBus 4.x ---


The API to select persistence has been changed in NServiceBus version 4. See below for details.

RavenDB version

NServiceBus version 4 requires a later version of RavenDB.


configure.RunTimeoutManagerWithInMemoryPersistence() is obsolete. Enable InMemory storage for timeouts using configure.UseInMemoryTimeoutPersister().

Default transaction isolation level

The default transaction IsolationLevel is now ReadCommitted. To revert to Serializable:

Configure.Transactions.Advanced(settings =>

INeedToInstallInfrastructure is deprecated

Use INeedToInstallSomething instead. See also NServiceBus Installers.


The type SecondLevelRetries has been moved from the NServiceBus.Management.Retries namespace to the NServiceBus.Features namespace.


The API for disabling SecondLevelRetries has changed.

// --- NServiceBus 3.x ---
// configure.DisableSecondLevelRetries();

// --- NServiceBus 4.x ---


The type NServiceBus.Unicast.Transport.Transsactional.TransactionalTransport has been renamed to NServiceBus.Unicast.Transport.TransportReceiver.

INeedInitialization moved

The interface INeedInitialization has been moved from NServiceBus.Config.INeedInitialization to NServiceBus.INeedInitialization. If an ambiguous reference error occurs, fully qualify the usage of that interface. See also Lifecycle Initialization.


The INeedToInstallSomething interface is now resolved via the container. See also NServiceBus Installers.

License detection changes

The locations that NServiceBus will scan for a valid license have been expanded. See also Licensing.

MsmqTransportConfig deprecated

The MsmqTransportConfig section has been deprecated in favor of TransportConfig.


        <!-- NServiceBus 3.x
        <section name="MsmqTransportConfig" 
             type="NServiceBus.Config.MsmqTransportConfig, NServiceBus.Core" /> -->

        <!-- NServiceBus 4.x -->
        <section name="TransportConfig"
            type="NServiceBus.Config.TransportConfig, NServiceBus.Core"/>


    <!-- NServiceBus 3.x
    <MsmqTransportConfig ErrorQueue="error" 
        MaxRetries="5"/> -->

    <!-- NServiceBus 4.x -->
    <TransportConfig MaximumConcurrencyLevel="5"


PowerShell cmdlet updates

NServiceBus PowerShell cmdlets have moved to NServiceBus.PowerShell.dll.


configure.JsonSerializer() is obsolete; use Configure.Serialization.Json(); instead.

The XmlSerializer will now automatically escape outgoing messages containing invalid characters.

If a message with encoded characters is sent from an NServiceBus version 4 endpoint to a version 3 endpoint, an exception will be thrown and that message will be forwarded to the error queue. From there, it can be handled manually and retried.


The NServiceBus NuGet package no longer depends on log4net; this dependency can be removed when upgrading the NuGet package and install the latest log4net version 1.2 package into the project. See also Integrating with log4net.

Sagas now auto-subscribe

Sagas have been changed to act similarly to handlers in their event subscription behavior. See Exclude sagas from auto-subscribe for details on how to revert to the previous behavior.

Transaction settings

The configuration APIs for transactions have changed.

Disabling transactions

To disable transactions when receiving, use Configure.Transactions.Disable(); instead of the deprecated configure.DontUseTransactions();.

Adjusting transaction isolation level

configure.IsolationLevel(level) has been deprecated; use Configure.Transactions.Advanced(x => x.IsolationLevel(level)) instead.

Adjusting transaction timeouts

configure.TransactionTimeout(timeout) has been deprecated; use Configure.Transactions.Advanced(x => x.DefaultTimeout(timeout)) instead.

Rename principal replacement

The principal replacement API has been renamed:

var unicastBus = configure.UnicastBus();

// --- NServiceBus 3.x ---
// unicastBus.ImpersonateSender(true);

// --- NServiceBus 4.x ---


The INeedToInstallInfrastructure interface is obsolete and will be removed in NServiceBus version 5.0. Use PowerShell commandlets as an alternative.

Last modified