# Upgrade Version 3 to 4




Upgrading a major dependency like NServiceBus requires careful planning, see the [general recommendations](/nservicebus/upgrades/index.md) article to learn more about the optimal upgrade process.



## Selecting [transports](/transports/index.md)

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


## [Sagas](/nservicebus/sagas/index.md)


### Enabling sagas

The API for enabling sagas has changed.

```cs
// --- 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.

```cs
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](/nservicebus/handlers/index.md).


## Critical errors

The API for defining critical errors has changed. See [Critical Errors](/nservicebus/hosting/critical-errors.md) for more information.


## Setting outgoing message headers

The API for setting outgoing message headers has changed:

```cs
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](/nservicebus/messaging/header-manipulation.md).


## Distributor


### Enabling a distributor

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

```cs
// --- 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](/persistence/non-durable/index.md) for timeouts using `configure.UseInMemoryTimeoutPersister()`.


## Default transaction isolation level

The default transaction [IsolationLevel](https://msdn.microsoft.com/en-us/library/system.transactions.isolationlevel.aspx) is now `ReadCommitted`. To revert to `Serializable`:

```cs
Configure.Transactions.Advanced(settings =>
    settings.IsolationLevel(IsolationLevel.Serializable));
```


## INeedToInstallInfrastructure is deprecated

Use `INeedToInstallSomething` instead. See also [NServiceBus Installers](/nservicebus/operations/installers.md).


## [Recoverability](/nservicebus/recoverability/index.md)

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.

```cs
// --- 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](/nservicebus/lifecycle/ineedinitialization.md).


## INeedToInstallSomething

The `INeedToInstallSomething` interface is now resolved via the container. See also [NServiceBus Installers](/nservicebus/operations/installers.md).


## License detection changes

The locations that NServiceBus will scan for a valid license have been expanded. See also [Licensing](/nservicebus/licensing/index.md).


## MsmqTransportConfig deprecated

The `MsmqTransportConfig` section has been deprecated in favor of `TransportConfig`.

```xml
<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](/transports/msmq/management-using-powershell.md) have moved to NServiceBus.PowerShell.dll.


## [Serialization](/nservicebus/serialization/index.md)

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

The [XmlSerializer](/nservicebus/serialization/xml.md) will now automatically escape outgoing messages containing invalid characters.

> [!WARNING]
> 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](/nservicebus/logging/index.md)

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](/nservicebus/logging/log4net.md).


## Sagas now auto-subscribe

Sagas have been changed to act similarly to handlers in their event subscription behavior. See [Exclude sagas from auto-subscribe](/nservicebus/messaging/publish-subscribe/controlling-what-is-subscribed.md#automatic-subscriptions-exclude-sagas-from-auto-subscribe) for details on how to revert to the previous behavior.


## Transaction settings

The [configuration APIs for transactions](/transports/transactions.md) 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:

```cs
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.