AI agents: use the documentation index at llms.txt to locate machine-readable pages. This section is indexed by https://docs.particular.net/tutorials/llms.txt. The markdown version of this page is served as plain text. An MCP server at /mcp serves the same content via the search_docs and read_doc tools; it is read-only and needs no credentials. Markdown versions of documentation pages are available by appending .md to the page URL. Directory URLs use index.md. They are served as text/plain because some retrieval backends reject text/markdown.

NServiceBus Sagas

In the NServiceBus step-by-step tutorial we created a functioning demo of a retail system that separates different concerns (like accepting an order, charging the credit card, and shipping the order) into different physical processes called endpoints that communicate by exchanging messages. We saw how the ability to publish events and create multiple subscribers lets us decouple our code so that each endpoint can focus on a single responsibility. Even in the face of errors and endpoint failures, we can fail gracefully and, in some cases, even recover to the point where our users don't even know an error occurred.

However, message handlers are stateless and many business processes are not. For example, how do we ship an order when we have to wait for both OrderPlaced and OrderBilled to be processed first? How do we create a delay so that we can trigger an action at some point in the future? How do we make decisions based on what happened minutes, hours, or even years ago?

For these types of scenarios, we need a stateful message handler. Other ways to describe what is needed might include a message-driven state machine or an orchestration engine. In NServiceBus, we call these Sagas. In this tutorial, we'll build on the solution from the NServiceBus Step-by-step tutorial and learn to master NServiceBus Sagas.

These lessons make the most sense when tackled in order, but it's not required.

  1. Saga basics (20-25 minutes) - learn how to introduce Sagas to complete the order shipping process.
  2. Timeouts (20-25 minutes) - learn how to delay processing of an order to implement the buyer's remorse pattern.
  3. Third-party integration (20-25 minutes) - learn how to execute multiple steps in a workflow and use timeouts to trigger compensating actions.