NServiceBus Host

Project Hosting
NuGet NServiceBus.Host (5.x)
Target NServiceBus Version: 5.x

The NServiceBus Host takes an opinionated approach to hosting. Endpoints using NServiceBus Host can run as windows services or console application (e.g. during development).

To use the host, create a new C# class library and reference the NServiceBus.Host NuGet package. The package will automatically create a sample endpoint configuration and will set the NServiceBus.Host.exe as the endpoint's startup project.

Application Domains

The NServiceBus.Host.exe creates a separate service Application Domain to run NServiceBus and the user code. The new domain is assigned a configuration file named after the dll that contains the class implementing IConfigureThisEndpoint. All the configuration should be done in that file (as opposed to NServiceBus.Host.exe.config). In most cases that means just adding the app.config file to the project and letting MSBuild take care of renaming it while moving to the bin directory.

When the endpoint configuration is not specified explicitly, the host scans all the assemblies to find it and it does so in the context of the host application domain, not the new service domain. Because of that, when redirecting assembly versions, the assemblyBinding element needs to be present in both NServiceBus.Host.exe.config and app.config.

Endpoint configuration

Assembly scanning

By default, the assembly scanning process of the NServiceBus Host is the same as for a regular endpoint. At startup the host scans the runtime directory to find assemblies that contain configuration for the given endpoint, i.e. classes implementing the IConfigureThisEndpoint interface.

The scanning process can be avoided if the class containing endpoint's configuration is explicitly specified:

    <add key="EndpointConfigurationType"
         value="YourNamespace.YourTypeName, YourAssembly"/>

Alternatively, it's possible to control which assemblies should be scanned. That can be done in code by implementing IConfigureThisEndpoint interface:

public class EndpointConfig :
    public void Customize(BusConfiguration busConfiguration)
        // use 'busConfiguration' object to configure scanning

or during installation by passing values to /scannedAssemblies: parameters.


For Versions 5 and above, customize the endpoint behavior using the IConfigureThisEndpoint.Customize method on the endpoint configuration class. Call the appropriate methods on the parameter passed to the method.

class CustomizingHost :
    public void Customize(BusConfiguration busConfiguration)
        // To customize, use the configuration parameter.

Endpoint Name

Via namespace convention

When using NServiceBus.Host, the namespace of the class implementing IConfigureThisEndpoint will be used as the endpoint name as the default convention. In the following example the endpoint name when running NServiceBus.Host.exe becomes MyServer. This is the recommended way to name a endpoint. Also this emphasizes convention over configuration approach.

namespace MyServer
    using NServiceBus;

    public class EndpointConfigByNamespace :
        // ... custom config

Via EndpointName attribute

Set the endpoint name using the [EndpointName] attribute on the endpoint configuration.

This will only work when using NServiceBus host.
public class EndpointConfigWithAttribute :
    // ... the config

Default Critical error action

The default Critical Error Action for the Host is:

if (Environment.UserInteractive)
    // so that user can see on their screen the problem

var fatalMessage = $"NServiceBus critical error:\n{errorMessage}\nShutting down.";
Environment.FailFast(fatalMessage, exception);

The default callback should be overriden, if some custom code should be executed before exiting the process, such as persisting some in-memory data, flushing the loggers, etc. Refer to the Critical Errors article for more information.

Roles - Built-in configurations

In Versions 5 and above roles are obsoleted and should not be used. The functionality of AsA_Server, and AsA_Publisher has been made defaults in the core and can be safely removed. If the AsA_Client functionality is still required add the following configuration.

var busConfiguration = new BusConfiguration();

var transactions = busConfiguration.Transactions();

Performance Counters

SLA violation countdown

In the NServiceBus Host the SLA violation countdown counter is enabled by default. But the value can be configured either by the above API or using a EndpointSLAAttribute on the instance of IConfigureThisEndpoint.

public class EndpointConfig :

When Endpoint Instance Starts and Stops

Classes that plug into the startup/shutdown sequence are invoked just after the endpoint instance has been started and just before it is stopped. This approach may be used for any tasks that need to execute with the same life-cycle as the endpoint instance.

public class Bootstrapper :

    public void Start()
        // Do startup actions here.

    public void Stop()
        // Do cleanup actions here.


Related Articles

Last modified