Upgrade Version 7 to 8

Component: NServiceBus
This page targets a pre-release version and is subject to change prior to the final release.
This is a working document; there is currently no timeline for the release of NServiceBus version 8.0.

Dependency injection

Support for external dependency injection containers is no longer provided by NServiceBus adapters for each container library. Instead, NServiceBus version 8 directly provides the ability to use any container that conforms to the Microsoft.Extensions.DependencyInjection.Abstractions container abstraction. Visit the dedicated dependency injection changes section of the upgrade guide for further information.

Support for external logging providers

Support for external logging providers is no longer provided by NServiceBus adapters for each logging framework. Instead, the NServiceBus.Extensions.Logging package provides the ability to use any logging provider that conforms to the Microsoft.Extensions.Logging abstraction.

The following provider packages will no longer be provided:

New gateway persistence API

The NServiceBus gateway has been moved to a separate NServiceBus.Gateway package and all gateway public APIs in NServiceBus are obsolete and will produce the following warning:

Gateway persistence has been moved to the NServiceBus.Gateway dedicated package. Will be treated as an error from version 8.0.0. Will be removed in version 9.0.0.

How to upgrade

Error notification events

In NServiceBus version 7.2, error notification events for MessageSentToErrorQueue, MessageHasFailedAnImmediateRetryAttempt, and MessageHasBeenSentToDelayedRetries using .NET events were deprecated in favor of Task-based callbacks. In NServiceBus version 8 and above, the event-based notifications will throw an error.

Error notifications can be set with the Task-based callbacks through the recoverability settings:

var recoverability = endpointConfiguration.Recoverability();

recoverability.Immediate(settings => settings.OnMessageBeingRetried(retry =>
    log.Info($"Message {retry.MessageId} will be retried immediately.");
    return Task.CompletedTask;

recoverability.Delayed(settings => settings.OnMessageBeingRetried(retry =>
    log.Info($@"Message {retry.MessageId} will be retried after a delay.");
    return Task.CompletedTask;

recoverability.Failed(settings => settings.OnMessageSentToErrorQueue(failed =>
    log.Fatal($@"Message {failed.MessageId} will be sent to the error queue.");
    return Task.CompletedTask;

Disabling subscriptions

In previous versions, users sometimes disabled the MessageDrivenSubscriptions feature to remove the need for a subscription storage on endpoints that do not publish events, which could cause other unintended consequences.

While NServiceBus still supports message-driven subscriptions for transports that do not have native publish/subscribe capabilities, the MessageDrivenSubscriptions feature itself has been deprecated.

To disable publishing on an endpoint, the declarative API should be used instead:

var transportConfiguration = endpointConfiguration.UseTransport<TransportDefinition>();

Connection strings

Configuring a transport's connection using .ConnectionStringName(name), which was removed for .NET Core in NServiceBus version 7, has been removed all platforms in NServiceBus version 8. To continue to retrieve the connection string by the named value in the configuration, first retrieve the connection string and then pass it to the .ConnectionString(value) configuration.

A connection string named NServiceBus/Transport will also no longer be detected automatically on any platform. The connection string value must be configured explicitly using .ConnectionString(value).

Change to license file locations

NServiceBus version 8 will no longer attempt to load the license file from the appSettings section of an app.config or web.config file, in order to create better alignment between .NET Framework 4.x and .NET Core.

In NServiceBus version 7 and below, the license path could be loaded from the NServiceBus/LicensePath app setting, or the license text itself could be loaded from the NServiceBus/License app setting.

Starting in NServiceBus version 8, one of the other methods of providing a license must be used.

Support for message forwarding

NServiceBus no longer natively supports forwarding a copy of every message processed by an endpoint. Instead, create a custom behavior to forward a copy of every procesed message as described in this sample.

NServiceBus Host

The NServiceBus.Host package is deprecated. See the NServiceBus Host upgrade guide for details and alternatives.

NServiceBus Azure Host

The NServiceBus.Hosting.Azure and NServiceBus.Hosting.Azure.HostProcess are deprecated.See the NServiceBus Azure Host upgrade guide for details and alternatives.

DateTimeOffset instead of DateTime

Usage of DateTime can result in numerous issues caused by disalignment in timezone offsets. These can then result in all types of time calculation errors. Although a DateTime.Kind property exists, it is often ignored during DateTime math and it is up to the user to ensure values are aligned in their offset. The DateTimeOffset type fixes this. It does not contain any timezone information, only an offset, which is sufficient to get all the math right.

> These uses for DateTimeOffset values are much more common than those for DateTime values. As a result, DateTimeOffset should be considered the default date and time type for application development."

In Version 8 all API's have been migrated from DateTime to DateTimeOffset.

NServiceBus Scheduler

In Version 8 the scheduler API has been deprecated in favor of options like sagas and production-grade schedulers like Hangfire, Quarts, FluentScheduler etc.

The recommendation is to create a .NET Timer with the same interval as the scheduled task and use IMessageSession.SendLocal that sends a message to process. Using message processing has the benefit of using Recoverability and uses a Transactional context. If these benefits are unwanted then do not send a message at all and directly invoke logic from the timer.

The Version 7 behavior is to not retry the task on failures, so make sure to wrap the business logic in a try catch statement to get the same behavior in Version 8.

See the scheduling with .NET Timers sample for more details.

Meaningful exceptions when stopped

NServiceBus is now throwing an InvalidOperationException when invoking message opererations on IMessageSession when the endpoint instance is stopping or stopped to indicate that the instance can no longer be used.

Non-durable messaging

Support for non-durable messaging has been moved to the transports that can support it which at this time is RabbitMQ. If using any other transport use of [Express] or message conventions to request non-durable deliver can safely be removed.

RabbitMQ user should use the new options.UseNonPersistentDeliveryMode() API provided by NServiceBus.RabbitMQ Version 7

Related Articles

Last modified