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. is obsolete; use configure. 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. is obsolete. Enable InMemory storage for timeouts using configure..
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. namespace to the NServiceBus. 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. has been renamed to NServiceBus..
INeedInitialization moved
The interface INeedInitialization has been moved from NServiceBus. to NServiceBus.. 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. is obsolete; use Configure. 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.
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. instead of the deprecated configure..
Adjusting transaction isolation level
configure. has been deprecated; use Configure. instead.
Adjusting transaction timeouts
configure. has been deprecated; use Configure. 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.