This is part of the NServiceBus Upgrade Guide from Version 5 to 6, which also includes the following individual upgrade guides for specific components:
Feature Details
- Assembly Scanning Changes in NServiceBus Version 6
- No Async Suffix
- Dependency Injection Changes in NServiceBus Version 6
- Deprecated TransportMessage in NServiceBus Version 6
- Endpoint API changes in NServiceBus Version 6
- Extension Seam Changes in NServiceBus Version 6
- Migrate handlers and sagas to Version 6
- Header API changes in NServiceBus Version 6
- Messaging Changes in NServiceBus Version 6
- Moving away from IBus in Version 6
- Recoverability Changes in Version 6
- Serialization Changes in NServiceBus Version 6
- Subscription Changes in NServiceBus Version 6
- Transaction Configuration Changes in NServiceBus Version 6
Transports
- Azure Service Bus Transport (Legacy) Upgrade Version 6 to 7
- RabbitMQ Transport Upgrade Version 3 to 4
- SQL Server Transport Upgrade Version 2 to 3
- SQL Server Transport Upgrade - Supporting Unicode in Headers
Persistence
- Upgrade from NServiceBus Azure Version 6
- NHibernate Persistence Upgrade Version 6 to 7
- NHibernate Persistence - Resolving incorrect timeout table indexes
- RavenDB Persistence Upgrade from 3 to 4
Hosting
Other
- Moving to the DataBus AzureBlobStorage Package
- Azure Cloud Services Host Upgrade Version 6 to 7
- NServiceBus.Azure package deprecated
- Gateway Upgrade Version 1 to 2
- NServiceBus Testing Upgrade Version 5 to 6
- Callback Changes in NServiceBus Version 6
- Migrating the distributor to use sender-side distribution
- Tool and Helper Changes in NServiceBus Version 6
Timeout storage
IPersistTimeouts
has been split into two interfaces, IPersistTimeouts
and IQueryTimeouts
, to separate those storage concerns. Both must be implemented to have a fully functional timeout infrastructure.
IQueryTimeouts
implements the concern of polling for timeouts outside the context of a message pipeline. IPersistTimeouts
implements the concern of storage and removal for timeouts which is executed inside the context of a pipeline. Depending on the design of the timeout persisters, those concerns can now be implemented independently. Furthermore, IPersistTimeouts
introduced a new parameter TimeoutPersistenceOptions
. This parameter allows access to the pipeline context. This enables timeout persisters to manipulate everything that exists in the context during message pipeline execution.
Outbox
IOutboxStorage
introduced a new parameter OutboxStorageOptions
. This parameter provides access to the pipeline context. This enables outbox storage methods to manipulate everything that exists in the context during message pipeline execution.
Queue creation
In NServiceBus version 5, the implementation of the interface ICreateQueues
was called for each queue that needed to be created. In version 6, ICreateQueues
has been redesigned. The implementation of the interface is called once but with all queues provided on the QueueBindings
object. It is now up to the implementation of that interface to determine if the queues are created asynchronously in a sequential order or even in parallel.
// For NServiceBus version 6.x
public class FeatureThatRequiresAQueue :
Feature
{
protected override void Setup(FeatureConfigurationContext context)
{
var queueBindings = context.Settings.Get<QueueBindings>();
queueBindings.BindReceiving("someQueue");
}
}
class YourQueueCreator :
ICreateQueues
{
public async Task CreateQueueIfNecessary(QueueBindings queueBindings, string identity)
{
// create the queues here
}
}
// For NServiceBus version 5.x
public class QueueRegistration :
IWantQueueCreated
{
public QueueRegistration(Address queueAddress)
{
Address = queueAddress;
}
public Address Address { get; }
public bool ShouldCreateQueue()
{
return true;
}
}
public class FeatureThatRequiresAQueue :
Feature
{
protected override void Setup(FeatureConfigurationContext context)
{
var container = context.Container;
container.ConfigureComponent(
componentFactory: () =>
{
return new Transports.QueueRegistration(Address.Parse("someQueue"));
},
dependencyLifecycle: DependencyLifecycle.InstancePerCall);
}
}
class YourQueueCreator :
ICreateQueues
{
public void CreateQueueIfNecessary(Address address, string account)
{
// create the queues here
}
}
See also Transport-specific queue creation.
Features
Removed FeaturesReport
FeaturesReport
exposed reporting information about features of a running endpoint instance. It has been internalized. As with previous versions, the information is still available by inspecting the DisplayDiagnosticsForFeatures
logger when the endpoint runs with log level DEBUG
.
Feature dependencies
Feature dependencies, using the string API, are now declared using the target feature's full type name (Type.
) which includes the namespace. Removing the Feature
suffix is no longer required.
// For NServiceBus version 6.x
public class DependentFeature :
Feature
{
public DependentFeature()
{
DependsOn("Namespace.DependencyB");
DependsOnAtLeastOne("Namespace.DependencyC", "Namespace.DependencyD");
}
// For NServiceBus version 5.x
public class DependentFeature :
Feature
{
public DependentFeature()
{
DependsOn("DependencyB");
DependsOnAtLeastOne("DependencyC", "DependencyD");
}
Satellites
ISatellite and IAdvancedSatellite interfaces are obsolete
Both the ISatellite
and the IAdvancedSatellite
interfaces are deprecated. The same functionality is available via the AddSatelliteReceiver
method on the context passed to the features Setup
method. The satellite documentation shows more detail.
Performance counters
Satellite pipelines (e.g. retries or timeouts) no longer create performance counters. Endpoints provide a single performance counter instance related to the main message processing pipeline.
To learn more about using performance counters, refer to the performance counter usage sample and the performance counters article.
Transport seam
IDequeueMessages
is now obsolete and has been replaced by IPushMessages
. The interfaces are equivalent so when creating a transport, implement the new interface. PushContext
has been given a new property PushContext.
, revealing the intent of cancellation for receiving the current message. The transport implementation should act accordingly, canceling the receive when the source's token is canceled.
The ConfigureTransport
class was deprecated. Custom transports are now configured using the TransportDefinition
class.
Corrupted messages
The core will now pass the error queue address to the transport to make it easier to handle corrupted messages. If a corrupted message is detected the transport is expected to move the message to the specified error queue.
Unit of work
In Versions 6 and above IManageUnitsOfWork
does not have access to the incoming message context. If access to headers and/or message body is required instead implement a unit of work using behaviors instead.