In the first part of the tutorial, we saw that publishing events using the Publish-Subscribe pattern reduces coupling and makes maintaining a system easier in the long run. Next, we saw how to react to failures gracefully. Let's now look at how we can add an additional subscriber without needing to modify any existing code.
If you didn't already download the quick start project in the previous lesson, you can download it now:
As shown in the diagram, we'll be adding a new messaging endpoint called Shipping that will subscribe to the OrderPlaced
event.
dotnet new
, dotnet add package
, and dotnet add reference
, but you can do the same things using the graphical tools in Visual Studio if you prefer.Create a new endpoint
First we'll create the Shipping project and set up its dependencies.
First let's make sure both browser windows and all console applications are closed, and in the terminal, we're in the root of the project where the RetailDemo.sln file is located:
> cd tutorials-quickstart
Next, we'll create a new Console Application project named Shipping and add it to the solution:
> dotnet new console --name Shipping --framework net6.0
> dotnet sln add Shipping
Now, we need to add references to the Messages project, as well as the NuGet packages we will need.
> dotnet add Shipping reference Messages
> dotnet add Shipping package NServiceBus
> dotnet add Shipping package NServiceBus.Extensions.Hosting
> dotnet add Shipping package NServiceBus.Heartbeat
> dotnet add Shipping package NServiceBus.Metrics.ServiceControl
Now that we have a project for the Shipping endpoint, we need to add some code to configure and start an NServiceBus
endpoint. In the Shipping project, find the auto-generated Program.cs file and replace its contents with the following.
using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using NServiceBus;
namespace Shipping
{
class Program
{
static async Task Main(string[] args)
{
Console.Title = "Shipping";
await CreateHostBuilder(args).RunConsoleAsync();
}
public static IHostBuilder CreateHostBuilder(string[] args)
{
return Host.CreateDefaultBuilder(args)
.UseNServiceBus(context =>
{
// Define the endpoint name
var endpointConfiguration = new EndpointConfiguration("Shipping");
// Choose JSON to serialize and deserialize messages
endpointConfiguration.UseSerialization<SystemJsonSerializer>();
// Select the learning (filesystem-based) transport to communicate
// with other endpoints
endpointConfiguration.UseTransport<LearningTransport>();
// Enable monitoring errors, auditing, and heartbeats with the
// Particular Service Platform tools
endpointConfiguration.SendFailedMessagesTo("error");
endpointConfiguration.AuditProcessedMessagesTo("audit");
endpointConfiguration.SendHeartbeatTo("Particular.ServiceControl");
// Enable monitoring endpoint performance
var metrics = endpointConfiguration.EnableMetrics();
metrics.SendMetricDataToServiceControl("Particular.Monitoring",
TimeSpan.FromMilliseconds(500));
// Return the completed configuration
return endpointConfiguration;
});
}
}
}
Take special note of the comments in this code, which annotate the various parts of the NServiceBus configuration we're using.
We want the Shipping endpoint to run when you debug the solution, so use Visual Studio's multiple startup projects feature to configure the Shipping endpoint to start along with ClientUI, Sales, and Billing.
Create a new message handler
Next, we need a message handler to process the OrderPlaced
event. When NServiceBus starts, it will detect the message handler and handle subscribing to the event automatically.
To create the message handler:
- In the Shipping project, create a new class named
OrderPlacedHandler
. - Mark the handler class as public, and implement the
IHandleMessages
interface.<OrderPlaced> - Add a logger instance, which will allow us to take advantage of the logging system used by NServiceBus. This has an important advantage over
Console.
: the entries written with the logger will appear in the log file in addition to the console. Use this code to add the logger instance to the handler class:WriteLine() static ILog log = LogManager.GetLogger<OrderPlacedHandler>();
- Within the
Handle
method, use the logger to record when theOrderPlaced
message is received, including the value of theOrderId
message property:log.Info($"Shipping has received OrderPlaced, OrderId = {message.OrderId}");
- Since everything we have done in this handler method is synchronous, return
Task.
.CompletedTask
When complete, the OrderPlacedHandler
class should look like this:
using System.Threading.Tasks;
using NServiceBus;
using NServiceBus.Logging;
using Messages;
namespace Shipping
{
public class OrderPlacedHandler :
IHandleMessages<OrderPlaced>
{
static ILog log = LogManager.GetLogger<OrderPlacedHandler>();
public Task Handle(OrderPlaced message, IMessageHandlerContext context)
{
log.Info($"Shipping has received OrderPlaced, OrderId = {message.OrderId}");
return Task.CompletedTask;
}
}
}
Run the updated solution
Now run the solution, and assuming you remembered to update the startup projects, a window for the Shipping endpoint will open in addition to the other three.
As you place orders by clicking the button in the ClientUI web view, you will see the Shipping endpoint reacting to OrderPlaced
events:
INFO Shipping has received OrderPlaced, OrderId = 25c5ba63
Shipping is now receiving events published by Sales without having to change the code in the Sales endpoint. Additional subscribers could be added, for example, to email a receipt to the customer, notify a fulfillment agency via a web service, update a wish list or gift registry, or update data on items that are frequently bought together. Each business activity would occur in its own isolated message handler and doesn't depend on what happens in other parts of the system.
Summary
In this tutorial, we explored the basics of how a messaging system using NServiceBus works.
We learned that asynchronous messaging failures in one part of a system can be isolated and prevent complete system failure. This level of resilience and reliability is not easy to achieve with traditional REST-based web services.
We saw how automatic retries provide protection from transient failures like database deadlocks. If we implement a multi-step process as a series of message handlers, then each step will be executed independently and can be automatically retried in case of failures. This means that a stray exception won't abort an entire process, leaving the system in an inconsistent state.
We saw how the tooling in the Particular Service Platform makes running a distributed system much easier. ServicePulse gives us critical insights into the health of a system, and allows us to diagnose and fix systemic failures. We don't have to worry about data loss—once we redeploy our system, we can replay failed messages in batches as if the error had never occurred.
We also implemented an additional event subscriber, showing how to decouple independent bits of business logic from each other. The ability to publish one event and then implement resulting steps in separate message handlers makes the system much easier to maintain and evolve.