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 to use

configure.MsmqTransport() has been obsoleted, use configure.UseTransport<Msmq>() instead.

Sagas

Enabling Sagas

The API for enabling sagas has changed.

4.x NServiceBus
Edit
Configure.Features.Enable<NServiceBus.Features.Sagas>();
3.x NServiceBus
Edit
configure.Sagas();
3.x NServiceBus
Edit
configure.Sagas();

ConfigureHowToFindSaga

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

4.x NServiceBus
Edit
public class OrderSaga :
    Saga<OrderSagaData>,
    IAmStartedByMessages<StartOrder>,
    IHandleMessages<CompleteOrder>
{
    public override void ConfigureHowToFindSaga()
    {
        ConfigureMapping<CompleteOrder>(message => message.OrderId)
            .ToSaga(sagaData => sagaData.OrderId);
    }
3.x NServiceBus
Edit
public class OrderSaga :
    Saga<OrderSagaData>,
    IAmStartedByMessages<StartOrder>,
    IHandleMessages<CompleteOrder>
{
    public override void ConfigureHowToFindSaga()
    {
        ConfigureMapping<CompleteOrder>(
            sagaData => sagaData.OrderId,
            message => message.OrderId);
    }

Change in behavior when no handler found

When a message is received for which there is 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.

4.x NServiceBus
Edit
var myMessage = new MyMessage();
bus.SetMessageHeader(
    msg: myMessage,
    key: "SendingMessage",
    value: "ValueSendingMessage");
bus.SendLocal(myMessage);
3.x NServiceBus
Edit
var myMessage = new MyMessage();
myMessage.SetHeader("SendingMessage", "ValueSendingMessage");
bus.SendLocal(myMessage);
3.x NServiceBus
Edit
var myMessage = new MyMessage();
myMessage.SetHeader("SendingMessage", "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.

4.x NServiceBus.Distributor.MSMQ
Edit
configure.RunMSMQDistributor();
3.x NServiceBus
Edit
configure.RunDistributor();

Enlisting with a Distributor

The API for enlisting with a distributor has changed.

4.x NServiceBus.Distributor.MSMQ
Edit
configure.EnlistWithMSMQDistributor();
3.x NServiceBus
Edit
configure.EnlistWithDistributor();

Persistence

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

RavenDB Version

Version 4 requires newer version of RavenDB. See also RavenDB Version Compatibility.

Timeouts

configure.RunTimeoutManagerWithInMemoryPersistence() has been obsoleted. Enable InMemory storage for timeouts using configure.UseInMemoryTimeoutPersister().

Default transaction isolation level

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

4.x NServiceBus
Edit
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.

4.x NServiceBus
Edit
Configure.Features.Disable<NServiceBus.Features.SecondLevelRetries>();
3.x NServiceBus
Edit
configure.DisableSecondLevelRetries();
3.x NServiceBus
Edit
configure.DisableSecondLevelRetries();

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 a a ambiguous reference error occurs fully qualify the usage of that interface. See also Life-cycle 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 has been expanded. See also License.

MsmqTransportConfig deprecated

The MsmqTransportConfig section has been deprecated in favor of TransportConfig.

4.x NServiceBus
Edit
<configuration>
  <configSections>
    <section name="TransportConfig"
             type="NServiceBus.Config.TransportConfig, NServiceBus.Core"/>
  </configSections>
  <TransportConfig MaximumConcurrencyLevel="5"
                   MaxRetries="2"
                   MaximumMessageThroughputPerSecond="0"/>
</configuration>
3.x NServiceBus
Edit
<configuration>
  <configSections>
    <section name="MsmqTransportConfig" 
             type="NServiceBus.Config.MsmqTransportConfig, NServiceBus.Core" />
  </configSections>
  <MsmqTransportConfig ErrorQueue="error" 
                       NumberOfWorkerThreads="1" 
                       MaxRetries="5"/>
</configuration>

PowerShell cmdlet Updates

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

Serialization

configure.JsonSerializer() has been obsoleted, 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 Version 4 to Version 3 an exception will be thrown and that message will be forwarded to the error queue. From there it can be handled manually and retried.

Logging

The NServiceBus NuGet package no longer depends on log4net and this means that if using log4net in Version 3 that dependency may be removed when doing a NuGet package upgrade. To solve this 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 the same as Handlers in their event subscription behavior. See Exclude sagas from auto subscribe for how to revert to the previous behavior.

Transaction settings

The configuration API's 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.

4.x NServiceBus
Edit
var unicastBus = configure.UnicastBus();
unicastBus.RunHandlersUnderIncomingPrincipal(true);
3.x NServiceBus
Edit
var unicastBus = configure.UnicastBus();
unicastBus.ImpersonateSender(true);
3.x NServiceBus
Edit
var unicastBus = configure.UnicastBus();
unicastBus.ImpersonateSender(true);

INeedToInstallInfrastructure

The INeedToInstallInfrastructure interface has been obsoleted and will be removed in Version 5.0. Use PowerShell commandlets as an alternative.


Last modified