Book Image

Learning NServiceBus Sagas

By : Richard L Helton
Book Image

Learning NServiceBus Sagas

By: Richard L Helton

Overview of this book

Table of Contents (13 chapters)


NServiceBus (NSB) is the most popular Enterprise Service Bus (ESB) in C#. It complements many of the other C# frameworks by providing an end-to-end ESB framework solution to work with services and messaging. The website,, has many tools to assist in building endpoints, services, and messaging in Visual Studio. Visit for more details. There are also production tools to check on heartbeats of running endpoints and provide deep insights into running endpoints, services, and messages. NSB provides rapid development to allow integration into many different endpoints and services, for instance, e-mail, Secure File Transfer Protocol (SFTP), and the Windows Communication Foundation (WCF) protocol for web services.

Let's discuss using NHibernate, an object-oriented mapper (ORM) that maps objects to SQL databases, such as MySQL and SQL Server. As a developer, you will need to provide the mapping interface, usually an hbm.xml interface. While creating endpoints and sending messages NSB takes care of the mapping interface. This includes the creation of tables, logging, message durability, message retries, encryption, and many more components that help ensure high quality of software with the use of NSB. NSB provides many components, unique to NSB, needed for automation. NSB provides the following advantages:

  • Separation of duties: There is separation of duties from the frontend to the backend, allowing the frontend to fire a message to a service and continue in its processing, not worrying about the results until it needs an update. Also, the separation of workflow responsibility exists through separating out NSB services. One service could be used to send payments to a bank, and another service could be used to provide feedback of the current status of the payment to the MVC-EF database, so that a user may see their payment status.

  • Message durability: Messages are saved to queues between services so that if services are stopped, it can start from the messages in the queues when it restarts, and the messages will persist until told otherwise.

  • Workflow retries: Messages, or endpoints, can be told to retry a number of times until they completely fail and send an error. The error is automated to return to an error queue. For instance, a web service message can be sent to a bank, and it can be set to retry the web service every 5 minutes for 20 minutes before giving up completely. This is useful during any network or server issues.

  • Monitoring: NSB ServicePulse can keep a finger on the pulse of its services. Other monitoring can easily be done on the NSB queues to report on the number of messages.

  • Encryption: Messages between services and endpoints can be easily encrypted.

  • High availability: Multiple services or subscribers could be processing the same or similar messages from various services that are living on different servers. When one server, or service, goes down, others could be made available to take over those that are already running. Sagas are at the heart of the NServiceBus (NSB) workflow. Sagas save the message state in the form of saga data. They can retrieve the data as it is related to a message to update the message or data. This allows the NSB workflow to control the flow of data and messaging from end to end and correlate saved data to messages in the saga.

Messages are the means to transfer interaction and data between services in a service-oriented architecture (SOA). Sagas correlate, save, route, and manage processes that are started by these messages between services. Sagas even provide timeouts to ensure that messages do not live forever in a system.

Sagas provide decoupling between frontend websites and backend processes. It allows workflow to transfer so that a website can continue to do its work without having to wait for processes to return, such as the dreaded message "Please do not refresh this website as we bill your credit card".

NSB doesn't stop at development on Windows servers and desktops, but plays a big part in cloud development, for example with Microsoft Azure and the Microsoft cloud. NSB uses Service Bus as well as storage queues, SQL Server, and other storage containers. As the cloud is used more and more, NSB plays a key part in Software as a Service, as it is the premier framework for ESB in the C# clouds.

Even if your cloud solution doesn't end up being a C# compatible cloud, as many might hide the software running behind the cloud as being preparatory, NSB is a component for those that will do hybrid solutions, such as keeping data resident on-site. The connection to the cloud then will likely be via web services, and NSB sagas might likely provide the workflow to those web services.

From this book, you will discover the many features and characteristics of NSB, as follows:

  • Sagas handle messages. A saga is started, or updated, by a message and passes it through its message handler. As messages are passed into the saga, the saga updates its sagas data from these messages through a message handler. The message logic doesn't normally end at the saga, but the saga creates a new one and passes it on to the next service. The saga may also respond back to the originating client. The saga routes messages while saving state and may be routing based on the previous state.

  • Sagas contain long-lived transactions (LLTs) that contain database information for the messages for relatively long periods of time. An LLT is used when conditions such as short-lived transactions are not adequate. A short-lived transaction occurs when a call to a database, or MSMQ, performs a straightforward rollback or commit. For queues, NServiceBus performs second-level retries (SLRs) to try to commit a message a number of times before performing a rollback. In LLTs, there can be multiple conditions and multiple actions that need to take place for a message to be fully completed, or else operations execute the message from the beginning.

    The message is changed from one type of message into another, as one is handled by the saga, and the saga may create a new one with the same ID to pass to another service. Even though the message is different, it is a continuation of the flow of the original message that is considered a single transaction. The transaction is the accumulation of messages as they flow from one end to another end with the same message ID so that it represents the same transaction. The messages may be a different message type as it passes through different services. For instance, it may be an order message for an order service. The transaction can take seconds, days, hours, or longer, as the services take responsibility for acting upon it.

  • Sagas contain timeouts for timing out messages and states. Because messages can be long-lived, services are responsible for retrieving and moving them. Sagas can have timers set on messages and data so that it doesn't live forever or the timer could be part of the business logic; for example, a customer has 30 seconds to enter a pin for their debit card. Sagas contain state information. Sagas save saga data to the database based on the message's data. The saga data is initially started with a message, and it is also updated with messages that are passed in with the same identification information. When a message passes between different services, saving the state information before the next service is wise, as there might be a business requirement to revert to its original state.

NServiceBus is the C# platform of choice for those that require workflows. In sagas, high availability, high performance, monitoring, encryption, rapid deployment, and many more features can only be found in this framework when building

C# solutions.

What this book covers

Chapter 1, Introduction to Sagas, discusses NServiceBus and a basic design pattern that it uses, known as sagas, which is used to save states of messages. We will discuss the benefits of sagas and what it brings to the table with regard to software design.

Chapter 2, NServiceBus Saga Architecture, expands on the uses of sagas for persistence, timeouts, message durability, and message handling. We will discuss various message exchange patterns through examples to include gateway and cluster managing. These are important concepts as they drive the high availability and high performance that NSB brings to the table.

Chapter 3, The Particular Service Platform, is an overview of the Particular website-associated tools for NServiceBus. We will discuss building sagas through the ServiceMatrix tool, which is a Visual Studio extension tool for visually designing NSB endpoints, messages, and services. The other tools that we will discuss at length as they apply to sagas are the ServicePulse to monitor the endpoint availability during production, and ServiceInsight to take a deep dive into the functionality and properties of endpoints, services, and messages as they execute.

Chapter 4, Saga Development, focuses on various useful constructions of sagas and message handlers. The purpose of sagas will be discussed as the discussion goes into the need for extending and coordinating transactional integrity using sagas. The chapter then morphs into a discussion of NServiceBus, using integrated pre-built WCF bridges. While some might consider it unusual to discuss WCF in a saga chapter, sagas become an intermediate for coordinating WCF and NServiceBus work. We can decouple the workflow from the frontend for interaction with backend processes through message handling. Sagas provide the means to persist the state information of the messages. This discussion will also handle other queuing sources as well to include RabbitMQ and ActiveMQ.

Chapter 5, Saga Snippets, discusses two primary saga examples, one using an e-mail, and one using the Secure File Transfer Protocol (SFTP). These samples sill demonstrate the saga workflow and the use of timeouts more in depth. The saga code will be a mediator between a frontend Windows Presentation Framework (WPF) and a backend client executing either an e-mail or SFTP. Using a saga as a mediator between frontend and backend code that will interface into an external server, there will be many added benefits and features. The external server interface, such as an e-mail server or SFTP server, is usually beyond our control and is in the control of external operations or organizations, such as a bank. So, the interface into these servers is all that we have to work with, and as business, software and operational needs increase, we need a framework that is robust enough to meet these demands. Thus, we have NSB and sagas.

Chapter 6, Using NServiceBus in the Cloud, gives an introduction to the cloud with a deeper dive into the Microsoft Azure cloud. The Azure Storage containers and Service Bus will be discussed at length. An Azure Storage example will be discussed, which will work on-premise using the Azure SDK and Azure Storage Emulator. Another example will be given with NSB sagas as it works through Service Bus in the Azure cloud.

What you need for this book

We will discuss and build many examples in this book using Visual Studio 2012. Visual Studio Express could be used to walk through the samples as well. The user is expected to have a very basic understanding of C# and Visual Studio as we examine the use of NServiceBus.

All of the examples were originally built in the Windows Server 2008 operating system, and tested in both Windows 8.1 and Windows Server 2012.

For many of the database pieces, SQL Server Express, version 2008, was used. NServiceBus and many Particular tools will have to be installed from When installing NSB, DTC, MSMQ, and RavenDB, performance counters will have to be installed. This book will walk you through those steps.

Who this book is for

This book is for the beginner or intermediate C# developer who wants to learn how to develop with NServiceBus and explore the NSB sagas, which is the workflow heart of NSB. Many beginning pieces will be discussed with a deep dive into sagas using many different Microsoft frameworks, which will also provide some basic knowledge of using WPF, WCF, ASP.NET MVC, and Entity Frameworks.


In this book, you will find a number of text styles that distinguish between different kinds of information. Here are some examples of these styles and an explanation of their meaning.

Code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles are shown as follows: "The RequestTimeout() function could take seconds, minutes, hours, days, or could be executed at a specific time of day."

A block of code is set as follows:

using System;
using System.IO;
using ServiceControl.Plugin.CustomChecks;
using ServiceControl.Plugin.CustomChecks.Messages;
using ServiceControl.Plugin.CustomChecks.Internal;
namespace PaymentEngine.ECommerce
public class MyCustomCheck : CustomCheck
public MyCustomCheck()
: base("ECommerce SubmitPayment check", "ECommerce")

Any command-line input or output is written as follows:

PM> Get-NserviceBusLocalMachineSettings

New terms and important words are shown in bold. Words that you see on the screen, for example, in menus or dialog boxes, appear in the text like this: "When the TimerSubmit process receives the reply message, it will pop a Timer in Seconds window as follows."


Warnings or important notes appear in a box like this.


Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or disliked. Reader feedback is important for us as it helps us develop titles that you will really get the most out of.

To send us general feedback, simply e-mail , and mention the book's title in the subject of your message.

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide at

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Downloading the example code

You can download the example code files from your account at for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit and register to have the files e-mailed directly to you.


Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you could report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting, selecting your book, clicking on the Errata Submission Form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website or added to any list of existing errata under the Errata section of that title.

To view the previously submitted errata, go to and enter the name of the book in the search field. The required information will appear under the Errata section.


Piracy of copyrighted material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works in any form on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at with a link to the suspected pirated material.

We appreciate your help in protecting our authors and our ability to bring you valuable content.


If you have a problem with any aspect of this book, you can contact us at , and we will do our best to address the problem.