NServiceBus for dummies who want to be smarties 6

2009-11-30 by mookid8000 Leave a comment

NServiceBus for dummies who want to be smarties 6… sixth and last post in the series will show an example using the publish/subscribe functionality provided by NServiceBus.

One could image all kinds of cool integration scenarios where interested parties somehow receive events from our system regarding stuff that may be interesting to them. Let’s imagine that our user registration from the fifth post is an extremely interesting event to the sales department and the Über Boss of our enterprise.

To accomodate this, I create a separate assembly meant for holding messages that are not private to our application. This way, I can easily distinguish between messages that I can change whenever I feel like it, and messages that I must put more care and effort into crafting, because they will most likely live forever when a dozen applications in our enterprise are suddenly depending on them.

This means that my saga from the fifth post will handle an email confirmation like this:

    public void Handle(ConfirmRegistration message)
    {
      Console.WriteLine("Confirming email {0}", Data.Email);

      NewUserService.CreateNewUserAccount(Data.Email);

      MailSender.Send(Data.Email,
                      "Your registration request",
                      "Your email has been confirmed, and your user account has been created");

      Bus.Publish(new SomeoneActuallyRegistered {Email = Data.Email});

      MarkAsComplete();
    }

public void Handle(ConfirmRegistration message)

{

Console.WriteLine("Confirming email {0}", Data.Email);

NewUserService.CreateNewUserAccount(Data.Email);

MailSender.Send(Data.Email,

"Your registration request",

"Your email has been confirmed, and your user account has been created");

Bus.Publish(new SomeoneActuallyRegistered {Email = Data.Email});

MarkAsComplete();

}

As you can see, I Bus.Publish(...) a message saying that someone with a particular email has registered.

To be able to publish stuff, some kind of subscription storage must be configure for the endpoint. Therefore, I change my backend’s EndpointConfig to be configured with this:

      Configure.With()
        .CastleWindsorBuilder(container)
        .Sagas()
        .NHibernateSagaPersisterWithSQLiteAndAutomaticSchemaGeneration()
        .MsmqSubscriptionStorage()
        .XmlSerializer();

Configure.With()

.CastleWindsorBuilder(container)

.Sagas()

.NHibernateSagaPersisterWithSQLiteAndAutomaticSchemaGeneration()

.MsmqSubscriptionStorage()

.XmlSerializer();

– which means my backend will be storing subscriptions in a message queue.

If you are somehow unclear on the difference between sending and publishing, I can tell you that the conceptual difference is this: sending is like saying “do this stuff”, whereas publishing is like saying “this stuff happened” – see the difference in tense?

Functionally, the difference is that sending will put a message in the queue specified as recipient for that particular message whereafter one recipient will consume that message off its input queue (possibly competing with others), whereas publishing will put a message in the input queue of each one of whoever subscribed to that particular message (possibly many – possibly zero).

Now, to simulate the sales department and the über boss, I create two new projects containing an app.config that looks like this:

<?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="salesDept"
                       ErrorQueue="error"
                       NumberOfWorkerThreads="1"
                       MaxRetries="5" />

  <UnicastBusConfig>
    <MessageEndpointMappings>
      <add Messages="PublicMessages" Endpoint="backend" />
    </MessageEndpointMappings>
  </UnicastBusConfig>
</configuration>

<?xml version="1.0" encoding="utf-8" ?>

</configSections>

<MsmqTransportConfig InputQueue="salesDept"

ErrorQueue="error"

NumberOfWorkerThreads="1"

MaxRetries="5" />

</MessageEndpointMappings>

</UnicastBusConfig>

</configuration>

– and similarly for the über boss.

Note how a subscriber must have a message endpoint mapping telling where messages will be published – in the example above, my mapping specifies that all messages from my PublicMessages assembly can be subscribe to on the endpoint named “backend”. And obviously, a subscriber must have an input queue, through which subscribed messages will be received.

The EndpointConfig can look like this:

namespace SalesDept
{
  public class EndpointConfig : 
    IConfigureThisEndpoint, 
    AsA_Server, 
    IWantCustomLogging, 
    IWantToRunAtStartup
  {
    public IBus Bus { get; set; }

    public void Init()
    {
    }

    public void Run()
    {
      Bus.Subscribe<SomeoneActuallyRegistered>();

      Console.WriteLine("Sales department running...");
    }

    public void Stop()
    {
    }
  }
}

namespace SalesDept

{

public class EndpointConfig :

IConfigureThisEndpoint,

AsA_Server,

IWantCustomLogging,

IWantToRunAtStartup

{

public IBus Bus { get; set; }

public void Init()

{

}

public void Run()

{

Bus.Subscribe<SomeoneActuallyRegistered>();

Console.WriteLine("Sales department running...");

}

public void Stop()

{

}

– and similarly for the über boss as well.

Note how the service subscribes to the messages that it wants to receive by calling Bus.Subscribe<...> in the Run() method. What happens, is that NServiceBus somehow communicates to whoever is configured as the publisher of messages of type SomeoneActuallyRegistered, that messages should be sent to this service’s input queue.

And then, I implement a message hander in each service… first, the sales department:

namespace SalesDept
{
  public class SendInformationAboutProducts : IMessageHandler<SomeoneActuallyRegistered>
  {
    public void Handle(SomeoneActuallyRegistered message)
    {
      Console.WriteLine("Sending stupid emails to {0}", message.Email);
    }
  }
}

namespace SalesDept

{

public class SendInformationAboutProducts : IMessageHandler<SomeoneActuallyRegistered>

{

public void Handle(SomeoneActuallyRegistered message)

{

Console.WriteLine("Sending stupid emails to {0}", message.Email);

}

and then, the über boss:

namespace ÜberBoss
{
  public class NoteEmailInLittleBlackBookOfEvilSchemes : IMessageHandler<SomeoneActuallyRegistered>
  {
    public void Handle(SomeoneActuallyRegistered message)
    {
      Console.WriteLine("Noting email {0}", message.Email);
    }
  }
}

namespace ÜberBoss

{

public class NoteEmailInLittleBlackBookOfEvilSchemes : IMessageHandler<SomeoneActuallyRegistered>

{

public void Handle(SomeoneActuallyRegistered message)

{

Console.WriteLine("Noting email {0}", message.Email);

}

To make this run, I go to “Set StartUp projects…” of my solution and make all my services start up when I press F5.

Picture showing how to configure multiple startup projects

Now, we can check things out by pressing F5, thus running the backend, the sales department, and the über boss at once. On my machine, it looks like this:

Running three services at once

Now it doesn’t take too much imagination to come up with all kinds of cool solutions to integration scenarios.

Conclusion

That concludes the sixth and last post in my “NServiceBus for dummies who want to be smarties” series. I hope the series can provide some information on how to get started using NServiceBus, and perhaps fill out some of the gaps that comes from documentation in the form of sparsely available blog posts from different sources.

NServiceBus for dummies who want to be smarties 5

2009-11-27 by mookid8000 1 Comment

NServiceBus for dummies who want to be smarties 5… fifth post, this time with an example on how sagas can be used to implement a workflow in ASP.NET MVC.

One of the typical workflows in web applications is when someone signs up for an account, but the web site wants to check if the email address is valid. Let’s look at an example that goes like this:

User enters email address as a signup request
Web application sends email with a “secret” confirmation link
User visits the secret link, thereby activating the account

To keep things simple, I have made a simple page containing two forms: one for the email address, and one that simulates visiting a secret link by letting us enter a “ticket”. The view looks like this:

<p>
  Enter your email address to begin registration
</p>

<form method="post" action="!{Url.Action("BeginRegistration")}">
  Email: <input name="email" type="text" />
  <input type="submit" value="Begin registration" />
</form>

<p>
  - or enter your ticket to confirm your email
</p>

<form method="post" action="!{Url.Action("ConfirmRegistration")}">
  Ticket: <input name="ticket" type="text" />
  <input type="submit" value="Confirm registration" />
</form>

<p>

Enter your email address to begin registration

</p>

Email: <input name="email" type="text" />

</form>

<p>

- or enter your ticket to confirm your email

</p>

Ticket: <input name="ticket" type="text" />

</form>

And then I have made this simple controller to handle the posts from the registration page:

  public class RegistrationController : TxBaseController
  {
    readonly IBus bus;

    public RegistrationController(IBus bus)
    {
      this.bus = bus;
    }

    public ViewResult Index()
    {
      return View();
    }

    public RedirectToRouteResult BeginRegistration(string email)
    {
      bus.Send(new RequestRegistration {Email = email});

      return RedirectToAction("Index");
    }

    public RedirectToRouteResult ConfirmRegistration(int ticket)
    {
      bus.Send(new ConfirmRegistration {Ticket = ticket});

      return RedirectToAction("Index");
    }
  }

public class RegistrationController : TxBaseController

{

readonly IBus bus;

public RegistrationController(IBus bus)

{

this.bus = bus;

}

public ViewResult Index()

{

return View();

}

public RedirectToRouteResult BeginRegistration(string email)

{

bus.Send(new RequestRegistration {Email = email});

return RedirectToAction("Index");

}

public RedirectToRouteResult ConfirmRegistration(int ticket)

{

bus.Send(new ConfirmRegistration {Ticket = ticket});

return RedirectToAction("Index");

}

Now, to model this workflow we need some kind of persistence on our backend, which is where sagas come into the picture. Sagas is the built-in mechanism in NServiceBus that helps in building stateful services. Stateful services are, as the word implies, services that preserve some kind of state between receiving messages.

The NServiceBus saga is a nifty way to declare what that state should contain (by letting a class implement ISagaEntity) and – given a message that the saga can handle – how to retrieve that saga (by overriding ConfigureHowToFindSaga and setting up which properties to compare).

Lets start out by specifying that NServiceBus should take care of persisting the saga entity (which will by done through Fluent NHibernate/NHibernate/SQLite under the hood)… that can easily be achieved by changing our backend’s endpoint configuration to this:

      Configure.With()
        .CastleWindsorBuilder(container)
        .Sagas()
        .NHibernateSagaPersisterWithSQLiteAndAutomaticSchemaGeneration()
        .XmlSerializer();

Configure.With()

.CastleWindsorBuilder(container)

.Sagas()

.NHibernateSagaPersisterWithSQLiteAndAutomaticSchemaGeneration()

.XmlSerializer();

This will make NServiceBus persist ongoing sagas in an SQLite db file called “NServiceBus.Sagas.sqlite” inside the backend’s execution directory. If you omit the NHibernateSagaPersisterWithSQLiteAndAutomaticSchemaGeneration() thing, NServiceBus will store ongoing sagas by using its InMemorySagaPersister, which – surprise! – stores sagas in memory.

I had some problems with the in-memory persister however, as I could not make it correlate messages with my saga unless I correlated with interned strings only, by implementing getters on my messages like so:

public string Email
{ 
    get { return string.Intern(email); }
    set { email = value; }
}

public string Email

{

get { return string.Intern(email); }

set { email = value; }

}

I imagine this has to do with a deserializer somewhere, somehow generating strings that are not interned, although I have not verified this – I am only guessing! No biggie though, as long as the SQLite saga persister is so easy to use.

In my example the saga is initiated by the RequestRegistration message which contains only an email. When the saga receives that message, the email is stored, and a secret ticket is generated, emailed to the user, and stored in the saga data. The saga is completed when it receives a ConfirmRegistration message with the right ticket.

Let’s specify what will constitute the saga data:

  public class UserRegistrationSagaData : ISagaEntity
  {
    public virtual Guid Id { get; set; }
    public virtual string Originator { get; set; }
    public virtual string OriginalMessageId { get; set; }

    public virtual string Email { get; set; }
    public virtual int Ticket { get; set; }
  }

public class UserRegistrationSagaData : ISagaEntity

{

public virtual Guid Id { get; set; }

public virtual string Originator { get; set; }

public virtual string OriginalMessageId { get; set; }

public virtual string Email { get; set; }

public virtual int Ticket { get; set; }

}

The first three properties come from the ISagaEntity interface – and then come my two properties for storing the email and the ticket.

Please do remember to mark all the properties of your saga data as virtual! Otherwise, Fluent NHibernate will throw some stupid exception, saying that “Database was not configured through Database method” (wtf?) (thanks to this post for sorting that one out!). The exception is fair though, as NHibernate would complain about not being able to create proxies if there were un-interceptable properties on the data class – the error message is just weird…

To create a saga, you let a class inherit from Saga<TSagaEntity> where TSagaEntity would be UserRegistrationSagaData in my example… and then we implement ISagaStartedBy<TMessage> and IMessageHandler<TMessage> where the two TMessage type parameters should be filled out with RequestRegistration and ConfirmRegistration respectively. Like so:

  public class UserRegistrationSaga : Saga<UserRegistrationSagaData>,
    ISagaStartedBy<RequestRegistration>,
    IMessageHandler<ConfirmRegistration>
  {
     //...
  }

public class UserRegistrationSaga : Saga<UserRegistrationSagaData>,

ISagaStartedBy<RequestRegistration>,

IMessageHandler<ConfirmRegistration>

{

//...

}

– and then – given the two kind of messages my saga can handle – how to correlate the messages with my saga:

    public override void ConfigureHowToFindSaga()
    {
      ConfigureMapping<RequestRegistration>(saga => saga.Email, message => message.Email);
      ConfigureMapping<ConfirmRegistration>(saga => saga.Ticket, message => message.Ticket);
    }

public override void ConfigureHowToFindSaga()

{

ConfigureMapping<RequestRegistration>(saga => saga.Email, message => message.Email);

ConfigureMapping<ConfirmRegistration>(saga => saga.Ticket, message => message.Ticket);

}

Even though my saga is initiated by RequestRegistration, I set up a mapping that ensures that a new saga will not be created if someone requests registration twice with the same email.

Lastly, the actual logic carried out by the saga – the two message handlers (note that MailSender and NewUserService are application services that are automagically injected becuase they’re public properties of the saga):

    public void Handle(RequestRegistration message)
    {
      // generate new ticket if it has not been generated
      if (Data.Ticket == 0)
      {
        Data.Ticket = NewUserService.CreateTicket();
      }

      Data.Email = message.Email;

      MailSender.Send(message.Email,
                      "Your registration request",
                      "Please go to /registration/confirm and enter the following ticket: " + Data.Ticket);

      Console.WriteLine("New registration request for email {0} - ticket is {1}", Data.Email, Data.Ticket);
    }

    public void Handle(ConfirmRegistration message)
    {
      Console.WriteLine("Confirming email {0}", Data.Email);

      NewUserService.CreateNewUserAccount(Data.Email);

      MailSender.Send(Data.Email,
                      "Your registration request",
                      "Your email has been confirmed, and your user account has been created");

      // tell NServiceBus that this saga can be cleaned up afterwards
      MarkAsComplete();
    }

public void Handle(RequestRegistration message)

{

// generate new ticket if it has not been generated

if (Data.Ticket == 0)

{

Data.Ticket = NewUserService.CreateTicket();

}

Data.Email = message.Email;

MailSender.Send(message.Email,

"Your registration request",

"Please go to /registration/confirm and enter the following ticket: " + Data.Ticket);

Console.WriteLine("New registration request for email {0} - ticket is {1}", Data.Email, Data.Ticket);

}

public void Handle(ConfirmRegistration message)

{

Console.WriteLine("Confirming email {0}", Data.Email);

NewUserService.CreateNewUserAccount(Data.Email);

MailSender.Send(Data.Email,

"Your registration request",

"Your email has been confirmed, and your user account has been created");

// tell NServiceBus that this saga can be cleaned up afterwards

MarkAsComplete();

}

Note how I mark the saga as complete by calling MarkAsComplete(), thus allowing the saga data to be deleted. This could also be a nifty place to save the time of when the last registration email was sent to a particular address in order to disallow sending another registration email for the next hour or so, to avoid people spamming each other by using our web site.

Now, if I fire up my backend and request registration with the email [email protected], it looks like this:

Submitting email as a registration request
The result on the backend showing that the message was properly received

Then, if I request registration with [email protected] followed by [email protected], I can verify that a new saga is only created for [email protected]:

Submitting the same email twice results in the same ticket being sent out

And then, when I confirm a registration request, it looks like this:

Submitting one of the 'secret' tickets
The result on the backend after having submitted on of the tickets

Isn’t that great? I cannot imagine a framework with an API more elegant and terse than this.

Conclusion

That was the fifth post in my “NServiceBus for dummies who want to be smarties” series. Sixth and last post will be about our backend publishing messages whenever interesting stuff happens. This will provide a message based interface for interested parties to subscribe to.

NServiceBus for dummies who want to be smarties 4

2009-11-17 by mookid8000 Leave a comment

NServiceBus for dummies who want to be smarties 4… fourth post, this time on how to incorporate NServiceBus as a backend in an ASP.NET MVC application.

How to create the projects

First, create a new ASP.NET MVC project. I assume you know how to use an IoC container to instantiate controllers, and that you know how to configure your container (otherwise, there are plenty of information available – e.g. here and here), so I will just show this simple snippet on how to build the bus and put it in the container:

In Application_Start:

ControllerBuilder.Current.SetControllerFactory(new WindsorControllerFactory(CreateWindsorContainer()));

1	ControllerBuilder.Current.SetControllerFactory(new WindsorControllerFactory(CreateWindsorContainer()));

– and then the container can be created like this:

    IWindsorContainer CreateWindsorContainer()
    {
      var container = new WindsorContainer();

      // register controllers and other stuff here

      Configure.WithWeb()
        .CastleWindsorBuilder(container)
        .XmlSerializer()
        .MsmqTransport()
          .IsTransactional(true)
          .PurgeOnStartup(true)
        .UnicastBus()
        .CreateBus()
        .Start();

      return container;
    }

IWindsorContainer CreateWindsorContainer()

{

var container = new WindsorContainer();

// register controllers and other stuff here

Configure.WithWeb()

.CastleWindsorBuilder(container)

.XmlSerializer()

.MsmqTransport()

.IsTransactional(true)

.PurgeOnStartup(true)

.UnicastBus()

.CreateBus()

.Start();

return container;

}

Notice the call to the extension method CastleWindsorBuilder? It comes from the assembly NServiceBus.ObjectBuilder.CastleWindsor.dll which is included with NServiceBus – it provides the adapters necessary for NServiceBus to a) register everything it discovers (like e.g. all your implementations of IHandleMessages<>), and b) pull instances when needed thus supplying dependencies during object activation. This way of supporting multiple IoC containers just plain ROCKS!

At this point NServiceBus has registered itself and registered all message handlers found in the current web application’s bin directory ( Configure.WithWeb() as opposed to Configure.With()) in the supplied IoC container, and since I am pulling all my controllers from Windsor, I can jump directly to implementing my HomeController:

  public class HomeController : TxBaseController
  {
    readonly IBus bus;

    public HomeController(IBus bus)
    {
      this.bus = bus;
    }

    [AcceptVerbs(HttpVerbs.Post)]
    public RedirectToRouteResult DoSomething(string text)
    {
      bus.Send(new SomethingHappened {Message = text});

      return RedirectToAction("Index");
    }

    [AcceptVerbs(HttpVerbs.Post)]
    public RedirectToRouteResult DoSomethingBad(string text)
    {
      bus.Send(new SomethingHappened { Message = text });

      throw new ApplicationException("oh noes!");
    }

    public ViewResult Index()
    {
      return View();
    }
  }

public class HomeController : TxBaseController

{

readonly IBus bus;

public HomeController(IBus bus)

{

this.bus = bus;

}

[AcceptVerbs(HttpVerbs.Post)]

public RedirectToRouteResult DoSomething(string text)

{

bus.Send(new SomethingHappened {Message = text});

return RedirectToAction("Index");

}

[AcceptVerbs(HttpVerbs.Post)]

public RedirectToRouteResult DoSomethingBad(string text)

{

bus.Send(new SomethingHappened { Message = text });

throw new ApplicationException("oh noes!");

}

public ViewResult Index()

{

return View();

}

As you can see, I implemented two actions responding to a HTTP post, both sending a message to the backend, but DoSomethingBad throws an exception, in which case i do not want the message to actually be sent.

My view is just a trivial (Spark) view with two forms:

<use master="Site"/>

<h1>DoSomething</h1>
<form method="post" action="!{Url.Action("DoSomething")}">
  Enter text: <input type="text" name="text" />
  <input type="submit" value="Send" />
</form>

<h1>DoSomethingBad</h1>
<form method="post" action="!{Url.Action("DoSomethingBad")}">
  Enter text: <input type="text" name="text" />
  <input type="submit" value="Send" />
</form>

<h1>DoSomething</h1>

Enter text: <input type="text" name="text" />

</form>

<h1>DoSomethingBad</h1>

Enter text: <input type="text" name="text" />

</form>

And then I made a simple backend with one message handler:

  public class HandleSomethingHappened : IHandleMessages<SomethingHappened>
  {
    public void Handle(SomethingHappened message)
    {
      Console.WriteLine("Something happened: {0}", message.Message);
    }
  }

public class HandleSomethingHappened : IHandleMessages<SomethingHappened>

{

public void Handle(SomethingHappened message)

{

Console.WriteLine("Something happened: {0}", message.Message);

}

Now, to check if things work, I navigate to /home/index, which on my computer looks like this:

dosomething

– and then I enter the text “WHEE!” into the first text field and press “Send”, yielding the following in my backend’s console window:

fantastic

Which is great! My backend receives messages from my web application, so now I can put all kinds of heavy calculations and processesing and whatnot in there, to be computed outside of web requests.

Now, what if something bad happens during the web request, and we do not want any messages to actually be sent? Well, if I enter a text into the other text field and submit it (to the DoSomethingBad action of my HomeController), nothing happens on the backend! Why is that?

Simply because I have started a TransactionScope in my controller layer supertype, TxBaseController, ensuring that all controller actions are run inside a (possibly distributed) transaction! It looks like this:

  public abstract class TxBaseController : Controller
  {
    TransactionScope currentTx;

    protected override void OnActionExecuting(ActionExecutingContext filterContext)
    {
      currentTx = new TransactionScope();

      base.OnActionExecuting(filterContext);
    }

    protected override void OnActionExecuted(ActionExecutedContext filterContext)
    {
      base.OnActionExecuted(filterContext);

      var exceptionHappened = filterContext.Exception != null;
      var exceptionWasHandled = filterContext.ExceptionHandled;

      if (!exceptionHappened || exceptionWasHandled)
      {
        currentTx.Complete();
      }

      currentTx.Dispose();
    }
  }

public abstract class TxBaseController : Controller

{

TransactionScope currentTx;

protected override void OnActionExecuting(ActionExecutingContext filterContext)

{

currentTx = new TransactionScope();

base.OnActionExecuting(filterContext);

}

protected override void OnActionExecuted(ActionExecutedContext filterContext)

{

base.OnActionExecuted(filterContext);

var exceptionHappened = filterContext.Exception != null;

var exceptionWasHandled = filterContext.ExceptionHandled;

if (!exceptionHappened || exceptionWasHandled)

{

currentTx.Complete();

}

currentTx.Dispose();

}

– and since message queueing plays along nicely with the currently ongoing ambient transaction (which e.g. the incredible NHibernate ALSO does), this transaction scope will make sure that everything just works!

Conclusion

That concludes today’s “NServiceBus for dummies who want to be smarties”. This one was on how to actually put NServiceBus to use as a simple backend for an ASP.NET MVC web application. Freaking easy, right?! Next time I will show how to put sagas to use by implementing one of the workflows of a typical web application.

NServiceBus for dummies who want to be smarties 3

2009-11-15 by mookid8000 Leave a comment

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" />

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

</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

2009-11-13 by mookid8000 2 Comments

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
    }
}

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; }
}

[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; }
}

[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 =)
    }
}

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

2009-11-11 by mookid8000 Leave a comment

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:

Create a new project of type “Class Library”
Make the project reference NServiceBus.DLL (“Get it now”) from the binaries folder
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; }
}

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:

Create a new project of type “Class Library”
Make the project reference NServiceBus.dll, NServiceBus.Core.dll, log4net.dll, and NServiceBus.Host.exe
Make the project reference the message DLL from above
Make a class implement IConfigureThisEndpoint – see example below
Make the endpoint configuration class implement either AsA_Client, AsA_Server, or AsA_Publisher

public class EndpointConfig : IConfigureThisEndpoint, AsA_Server
{
}

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 IHandleMessages<TMessage>. This requires you to implement one function, Handle. See example below:

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

public class HandleCreateNewUserRequest : IHandleMessages<CreateNewUserRequest>

{

public void Handle(CreateNewUserRequest message)

{

// ..... do stuff

}

But how does the service get access to the bus?

NServiceBus defaults to using Spring.NET 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 : IHandleMessages<CreateNewUserRequest>
{
    public IBus Bus { get; set; }

    public void Handle(CreateNewUserRequest message)
    {
        Bus.Send(new DoSomethingSomewhere());
    }
}

public class HandleCreateNewUserRequest : IHandleMessages<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>

<?xml version="1.0" encoding="utf-8" ?>

</configSections>

<MsmqTransportConfig InputQueue="client"

ErrorQueue="error"

NumberOfWorkerThreads="1"

MaxRetries="5" />

</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 the message types from the assembly Messages are owned by the service behind the server endpoint

Why do I say that the messages “are owned by the service behind the server endpoint”? Why not just say that the message endpoint mappings configure the destination? Consider this table:

Operation	Who performs the operation	Who has IHandleMessages<TMessage>
bus.Send	client	server
bus.Publish	server	client

As you can see, there’s more to the endpoint mappings than just specifying the message destination – a more careful and precise description is that the endpoint mappings specify who owns the messages.

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.

ReSharper 5 and ASP.NET MVC goodies

2009-11-11 by mookid8000 Leave a comment

I have probably only scratched the surface of the goodies that JetBrains have added to the new ReSharper 5, but here’s two nifties I discovered today: F12 jumps from the redirect string to the corresponding action method in my controller (the light arrow), and F12 on a view result method gives me the ability to jump to the corresponding view (the gray arrow). That’ s just neat!

resharper_aspnet_mvc