Jasper as Mediator #

Recently there's been some renewed interest in the old Gof Mediator pattern as a way to isolate the actual functionality of web services and applications from the mechanics of HTTP request handling. In more concrete terms for .Net developers, a mediator tool allows you to keep MVC Core code ceremony out of your application business logic and service layer. It wasn't the original motivation of the project, but Jasper can be used as a full-featured mediator tool.

Let's jump into a sample project. Let's say that your system creates and tracks Items of some sort. One of the API requirements is to expose an HTTP endpoint that can accept an input that will create and persist a new Item, while also publishing an ItemCreated event message to any other system (or internal listener within the same system). For the technology stack, let's use:

• MVC Core as the Web API framework, but I'm mostly using the newer Minimal API feature for this
• Jasper as our mediator of course!
• Sql Server as the backing database store, using Jasper's Sql Server message persistence
• EF Core as the persistence mechanism

First off, let's start a new project with the dotnet new webapi template. Next, we'll add some configuration to add in Jasper, a small EF Core ItemDbContext service, and wire up our new service for Jasper's outbox and EF Core middleware:

From there, we'll slightly modify the Program file generated by the webapi template to add Jasper and opt into Jasper's extended command line support:

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("SqlServer");

builder.Host.UseJasper(opts =>
{
    // TODO -- use single helper that can read the connection string
    // from the DbContext
    opts.PersistMessagesWithSqlServer(connectionString);
    opts.UseEntityFrameworkCorePersistence();
});

// Register the EF Core DbContext
builder.Services.AddDbContext<ItemsDbContext>(
    x => x.UseSqlServer(connectionString),

    // This is important! Using Singleton scoping
    // of the options allows Jasper + Lamar to significantly
    // optimize the runtime pipeline of the handlers that
    // use this DbContext type
    optionsLifetime: ServiceLifetime.Singleton);

^{snippet source | anchor}

Now, let's add a Jasper message handler that will:

1. Handle a new CreateItemCommand message
2. Create a new Item entity and persist that with a new ItemsDbContext custom EF Core DbContext
3. Create and publish a new ItemCreated event message reflecting the new Item

Using idiomatic Jasper, that handler looks like this:

public class ItemHandler
{
    // This attribute applies Jasper's EF Core transactional
    // middleware
    [Transactional]
    public static ItemCreated Handle(
        // This would be the message
        CreateItemCommand command,

        // Any other arguments are assumed
        // to be service dependencies
        ItemsDbContext db)
    {
        // Create a new Item entity
        var item = new Item
        {
            Name = command.Name
        };

        // Add the item to the current
        // DbContext unit of work
        db.Items.Add(item);

        // This event being returned
        // by the handler will be automatically sent
        // out as a "cascading" message
        return new ItemCreated
        {
            Id = item.Id
        };
    }
}

^{snippet source | anchor}

Note, as long as this handler class is public and in the main application assembly, Jasper is going to find it and wire it up inside its execution pipeline. There's no explicit code or funky IoC registration necessary.

Now, moving up to the API layer, we can add a new HTTP endpoint to delegate to Jasper as a mediator with:

app.MapPost("/items/create", (CreateItemCommand cmd, ICommandBus bus) => bus.InvokeAsync(cmd));

^{snippet source | anchor}

There isn't much to this code -- and that's the entire point! When Jasper registers itself into a .Net Core application, it adds the ICommandBus service to the underlying system IoC container so it can be injected into controller classes or Minimal API endpoint as shown above.The ICommandBus.InvokeAsync(message) method takes the message passed in, finds the correct execution path for the message type, and executes the correct Jasper handler(s) as well as any of the registered Jasper middleware.

See also:

• Cascading messages from actions for a better explanation of how the ItemCreated event message is automatically published if the handler success.
• Messages and message handlers for the details of how to write Jasper message handlers and how they are discovered

As a contrast, here's what the same functionality looks like if you write all the functionality out explicitly in a controller action:

// This controller does all the transactional work and business
// logic all by itself
public class DoItAllMyselfItemController : ControllerBase
{
    private readonly IExecutionContext _messaging;
    private readonly ItemsDbContext _db;

    public DoItAllMyselfItemController(IExecutionContext messaging, ItemsDbContext db)
    {
        _messaging = messaging;
        _db = db;
    }

    [HttpPost("/items/create3")]
    public async Task Create([FromBody] CreateItemCommand command)
    {
        // Start the "Outbox" transaction
        await _messaging.EnlistInOutboxAsync(_db);

        // Create a new Item entity
        var item = new Item
        {
            Name = command.Name
        };

        // Add the item to the current
        // DbContext unit of work
        _db.Items.Add(item);

        // Publish an event to anyone
        // who cares that a new Item has
        // been created
        var @event = new ItemCreated
        {
            Id = item.Id
        };

        // Because the message context is enlisted in an
        // "outbox" transaction, these outgoing messages are
        // held until the ongoing transaction completes
        await _messaging.SendAsync(@event);

        // Commit the unit of work. This will persist
        // both the Item entity we created above, and
        // also a Jasper Envelope for the outgoing
        // ItemCreated message
        await _db.SaveChangesAsync();

        // After the DbContext transaction succeeds, kick out
        // the persisted messages in the context "outbox"
        await _messaging.FlushOutgoingMessagesAsync();
    }
}

^{snippet source | anchor}

So one, there's just more going on in the /items/create HTTP endpoint defined above because you're needing to do a little bit of additional work that Jasper can do for you inside of its execution pipeline (the outbox mechanics, the cascading message getting published, transaction management). Also though, you're now mixing up MVC controller stuff like the [HttpPost] attribute to control the Url for the endpoint and the service application code that exercises the data and domain model layers.

Getting a Response #

The controller methods above would both return an empty response body and the default 200 OK status code. But what if you want to return some kind of response body that gave the client of the web service some kind of contextual information about the newly created Item.

To that end, let's write a different controller action that will relay the body of the ItemCreated output of the message handler to the HTTP response body (and assume we'll use JSON because that makes the example code simpler):

app.MapPost("/items/create2", (CreateItemCommand cmd, ICommandBus bus) => bus.InvokeAsync<ItemCreated>(cmd));

^{snippet source | anchor}

Using the ICommandBus.Invoke<T>(message) overload, the returned ItemCreated response of the message handler is returned from the Invoke() message. To be perfectly clear, this only works if the message handler method returns a cascading message of the exact same type of the designated T parameter.