NServiceBus Host

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

To use the host, create a new C# class library and reference the NServiceBus.Host NuGet package.

Host Versions

Versions of the host prior to 5.0 were aligned with NServiceBus core. Since version 6 of NServiceBus.Host the releases are maintained and released independently and the version numbers don't match between NServiceBus.Host and NServiceBus core. This table shows the NServiceBus.Host versions and the corresponding version of NServiceBus core.

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 rename it while moving to the bin directory.

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 the endpoint's configuration is explicitly specified:

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

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

public class EndpointConfig :
    IConfigureThisEndpoint
{
    public void Customize(EndpointConfiguration endpointConfiguration)
    {
        // use 'endpointConfiguration' object to configure scanning
    }
}

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

Initialization

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 :
    IConfigureThisEndpoint
{
    public void Customize(EndpointConfiguration endpointConfiguration)
    {
        // To customize, use the configuration parameter.
        endpointConfiguration.UsePersistence<InMemoryPersistence>();
    }
}

The following snippet shows a sample configuration that can be used as a starting point.

using NServiceBus;

public class EndpointConfig : IConfigureThisEndpoint
{
    public void Customize(EndpointConfiguration endpointConfiguration)
    {
        //TODO: NServiceBus provides multiple durable storage options, including SQL Server, RavenDB, and Azure Table Persistence.
        // Refer to the documentation for more details on specific options.
        endpointConfiguration.UsePersistence<LearningPersistence>();
        // NServiceBus will move messages that fail repeatedly to a separate "error" queue. It is recommended
        // to start with a shared error queue for all endpoints for easy integration with ServiceControl.
        endpointConfiguration.SendFailedMessagesTo("error");
        // NServiceBus will store a copy of each successfully process message in a separate "audit" queue. It is recommended
        // to start with a shared audit queue for all endpoints for easy integration with ServiceControl.
        endpointConfiguration.AuditProcessedMessagesTo("audit");
    }
}

Set the host as a startup project

Either setup the start project to NServiceBus.Host.exe (available in the output directory of the build) or create a launchSettings.json with the following content

{
  "profiles": {
    "Host_8": {
      "commandName": "Executable",
      "executablePath": ".\\NServiceBus.Host.exe"
    }
  }
}

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 an endpoint. Also, this emphasizes convention over configuration approach.

namespace MyServer
{
    using NServiceBus;

#pragma warning disable 618
    public class EndpointConfigByNamespace :
        IConfigureThisEndpoint
    {
        // ... custom config

Defined in code

Set the endpoint name using the DefineEndpointName(name) extension method on the endpoint configuration.

public void Customize(EndpointConfiguration endpointConfiguration)
{
    endpointConfiguration.DefineEndpointName("CustomEndpointName");
}

Via EndpointName attribute

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

[EndpointName("MyEndpointName")]
public class EndpointConfigWithAttribute :
    IConfigureThisEndpoint
{
    // ... custom 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
    Thread.Sleep(10000);
}

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

The default callback should be overridden, 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 endpointConfiguration = new EndpointConfiguration("MyEndpointName");
endpointConfiguration.PurgeOnStartup(true);

var transport = endpointConfiguration.UseTransport<MsmqTransport>();
transport.Transactions(TransportTransactionMode.None);

var recoverability = endpointConfiguration.Recoverability();
recoverability.Delayed(
    customizations: settings =>
    {
        settings.NumberOfRetries(0);
    });
endpointConfiguration.DisableFeature<TimeoutManager>();

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 be executed with the same lifecycle as the endpoint instance.

public class Bootstrapper :
    IWantToRunWhenEndpointStartsAndStops
{
    public Task Start(IMessageSession session)
    {
        // Do startup actions here.
        // Either mark Start method as async or do the following
        return Task.CompletedTask;
    }

    public Task Stop(IMessageSession session)
    {
        // Do cleanup actions here.
        // Either mark Stop method as async or do the following
        return Task.CompletedTask;
    }
}

Support for TLS 1.2 and higher

The NServiceBus.Host is compiled against .NET Framework 4.5.2. The Transport Layer Security (TLS) best practices from Microsoft state that an application should not hardcode the TLS version but let the operating system choose a sensible default. Unfortunately being compiled against .NET 4.5.2 means TLS 1.1 and not TLS 1.2 or 1.3 will be used. To enable TLS 1.2 or higher compatibility on the Host add the following runtime configuration to the NServiceBus.Host.exe.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <AppContextSwitchOverrides value="Switch.System.Net.DontEnableSystemDefaultTlsVersions=false"/>
  </runtime>
</configuration>