Hosting NServiceBus In Your Own Process

Lighter-weight than BizTalk & more powerful than WCF,
NServiceBus comes with its own host process and also
allows you to host it in your own process.

Requiring as little as 3 assemblies to be referenced
the fluent configuration API will have you up and running
with transactional one-way messaging in a snap.

Assembly references

The 3 assemblies you need to reference in order to host NServiceBus in your own process are shown to the left. Log4Net is the industry-standard logging library used by NServiceBus. NServiceBus.dll contains the main interfaces developers should be programming against, and NServiceBus.Core.dll contains all the runtime elements needed for execution.

The AsyncPages sample demonstrates this configuration.

NServiceBus Initialization

In the Application_Start method of your Global.asax file in a web application, or in the Main method of your Program file for console or Windows Forms applications, include the following initialization code:

NServiceBus.Configure.With()
    .DefaultBuilder()
    .Log4Net()
    .XmlSerializer()
    .MsmqTransport()
    .UnicastBus()
    .CreateBus()
    .Start();

This is the minimum initialization code that is required by NServiceBus.

Most of the methods you see here are extension methods on the NServiceBus.Configure class provided by the specific components that are packaged in the NServiceBus.Core assembly. This makes it possible for you to similarly configure your own components in the same style by writing your own extension methods.

Log4Net() tells NServiceBus what to log with - more information here.
DefaultBuilder() tells NServiceBus to use the default(Autofac) dependency injection framework. Other dependency injection frameworks are available as well - more information here.
XmlSerializer() tells NServiceBus to serialize messages as XML. There is also the option of specifying BinarySerializer() which will do binary serialization of messages.
MsmqTransport() tells NServiceBus to use MSMQ as its transactional messaging transport. NServiceBus also supports Azure queues(see sample here) and FTP(see sample here) as transport mechanisms.
UnicastBus() tells NServiceBus to use unicast messaging. Currently the only option available out of the box. LoadMessageHandlers() readies the bus for invoking message handlers when a message arrives.
CreateBus() takes all the previous options and wires up a bus object for you to use. You can store the reference returned from this call to use to send messages.
Start() tells the bus object created by CreateBus() to start the threads it uses for listening and processing messages.

In addition to the above initialization code, NServiceBus requires certain configuration data to be available. By default, it retrieves this information from the application config file, though this can be changed by using the CustomConfigurationSource() method.

Configuration

When using the initialization code above, you will need to provide configuration for the MsmqTransport and processing of faults - specifically the number of threads it runs, and where it sends messages that couldn't be processed.

You'll need to include these configuration sections:

<section name="MsmqTransportConfig" 
         type="NServiceBus.Config.MsmqTransportConfig, NServiceBus.Core"/>
<section name="MessageForwardingInCaseOfFaultConfig" 
         type="NServiceBus.Config.MessageForwardingInCaseOfFaultConfig, NServiceBus.Core" />

And specify the configuration data as follows:

<MsmqTransportConfig 
    NumberOfWorkerThreads="1" 
    MaxRetries="5"  />
<MessageForwardingInCaseOfFaultConfig ErrorQueue="error"/>

In the case where an exception was thrown during the processing of a message, NServiceBus automatically retries the message (as it could be that if failed due to something transient like a database deadlock). MaxRetries specifies the maximum number of times this will be done before the message is moved to the ErrorQueue.

Routing Configuration

While you can tell NServiceBus to which address to send a message using the API: Bus.Send(toDestination, message); NServiceBus enables you to keep your code decoupled from where endpoints are deployed on the network through the use of routing configuration.

In order to make use of it, include this configuration section:

<section name="UnicastBusConfig" type="NServiceBus.Config.UnicastBusConfig, NServiceBus.Core"/>

And then specify the configuration data like this:

<UnicastBusConfig>
<MessageEndpointMappings>
    <add Messages="MessageDLL" Endpoint="DestinationQueue@TargetMachine"/>
</MessageEndpointMappings>
</UnicastBusConfig>

This tells NServiceBus that all messages in the MessageDLL assembly should be routed to the queue called DestinationQueue on the machine TargetMachine. This allows you to send messages from that assembly like this: Bus.Send(messageFromMessageDLL);