Hosting

Component: NServiceBus
NuGet Package NServiceBus (4.x)
Standard support for version 4.x of NServiceBus has expired. For more information see our Support Policy.

At its core NServiceBus is a library; as such it can be hosted in any .NET process.

There are several approaches to hosting.

Self-hosting

"Self-hosting" is a general term used when the application code takes full control over all facets of hosting NServiceBus. This includes the following actions:

Override the default critical error callback when self-hosting NServiceBus. By default NServiceBus will stop the endpoint instance without exiting the process. Refer to the Critical Errors article for more information.

Related:

When self-hosting, the user is responsible for creating and starting the endpoint instance:

var configure = Configure.With();
// Apply configuration
var configUnicastBus = configure.UnicastBus();
var startableBus = configUnicastBus.CreateBus();
var bus = startableBus.Start();

The user is also responsible for properly shutting down the endpoint when it is no longer needed (usually when the application terminates).

var busImpl = (UnicastBus)bus;
busImpl.Dispose();

Windows Service hosting

A Windows Service is the most common way to host NServiceBus in Windows.

Related:

Send-only hosting

A "Send-only endpoint" is used when the only purpose of the endpoint is to send messages and no message processing is required in that endpoint. Common use cases include websites, console applications, and windows applications. This is the code for starting an endpoint in send-only mode.

var configure = Configure.With();
var configUnicastBus = configure.UnicastBus();
var bus = configUnicastBus.SendOnly();

The only configuration required when running in this mode is the destination when sending a message.

Web hosting

NServiceBus can be hosted in any web technology that supports .NET. See Web Application Hosting.

Service Fabric hosting

Service Fabric can be used to host NServiceBus endpoints in several ways. See Service Fabric Hosting.

Multi-hosting

"Multi-hosting" refers to hosting multiple NServiceBus endpoints in a single .NET process.

This can be achieved through multiple AppDomains.

Related:

Accessing the bus

Most usages of the bus will occur where the NServiceBus APIs are used, for example handlers and sagas. However, there are other scenarios that may require an alternate approach where the user needs to directly access the bus from outside of the framework.

Using dependency injection

NServiceBus supports dependency injection. At startup, the instance of a bus session will be injected into the configured dependency injection and can be access via that instance.

Related:

Static variable

For many scenarios, dependency injection is not required. In these cases, a simple public static variable on the startup class will suffice. This variable can then be access globally in the application. For example:

  • In a Windows service or console the variable could be placed in Program.cs
  • In a website the variable could be placed in Global.asax.cs.

The static variable could also be placed in a helper class.

public static class EndpointInstance
{
    public static IBus Endpoint { get; private set; }
    public static void SetInstance(IBus endpoint)
    {
        if (Endpoint != null)
        {
            throw new Exception("Endpoint already set.");
        }
        Endpoint = endpoint;
    }
}

Custom hosting

A "Custom host" is a process or library that wraps the NServiceBus library to take partial control of configuration, startup and shutdown. This host exposes extension points for common activities and uses conventions and/or sensible defaults for many other configuration options.

NServiceBus host

The NServiceBus host takes a more opinionated approach to hosting. It allows the execution as both a Windows service and a console application (for development). It also adds the concepts of profiles and custom installation.

Related:

Hosting in Azure

There are multiple ways to host in Azure. Depending on the requirements, self-hosting may be an option or a custom Azure host may be required. See Hosting in Azure Cloud Services for more information.

Related:

ILMerging NServiceBus assemblies

Since NServiceBus makes assumptions on aspects like assembly names, ILMerging any of the NServiceBus* assemblies is not supported.

Related Articles


Last modified