NServiceBus Azure Host Upgrade Version 7 to 8

The NServiceBus Azure Host will be deprecated as of Version 9 and users are recommended to switch to self hosting for new endpoints. Upgrading existing endpoints is still supported for Version 8.

The following are the main reasons why the NServiceBus hosts are being deprecated:

  • Ease of configuration: Endpoint configuration and related APIs have been significantly improved over the last few years. Therefore self-hosting is much simpler to set up than it used to be when hosts were first introduced.

  • NuGet functionality changes: Related to the ease of configuration, NuGet no longer allows packages to add add source files and modify project files in new projects using the SDK style .csproj project definitions. This means that installing the host won't result in a runnable endpoint out of the box, which limits usefulness of supporting that feature by NServiceBus. Existing endpoints using the host can be upgraded without issues.

  • Ease and transparency of deployment: The hosts provide abstractions for service installations that configure most of the relevant settings, but still require performing additional manual steps to ensure reliability. The additional steps were sometimes accidentally skipped, causing issues after deployment. Now the installation process is more explicit and guides through service configuration in a more transparent manner.

  • Configuration transparency: The hosts used to have various profiles and roles which automatically set certain options like disabling transactions. The effect was not obvious without reading the documentation, which could result in misunderstandings and undesired, surprising effects in the system at runtime. Self-hosting comes with full, explicit, fine-grained control over all aspects of the endpoint configuration and runtime behavior.

  • Easier troubleshooting: The hosts introduce another layer of abstraction which can make troubleshooting more difficult. Some problems require deep dive into internal implementation and tend to be hard to resolve without support.

  • Better performance: Using the hosts with default, generic settings introduces certain overhead. Self-hosting typically leads to shorter startup times and less memory consumption. With self-hosting, more control over the configuration is enabled.

Migrating procedure

See the self hosting sample for details. For multi-hosting it is recommended to apply self-hosting with multiple endpoints similar to the multi hosting sample.

If process isolation is required between the endpoints it is advised to stay with the latest version of the cloud host. Process isolation will be addressed in the upgrade guides when the host is fully deprecated.


Self hosting gives access to the same configuration options. See below for migration of host specific configuration APIs.

Custom endpoint configuration

Configuration code in IConfigureThisEndpoint.Customize can be transferred as-is to the configuration of the self-hosted endpoint.


The AsA_Worker role didn't change any configuration and can safely be ignored.

Endpoint name

The host defaults the endpoint name to the namespace of the type implementing IConfigureThisEndpoint. Pass that value to the name to the constructor of EndpointConfiguration.

Overriding endpoint name

Overriding endpoint name using the EndpointName attribute or DefineEndpointName method is no longer needed. Pass the relevant name to the constructor of EndpointConfiguration.

Executing custom code on start and stop

The host allowed custom code to run at start and stop by implementing IWantToRunWhenEndpointStartsAndStops. Since self-hosted endpoints are in full control over start and stop operations this code can be executed explicitly when starting/stopping.


Related Articles

Last modified