Hosting

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 to refer to when the application code takes full control over all facets of hosting NServiceBus. This includes the following actions:

Related:

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

6-pre NServiceBus
EndpointConfiguration endpointConfiguration = new EndpointConfiguration("EndpointName");
//Apply configuration
IStartableEndpoint startableEndpoint = await Endpoint.Create(endpointConfiguration);
IEndpointInstance endpointInstance = await startableEndpoint.Start();

//Shortcut
IEndpointInstance endpointInstance2 = await Endpoint.Start(endpointConfiguration);
5.x NServiceBus
BusConfiguration busConfiguration = new BusConfiguration();
//Apply configuration
IStartableBus startableBus = Bus.Create(busConfiguration);
IBus bus = startableBus.Start();
4.x NServiceBus
Configure configure = Configure.With();
//Apply configuration
ConfigUnicastBus configUnicastBus = configure.UnicastBus();
IStartableBus startableBus = configUnicastBus.CreateBus();
IBus bus = startableBus.Start();
3.x NServiceBus
Configure configure = Configure.With();
ConfigUnicastBus configUnicastBus = configure.UnicastBus();
IStartableBus startableBus = configUnicastBus.CreateBus();
IBus 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).

6-pre NServiceBus
await endpointInstance.Stop();
5.x NServiceBus
bus.Dispose();
3.x - 4.x NServiceBus
UnicastBus busImpl = (UnicastBus)bus;
busImpl.Dispose();
In Version 6, the endpoint instance is not disposable due to the asynchronous nature of the pipeline. Call Stop in an async manner (see example above).

Windows Service Hosting

A Windows Service is the most common way NServiceBus is hosted.

Related:

Send-only hosting

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

6-pre NServiceBus
EndpointConfiguration endpointConfiguration = new EndpointConfiguration("EndpointName");
endpointConfiguration.SendOnly();
IEndpointInstance endpointInstance = await Endpoint.Start(endpointConfiguration);
5.x NServiceBus
BusConfiguration busConfiguration = new BusConfiguration();
ISendOnlyBus bus = Bus.CreateSendOnly(busConfiguration);
3.x - 4.x NServiceBus
Configure configure = Configure.With();
ConfigUnicastBus configUnicastBus = configure.UnicastBus();
IBus bus = configUnicastBus.SendOnly();

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

Web Hosting

NServiceBus can be hosted in any web technology that support .NET. This includes

  • ASP.net
  • ASP.MVC
  • WCF
  • Web API
  • NancyFX

And many others.

As most web technologies operate in a scale out manner NServiceBus is usually hosted in a "Send-only" manner. In this mode they act as a "forwarder" of messages rather than the "processor". So the handling code (MVC controller, NancyFX module etc) of a given web request simply leverages the Bus send APIs and no processing is done in the web process. The actually message handling is done in a Windows Service Endpoint.

In a web hosted scenario a IIS Recycle is considered a shutdown and restart of the bus.

Related:

Multi-Hosting

"Multi-hosting" refers to hosing multiple NServiceBus endpoints in a single .NET process. In Version 4 and earlier this could be achieved through multiple AppDomains. In Version 5 and above multiple endpoints can share the same AppDomain or use the multiple AppDomains approach.

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 alternative approach where the user needs to directly access the bus from outside of the framework.

Using a Container

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

Related:

In Versions 6 and above, IEndpointInstance/IMessageSession (the equivalent of IBus in earlier versions) is no longer automatically injected into the container. In order to send messages explicitly create a bus context. Here's a sample code showing how to automate this task using the Autofac container
6-pre NServiceBus
ContainerBuilder containerBuilder = new ContainerBuilder();

EndpointConfiguration endpointConfiguration = new EndpointConfiguration("EndpointName");
IEndpointInstance endpointInstance = await Endpoint.Start(endpointConfiguration);
containerBuilder.Register(_ => endpointInstance).InstancePerDependency();

Static variable

For many scenarios a container 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 windows service or console the variable would be placed on the Program.cs
  • In a Website the variable would be placed on the Global.cs.

Alternatively the static variable could be placed on a (more appropriately named) helper class.

6-pre NServiceBus
public static class EndpointInstance
{
    public static IEndpointInstance Endpoint { get; private set; }
    public static void SetInstance(IEndpointInstance endpoint)
    {
        if (Endpoint != null)
        {
            throw new Exception("Endpoint already set.");
        }
        Endpoint = endpoint;
    }
}
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 Host" Solutions

A "Custom Host" refers to a process or library that wraps the NServiceBus library to take partial control of configuration, startup and shutdown. This Host then 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 a variety of ways to host in Azure. Depending on the requirements Self Hosting may be an option or, alternatively, a custom Azure host may be required. See Hosting in Azure Cloud Services and Hosting in Azure for more information.

Related:

Samples

Related Articles

Hosting in Azure Cloud Services

Using Azure Cloud Services to host NServiceBus.

NServiceBus Host

Avoid writing repeat configuration code, host the endpoints in a Windows Service, and change technologies without code.


Last modified 2016-04-19 08:45:39Z