Hosting

NServiceBus is a library at its core so that it can be hosted in any .NET process.

There are several approaches to hosting.

Microsoft Generic Host

The Microsoft Generic Host is the most common way to host NServiceBus on .NET Core. NServiceBus can be integrated with the generic host using the NServiceBus.Extensions.Hosting package.

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:

• Configuration
• Logging
• Dependency injection
• Startup and Shutdown
• Endpoint Lifecycle
• Critical Error handling

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

var endpointConfiguration = new EndpointConfiguration("EndpointName");
// Apply other necessary endpoint configuration, e.g. transport
var startableEndpoint = await Endpoint.Create(endpointConfiguration);
var endpointInstance = await startableEndpoint.Start();

// Shortcut
var endpointInstance2 = await Endpoint.Start(endpointConfiguration);

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

await endpointInstance.Stop();

Windows Service hosting

A Windows Service is a common way to host NServiceBus in Windows.

Related:

• Generic host as Windows Service
• Generate a Windows Service project using dotnet new
• Windows Service installation

Docker container hosting

An endpoint can be hosted inside a Docker container.

Related:

• Docker container host
• Generate a Docker-hosted endpoint project with dotnet new
• Hosting endpoints in Docker Linux containers
• Generic host

Send-only hosting

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

var endpointConfiguration = new EndpointConfiguration("EndpointName");
endpointConfiguration.SendOnly();
// Apply other necessary endpoint configuration, e.g. transport
var endpointInstance = await Endpoint.Start(endpointConfiguration);

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

Web hosting

NServiceBus can be hosted using any web technology that supports .NET. See Web Application Hosting for more information.

WebJob hosting

NServiceBus can be hosted in a WebJob. See Self-Hosting in Azure WebJobs

Service Fabric hosting

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

Serverless hosting

NServiceBus can be hosted in several serverless environments such as Azure Functions and AWS Lambda.

Accessing the bus

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

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 accessed globally within 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 IEndpointInstance Endpoint { get; private set; }
    public static void SetInstance(IEndpointInstance 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 control configuration, startup, and shutdown partially. This host exposes extension points for common activities and uses conventions and/or sensible defaults for many other configuration options.

ILMerging NServiceBus assemblies

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

Hosting environment requirements

NServiceBus endpoints have certain requirements for the hosting environment:

• The endpoint process needs write access to write log files. See the logging documentation for more details about the default log file location and how to configure logging.
• The endpoint process needs write access to write the startup diagnostics file. See the startup diagnostics documentation for more details about the diagnostic file.