Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

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.

Sagas

Enabling sagas

The API for enabling sagas has changed.

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

// --- NServiceBus 4.x ---
Configure.Features.Enable<NServiceBus.Features.Sagas>();

ConfigureHowToFindSaga

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

public class OrderSaga :
    Saga<OrderSagaData>,
    IAmStartedByMessages<StartOrder>,
    IHandleMessages<CompleteOrder>
{
    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 ---
bus.SetMessageHeader(
                msg: myMessage,
                key: "SendingMessage",
                value: "ValueSendingMessage");

bus.SendLocal(myMessage);

See also Header Manipulation.

Distributor

Enabling a distributor

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

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

// --- NServiceBus 4.x ---
configure.RunMSMQDistributor();

Enlisting with a distributor

The API for enlisting with a distributor has changed:

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

// --- NServiceBus 4.x ---
configure.EnlistWithMSMQDistributor();

Persistence

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.

Timeouts

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 =>
    settings.IsolationLevel(IsolationLevel.Serializable));

INeedToInstallInfrastructure is deprecated

Use INeedToInstallSomething instead. See also NServiceBus Installers.

Recoverability

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

Disabling

The API for disabling SecondLevelRetries has changed.

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

// --- NServiceBus 4.x ---
Configure.Features.Disable<NServiceBus.Features.SecondLevelRetries>();

TransactionalTransport

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.

INeedToInstallSomething

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.

<configuration>
    <configSections>

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

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

    </configSections>

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

    <!-- NServiceBus 4.x -->
    <TransportConfig MaximumConcurrencyLevel="5"
        MaxRetries="2"
        MaximumMessageThroughputPerSecond="0"/>

</configuration>

PowerShell cmdlet updates

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

Serialization

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

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

Logging

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 ---
unicastBus.RunHandlersUnderIncomingPrincipal(true);

INeedToInstallInfrastructure

The INeedToInstallInfrastructure interface is obsolete and will be removed in NServiceBus version 5.0.