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. This settings are stored per user but if you want to set this up for all you developers please follow the instructions in this video.

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>

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)
    

Note that the NServiceBus assemblies are always included in scanning since they are needed for NServiceBus to function properly.

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 INeedInitialization 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.

To change core settings like assembly scanning, container, serialization format etc you need to implement IWantCustomInitialization on the endpoint configuration class (the same class which implements IConfigureThisEndpoint). Doing this requires you to start the configuration expression with Configure.With()...

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 IWantToRunWhenTheBusStarts.

An example of behavior suitable to implement under IWantToRunWhenTheBusStarts 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 IWantToRunWhenTheBusStarts.

Containers and Dependency Injection

By default, the host will make use of Autofac internally 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()
    }
}

If you omit the serialization configuration XML will be used by default. 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 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.

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 name of your endpoint. By default the endpoint name is the namespace of your endpoint config class. To enable side by side operations use the /sideBySide switch. This will add the semver version to the service name. Passing /install will also cause the host to invoke the installers.

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

USAGE:
NServiceBus.Host.exe [/install [/serviceName]
                           [/displayName]
                           [/description]
                           [/endpointConfigurationType]
                           [/endpointName]
                           [/installInfrastructure]
                           [/scannedAssemblies]
                           [/dependsOn]
                           [/sideBySide]
                           [/startManually]
                           [/username]
                           [/password]]
                           [/uninstall [/serviceName]
                           [/sidebyside]
                           [/instance:Instance Name ]
    

You can get to this list by running at the command line the following:
    > NServiceBus.Host.exe /?

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.

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.

The following is an example of using the /install command line:

NServiceBus.Host.exe /install /serviceName:"MyPublisher" 
        /displayName:"My Publisher Service"
        /description:"Service for publishing event messages"
        /endpointConfigurationType:"YourEndpointConfigType.YourNameSpace, YourAssembly"
        /username:"corp\serviceuser"
        /password:"p@ssw0rd!" NServiceBus.Production

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

To invoke the infrastructure installers you need to run the host with the /installInfrastructure switch. Learn about installers