Upgrade Version 6 to 7

Component: NServiceBus
This page targets a pre-release version and is subject to change prior to the final release.

Upgrading a major dependency like NServiceBus requires careful planning, see the general recommendations article to learn more about the optimal upgrade process.

Config

The Configuration APIs IProvideConfiguration, IConfigurationSource and CustomConfigurationSource have been deprecated. Code based API can be used instead.

Audit

Configuring Audit via the following APIs have been deprecated:

  • IProvideConfiguration<AuditConfig>
  • AuditConfig in an app.config configSections
  • Returning a AuditConfig from a IConfigurationSource
  • HKEY_LOCAL_MACHINE\SOFTWARE\ParticularSoftware\ServiceBus\AuditQueue registry key

Instead use one of the following:

Configure by the code API

7-pre NServiceBus
endpointConfiguration.AuditProcessedMessagesTo(
    auditQueue: "targetAuditQueue",
    timeToBeReceived: TimeSpan.FromMinutes(10));

Read from an AppSettings and configure by the code API

7-pre NServiceBus
<configuration>
  <appSettings>
    <add key="AuditQueue" value="targetAuditQueue" />
    <add key="TimeToBeReceived" value="00:10:00" />
  </appSettings>
</configuration>
7-pre NServiceBus
var appSettings = ConfigurationManager.AppSettings;
var auditQueue = appSettings.Get("auditQueue");
var timeToBeReceived = TimeSpan.Parse(appSettings.Get("timeToBeReceived"));
endpointConfiguration.AuditProcessedMessagesTo(
    auditQueue: auditQueue,
    timeToBeReceived: timeToBeReceived);

Logging

Configuring Logging via the following APIs have been deprecated:

  • IProvideConfiguration<Logging>
  • Logging in an app.config configSections

Instead use one of the following:

Configure by the code API

7-pre NServiceBus
var logFactory = LogManager.Use<DefaultFactory>();
logFactory.Level(LogLevel.Info);

Read from an AppSettings and configure by the code API

7-pre NServiceBus
<appSettings>
  <add key="LoggingThreshold" value="Debug" />
</appSettings>
7-pre NServiceBus
var appSettings = ConfigurationManager.AppSettings;
var level = (LogLevel)Enum.Parse(typeof(LogLevel), appSettings.Get("LoggingThreshold"));
var logFactory = LogManager.Use<DefaultFactory>();
logFactory.Level(level);

Error Queue

Configuring the error queue via the following APIs have been deprecated:

  • IProvideConfiguration<MessageForwardingInCaseOfFaultConfig>
  • MessageForwardingInCaseOfFaultConfig in an app.config configSections
  • Returning a MessageForwardingInCaseOfFaultConfig from a IConfigurationSource
  • HKEY_LOCAL_MACHINE\SOFTWARE\ParticularSoftware\ServiceBus\ErrorQueue registry key

Instead use one of the following:

Configure by the code API

7-pre NServiceBus
endpointConfiguration.SendFailedMessagesTo("error");

Read from an AppSettings and configure by the code API

7-pre NServiceBus
<configuration>
  <appSettings>
    <add key="ErrorQueue" value="error" />
  </appSettings>
</configuration>
7-pre NServiceBus
var appSettings = ConfigurationManager.AppSettings;
var errorQueue = appSettings.Get("errorQueue");
endpointConfiguration.SendFailedMessagesTo(errorQueue);

Endpoint Mappings

Configuring the error queue via the following APIs have been deprecated:

  • IProvideConfiguration<UnicastBusConfig>
  • UnicastBusConfig in an app.config configSections
  • Returning a UnicastBusConfig from a IConfigurationSource

It can be replaced with a combination of the following

Command routing

7-pre NServiceBus
var transportExtensions = endpointConfiguration.UseTransport<MyTransport>();

var routing = transportExtensions.Routing();
routing.RouteToEndpoint(
    assembly: typeof(AcceptOrder).Assembly,
    destination: "Sales");

routing.RouteToEndpoint(
    assembly: typeof(AcceptOrder).Assembly,
    @namespace: "PriorityMessages",
    destination: "Preferred");

routing.RouteToEndpoint(
    messageType: typeof(SendOrder),
    destination: "Sending");

Event routing

7-pre NServiceBus
var transportExtensions = endpointConfiguration.UseTransport<MyTransport>();

var routing = transportExtensions.Routing();
routing.RegisterPublisher(
    assembly: typeof(OrderAccepted).Assembly,
    publisherEndpoint: "Sales");

routing.RegisterPublisher(
    assembly: typeof(OrderAccepted).Assembly,
    @namespace: "PriorityMessages",
    publisherEndpoint: "Preferred");

routing.RegisterPublisher(
    eventType: typeof(OrderSent),
    publisherEndpoint: "Sending");

Renamed APIs

Access to settings

The GetSettings extension method has been moved from NServiceBus.Configuration.AdvanceExtensibility to the NServiceBus.Configuration.AdvancedExtensibility namespace. More details on advanced access to settings can be found here.

ContextBag extensions

The RemoveDeliveryConstaint extension method has been renamed to RemoveDeliveryConstraint.

IncomingMessage extensions

The GetMesssageIntent extension method has been renamed to GetMessageIntent.

Assembly scanning

64-bit assemblies are no longer silently excluded from scanning when running in a x86 process. Instead startup will fail with a System.BadImageFormatException. Use the exclude API to exclude the assembly and avoid the exception.

Legacy .Retries message receiver

The .Retries message receiver added to assist in migrating from Version 5 to Version 6 has been removed. The API to disable it has also been removed.

MSMQ

The MSMQ transport is no longer part of the NServiceBus NuGet package. It has been moved into a separate package, NServiceBus.Transport.Msmq.

Default transport

There is no longer a default transport, so an exception will be thrown if an endpoint is created or started without configuring a transport.

Message Property Encryption

The Message Property Encryption feature has been moved from the NServiceBus package. It is now available as a separate NuGet package, NServiceBus.Encryption.MessageProperty.

See the NServiceBus.Encryption.MessageProperty upgrade guide for more details.

Custom Correlation ID

Setting a custom correlation ID is considered dangerous. Therefore, the SendOptions.SetCorrelationId and SendOptions.GetCorrelationId APIs have been removed.


Last modified