The NServiceBus Host

If you've written the same config code too many times,
if you'd like to host your endpoints in a windows service,
NServiceBus.Host.exe can do that and run as a console too.

Enabling developers to change technologies without code,
administrator friendly for setting permissions and accounts,
the host streamlines service development and deployment.

See below the features the NServiceBus host gives you.

Overview

If you're implementing some back-end message processing, you don't have to write your own host process any more. Just reference NServiceBus.Host.exe from your message handler assembly and write a single class which inherits from IConfigureThisEndpoint, specifying whether you want server or client behavior (as described below) and you're done.

In order to F5 and debug through your endpoint, make sure you change the Debug settings of the Visual Studio project by right-clicking on it, selecting Properties, and then the Debug tab as shown here:

Make sure that Start Action has the 'Start external program' radio button set and choose the file 'NServiceBus.Host.exe' in the /bin/debug directory of your project.

Now we're ready to describe how it hooks into configuration.

Configuration

How does the host know which configuration file to use? Here's how:

NServiceBus.Host.exe scans the runtime directory loading all DLLs into memory. Then it searches the types defined in those assemblies for a class which implements the interface IConfigureThisEndpoint. Then, the name of the assembly holding that type is used to create assembly.dll.config and that is the file used for configuration.

You can shortcut the scanning process by telling the host which type to use by including a file called 'NServiceBus.Host.exe.config' in which you specify the type which implements IConfigureThisEndpoint like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="EndpointConfigurationType" value="YourNamespace.YourTypeName, YourAssembly"/>
  </appSettings>
</configuration>

Any issues encountered by the host at startup will be logged to 'hostlogfile'.

File Scanning

By default, NServiceBus scans files to find types implementing its interfaces so that it can configure them automatically. This is separate from the host's file scanning behavior and happens inside the call 'NServiceBus.Configure.With()'.

If you want to specify to NServiceBus which assemblies to use, you'll need to set the container as well. This is done by implementing IWantCustomInitialization as described in the Container section below. In that Init method you can make use of the appropriate method overload:

    Configure.With(string probeDirectory)
    Configure.With(params Assembly[] assemblies)
    Configure.With(IEnumerable<Type> typesToScan)

Logging

If you want to change the logging infrastructure that the host uses, implement the interface IWantCustomLogging and in the Init method, do your custom setup. In order to have NServiceBus use your logger, use the NServiceBus.SetLoggingLibrary.Log4Net API as described in the logging documentation and shown below:

class MyEndpointConfig : IConfigureThisEndpoint, IWantCustomLogging
{
    public void Init()
    {
        // setup your logging infrastructure then call
        NServiceBus.SetLoggingLibrary.Log4Net(null, yourLogger);
    }
}

It is likely that you'll want to specify different logging levels (DEBUG, WARN, etc) and possibly different targets (CONSOLE, FILE, etc) in various circumstances. The host provides a mechanism for changing these permutations without either code or config changes. This is done via profiles, described on this page.

Custom Initialization and Startup

On top of the standard NServiceBus initialization it is likely that you'll want to initialize your own components as well. NServiceBus enables you to do so at the same time as its own initialization so that no messages will be processed until all initialization is complete.

Out of the files scanned above, the host looks for classes which implement IWantCustomInitialization and calls their Init() method. The best practice is to have one initialization class per independent component to be initialized. You can have as many classes as you like, though you should avoid any assumption about the order of their invocation.

If you implement IWantCustomInitialization on the same class as the one which implements IConfigureThisEndpoint, that is the one that will be called first. This is useful if you want to configure your own container as described below.

Make sure not to perform any startup behaviors in the Init method.

All startup behaviors should be deferred until all initialization has been completed. At that point, NServiceBus will invoke classes that implement the interface IWantToRunAtStartup.

An example of behavior suitable to implement under IWantToRunAtStartup is the opening of the main form in a Windows Forms application. In back-end Windows Services, things like web crawling, data mining, and batch processes should be kicked off by classes implementing IWantToRunAtStartup.

Containers and Dependency Injection

By default, the host will make use of Spring as its container (dependency injection framework). If you wish to use a different container, you need to implement the interface IWantCustomInitialization on the class which implements IConfigureThisEndpoint and provide NServiceBus an adapter object to your container as described in this page. Here is an example of setting Castle Windsor as the container of choice:

class EndpointConfig : IConfigureThisEndpoint, AsA_Server, IWantCustomInitialization
{
    public void Init()
    {
        NServiceBus.Configure.With()
            .CastleWindsorBuilder()
            .XmlSerializer(); // or BinarySerializer()
    }
}

Notice that you have to specify the serialization here as well as the container. The rest of the code specifying transport, subscription storage, and other technologies isn't here. This is due to the AsA_Server built-in configuration described below.

Built-in Configurations

While NServiceBus allows you to extensibly pick and choose which technologies to use and how to configure each of them, the host has packaged up these choices into 3 built-in options:

AsA_Client, AsA_Server, and AsA_Publisher

All of these options make use of the XmlSerializer, the MsmqTransport, and the UnicastBus. The difference is in how each configures them.

AsA_Client sets MsmqTransport to be non-transactional, and it purges its queue of messages on startup. This means that it starts fresh everytime, not remembering anything before a crash. Also, it processes messages using its own permissions, not those of the message sender.

AsA_Server sets the MsmqTransport to be transactional and does not purge messages from its queue on startup. This makes it fault-tolerant. Also, it processes messages under the permissions of the message sender (called impersonation) which prevents elevation of privelege attacks.

AsA_Publisher extends AsA_Server and also indicates to the infrastructure that a storage for subscription requests is to be set up. This is done as described in the profiles page.

Installation

In order to install your process as a windows service, you need to pass /install on the command line to the host. By default, the name of the service will be derived from the name of the class which implements IConfigureThisEndpoint and the version number of its assembly.

For example: YourNamespace.YourClassName_v1.2.3.4

You can override this and specify additional details for installation as follows:

    NServiceBus.Host.exe [/install  [/serviceName]
                                    [/displayName]
                                    [/description]
                                    [/instance]
                                    [/startManually]
                                    [/username]
                                    [/password]]

Specifying /serviceName:YourServiceName will set the actual name of the windows services in the registry - this is different from what you see in the Windows Service Manager.

Specifying /displayName:YourService will set the name of the windows service as you see it in the Windows Service Manager. If you do not specify /displayName, but do specify /serviceName, the display name will not become what was passed in the /serviceName, but rather the default described above (YourNamespace.YourClassName_v1.2.3.4).

Specifying /description:DescriptionOfYourService will set the description shown in the Windows Service Manager.

The 'instance' flag allows you to install multiple instances of the same service by providing each a different instance name - for example: /instance:Instance5.

By default, windows services are started automatically when the operating system starts. If you don't want your service to do that, add /startManually to the /install command.

In order to specify under which account you want your service to run, pass in the username and password of that account.

To uninstall, call NServiceBus.Host.exe /uninstall. If you specified a service name or instance name when installing your service, you'll need to pass those in to the uninstall command as well:

    NServiceBus.Host.exe [/uninstall  [/serviceName]
                                      [/instance]]

For example: NServiceBus.Host.exe /uninstall /serviceName:YourServiceName /instance:YourInstanceName

Administrators can find this information by invoking 'NServiceBus.Host.exe /help'.

Next Steps

Learn about profiles