NServiceBus for dummies who want to be smarties 3… third post on how to do some more stuff with NServiceBus.

But where do the messages go?

Well, where did you tell the framework to send them?

The answer to this question is deferred until the last meaningful moment, i.e. the moment when the generic host starts up and reads its app.config.

How do I receive messages?

The answer is simple: use the MsmqTransportConfig section to tell NServiceBus where this service can be reached. If the specified queue does not exist, it will be created. E.g. like so:

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

How do I send messages?

This question is a bit harder to answer. First, it can be specified in the UnicastBusConfig/MessageEndpointMappings element, for each message type, or for an entire assembly at a time. E.g. like so:

  <UnicastBusConfig>
    <MessageEndpointMappings>
      <add Messages="Messages" Endpoint="someService" />
      <add Messages="MessagesRootNamespace.SomeSpecificMessage, Messages" Endpoint="anotherService" />
    </MessageEndpointMappings>
  </UnicastBusConfig>

In the example above, I have configured that all messages from the assembly Messages except SomeSpecificMessage will be routed to someService, whereas SomeSpecificMessage has its own destination in the queue anotherService.

Note that this section is not required if the service is a publisher, because then it will know where to send messages because other services have subscribed, and in the process they leave the name of the queue where they can be found.

Conclusion

That concludes today’s “NServiceBus for dummies who want to be smarties”. This was about where messages go. Next post will be an example with a simple infrastructure for an ASP.NET MVC backend running on NServiceBus, accepting subscriptions from other services. It’s going to be hot!

NServiceBus for dummies who want to be smarties 2… second post, this time on how to do some more stuff with NServiceBus.

How to do stuff when the service starts

Make a class implement IWantToRunAtStartup, e.g. like so:

public class BuildPoolOfExpensiveObjects : IWantToRunAtStartup
{
    public void Run()
    {
        // build that pool
    }
 
    public void Stop()
    {
        // dispose it properly
    }
}

How to speed up delivery of messages that are transient in nature

If your message contents get stale after a short period of time, it makes no sense to use reliable messaging where messages are written to disk before the message queueing service attempts to deliver the messages to their destination. Therefore, to be true to the transient nature of the messages and speed up delivery, you can decorate some of your messages with the [Express] attribute. E.g. like so:

[Express]
public class SomeFrequentlyChangingValueJustChanged : IMessage
{
    public double Value { get; set; }
}

How to make messages expire after some amount of time

If you know your message content does not make sense after some period of time, say one hour, just decorate your message with the [TimeToBeReceived] attribute – e.g. like so:

[TimeToBeReceived]("01:00:00")]
public class AnotherPeriodicallyChangingValueJustChanged : IMessage
{
    public double Value { get; set; }
}

Note that the argument to the attribute must be Parseable – unfortunately C# does not allow for calling e.g. TimeSpan.FromHours(1) in the attribute initializer.

How to stop logging all kinds of noise to the console

Logging is good, but not all the time. To disable all of NServiceBus’ logging, just make your endpoint config implement the interface IWantCustomLogging and do nothing in the Init method – e.g. like so:

public class EndpointConfig : IConfigureThisEndpoint, AsA_Server, IWantCustomLogging
{
    public void Init()
    {
        // ... do nothing here =)
    }
}

Conclusion

That concludes today’s “NServiceBus for dummies who want to be smarties”. This was about how to add some more life to your service. Next post will be about the question: where do the messages go?

NServiceBus for dummies who want to be smarties 1… first post: on how to get started creating services with NServiceBus.

How to create messages

Creating messages with NServiceBus consists of performing the following steps:

1. Create a new project of type “Class Library”
2. Make the project reference NServiceBus.DLL (“Get it now”)
3. Create a class for each message, “tagging” each message class with the IMessage interface – see example below

public class CreateNewUserRequest : IMessage
{
    public string Username { get; set; }
}

Note that IMessage is just a marker interface, so it does not require you to implement anything.

How to create a service

Creating a service with NServiceBus consists of performing the following steps:

1. Create a new project of type “Class Library”
2. Make the project reference all the DLLs AND NServiceBus.Host.exe from the ZIP file
3. Make the project reference the message DLL from above
4. Make a class implement IConfigureThisEndpoint – see example below
5. Make the endpoint configuration class implement either AsA_Client, AsA_Server, or AsA_Publisher

public class EndpointConfig : IConfigureThisEndpoint, AsA_Server
{
}

How to run that service

Make each service project run the referenced NServiceBus.Host.exe inside its bin\Debug directory – e.g. CustomerService should, as its debug action, run the external program SolutionDir\CustomerService\bin\Debug\NServiceBus.Host.exe.

NServiceBus.Host.exe, referred to as “the generic host”, is actually a Windows service, that uses reflection to pick up all the assemblies that surround it, and use them to build a service.

This is why you need to implement IConfigureThisEndpoint – it’s a marker interface that tells the generic host to look for configuration in that class.

A nifty thing to do at this point, is to set your solution to debug multiple projects when you press F5 – do this by right clicking on the top node in solution explorer, select “Set startup projects…”, and make all your service projects start up when debugging.

How to do stuff in a service

Make a class in a service that implements IMessageHandler<TMessage>. This requires you to implement one function, Handle. See example below:

public class HandleCreateNewUserRequest : IMessageHandler<CreateNewUserRequest>
{
    public void Handle(CreateNewUserRequest message)
    {
        // ..... do stuff
    }
}

But how does the service get access to the bus?

NServiceBus defaults to using Spring for DI, so dependencies are automagically resolved – which also includes the bus! Which in turn means that the following code snippet can send messages by using the bus:

public class HandleCreateNewUserRequest : IMessageHandler<CreateNewUserRequest>
{
    public IBus Bus { get; set; }
 
    public void Handle(CreateNewUserRequest message)
    {
        Bus.Send(new DoSomethingSomewhere());
    }
}

Ok, but where does the message go?

Well, that depends – for this stuff to run, we need to do a tad more configuration by supplying each service with an app.config. E.g. like so:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="MsmqTransportConfig" type="NServiceBus.Config.MsmqTransportConfig, NServiceBus.Core" />
    <section name="UnicastBusConfig" type="NServiceBus.Config.UnicastBusConfig, NServiceBus.Core" />
  </configSections>
 
  <MsmqTransportConfig InputQueue="client"
                       ErrorQueue="error"
                       NumberOfWorkerThreads="1"
                       MaxRetries="5" />
 
  <UnicastBusConfig>
    <MessageEndpointMappings>
      <add Messages="Messages" Endpoint="server" />
    </MessageEndpointMappings>
  </UnicastBusConfig>
</configuration>

In this XML file, I am configuring the following things:

• The MsmqTransportConfig section tells the generic host that this service can be reached at client, which is just the name of a private message queue, which the framework will automatically create for us
• The UnicastBusConfig/MessageEndpointMappings section tells the framework that all message types from the assembly Messages should be sent to the message queue server

Please pay some respect and awe to the MaxRetries, ErrorQueue, and NumberOfWorkerThreads attributes – how cool is that?! It means that all exceptions that may happen inside your message handlers should not be handled by you, just let them bubble up to the framework and let it retry delivery up to 5 times until successful, or else the message will go to the error queue. That totally rids you of handling those pesky exceptions coming from your database transaction (hopefully rarely, or else your database is a bottleneck) being selected as the deadlock victim, temporarily unavailable external services unable to communicate, etc. Handling those things is truly the job of a framework.

Conclusion

That concludes today’s “NServiceBus for dummies who want to be smarties”. This was how to go about creating a simple service which is capable of receiving a message, and in the message handler it can send a message.