NServiceBus Host Upgrade Version 7 to 8

The NServiceBus Host will be deprecated as of version 9; it is recommended to switch to self-hosting or the generic host 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: NuGet no longer allows packages to 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. With self-hosting, the installation process is more explicit and guides the user 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 undesired and unexpected 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 a deep dive into internal implementations 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

Switching to self-hosting can be done by using the generic host, Create a project that supports Windows Service hosting or Docker container hosting with dotnet new using the ParticularTemplates package, then move the relevant code and configuration to the new project.

Configuration

Self-hosting provides access to the same configuration options as provided by the Host. See below for the migration of host-specific configuration APIs.

Custom endpoint configuration

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

Roles

The AsA_Client role can be replaced with the following configuration:

endpointConfiguration.PurgeOnStartup(true);
endpointConfiguration.DisableFeature<TimeoutManager>();
var transport = endpointConfiguration.UseTransport<MyTransport>();
transport.Transactions(TransportTransactionMode.None);

var recoverability = endpointConfiguration.Recoverability();
recoverability.Delayed(
    customizations: delayed =>
    {
        delayed.NumberOfRetries(0);
    });

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

The UsingTransport<MyTransport> role can be replaced with the equivalent EndpointConfiguration.UseTransport<MyTransport>() call.

Endpoint name

The Host defaulted the endpoint name to the namespace of the type implementing IConfigureThisEndpoint. When self-hosting, that name should be passed to the constructor of an EndpointConfiguration.

Overriding the endpoint name

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

Defining an SLA for the endpoint

Defining an endpoint's SLA via the EndpointSLA attribute is no longer supported.

Install the NServiceBus.WindowsPerformanceCounters package and follow the configuration instructions.

Executing custom code when the endpoint starts and stops

The Host allowed custom code to run when an endpoint started and stopped by implementing IWantToRunWhenEndpointStartsAndStops. Since self-hosted endpoints are in full control over what happens in their start and stop phases, this code can be executed explicitly when starting or stopping the endpoint.

Profiles

Profiles allowed endpoint configuration to be customized for different runtime environments like dev, test, and prod. Self-hosted endpoints can instead explicitly change configuration based on environment variables, command-line arguments, machine names, etc.

Installation

See the instructions on how to use SC.exe to install self-hosted windows services.

Details on how to run custom installers can be found in the installation documentation.