Hey, did you know that JasperFx Software is ready for formal support plans for Marten and Wolverine? Not only are we trying to make the “Critter Stack” tools be viable long term options for your shop, we’re also interested in hearing your opinions about the tools and how they should change.
Let’s build a small web service application using the whole “Critter Stack” and their friends, one small step at a time. For right now, the “finished” code is at CritterStackHelpDesk on GitHub.
The posts in this series are:
- Event Storming
- Marten as Event Store
- Marten Projections (this post)
- Integrating Marten into Our Application
- Wolverine as Mediator
- Web Service Query Endpoints with Marten
- Dealing with Concurrency
- Wolverine’s Aggregate Handler Workflow FTW!
- Command Line Diagnostics with Oakton
- Integration Testing Harness
- Marten as Document Database
- Asynchronous Processing with Wolverine
- Durable Outbox Messaging and Why You Care!
- Wolverine HTTP Endpoints
- Easy Unit Testing with Pure Functions
- Vertical Slice Architecture
- Messaging with Rabbit MQ
- The “Stateful Resource” Model
- Resiliency
In the previous post I showed how to use the Marten library as the storage mechanism for events and event streams within an event sourcing persistence strategy. If you’re following along, you’ve basically learned how to stuff little bits of JSON into a database as the authoritative source of truth for your system. You might be asking yourself “what the @#$%@# am I supposed to do this this stuff now?” In today’s post I’m going to show you how Marten can help you derive the current state of the system from the raw event data through its usage of projections.
For more information about the conceptual role of projections in an event sourcing system, see my colleague Oskar Dudycz‘s post Guide to Projections and Read Models in Event-Driven Architecture.
Back to our help desk service, last time we created event streams representing each incident with events like:
public record IncidentLogged(
Guid CustomerId,
Contact Contact,
string Description,
Guid LoggedBy
);
public class IncidentCategorised
{
public IncidentCategory Category { get; set; }
public Guid UserId { get; set; }
}
public record IncidentPrioritised(IncidentPriority Priority, Guid UserId);
public record AgentAssignedToIncident(Guid AgentId);
public record AgentRespondedToIncident(
Guid AgentId,
string Content,
bool VisibleToCustomer);
public record CustomerRespondedToIncident(
Guid UserId,
string Content
);
public record IncidentResolved(
ResolutionType Resolution,
Guid ResolvedBy,
DateTimeOffset ResolvedAt
);
Those events are directly stored in our database as our single source of truth, but we will absolute need to derive the current state of an incident to support:
- User interface screens
- Reports
- Decision making within the help desk workflow (what event sourcing folks call the “write model”
For now, let’s say that we’d really like to have this view of a single incident:
public class IncidentDetails
{
public Guid Id { get; set; }
public Guid CustomerId{ get; set; }
public IncidentStatus Status{ get; set; }
public IncidentNote[] Notes { get; set; } = Array.Empty<IncidentNote>();
public IncidentCategory? Category { get; set; }
public IncidentPriority? Priority { get; set; }
public Guid? AgentId { get; set; }
public int Version { get; set; }
}
Let’s teach Marten how to combine the raw events describing an incident into our new IncidentDetails view. The easiest possible way to do that is to drop some new methods onto our IncidentDetails class to “teach” Marten how to modify the projected view:
public class IncidentDetails
{
public IncidentDetails()
{
}
public IncidentDetails(IEvent<IncidentLogged> logged)
{
Id = logged.StreamId;
CustomerId = logged.Data.CustomerId;
Status = IncidentStatus.Pending;
}
public Guid Id { get; set; }
public Guid CustomerId{ get; set; }
public IncidentStatus Status{ get; set; }
public IncidentNote[] Notes { get; set; } = Array.Empty<IncidentNote>();
public IncidentCategory? Category { get; set; }
public IncidentPriority? Priority { get; set; }
public Guid? AgentId { get; set; }
// Marten itself will set this to its tracked
// revision number for the incident
public int Version { get; set; }
public void Apply(IncidentCategorised categorised) => Category = categorised.Category;
public void Apply(IncidentPrioritised prioritised) => Priority = prioritised.Priority;
public void Apply(AgentAssignedToIncident prioritised) => AgentId = prioritised.AgentId;
public void Apply(IncidentResolved resolved) => Status = IncidentStatus.Resolved;
public void Apply(ResolutionAcknowledgedByCustomer acknowledged) => Status = IncidentStatus.ResolutionAcknowledgedByCustomer;
public void Apply(IncidentClosed closed) => Status = IncidentStatus.Closed;
}
In action, the simplest way to execute the projection is to do a “live aggregation” as shown below:
static async Task PrintIncident(IDocumentStore store, Guid incidentId)
{
await using var session = store.LightweightSession();
// Tell Marten to load all events -- in order -- for the designated
// incident event stream, then project that data into an IncidentDetails
// view
var incident = await session.Events.AggregateStreamAsync<IncidentDetails>(incidentId);
}
You can see a more complicated version of this projection in action by running the EventSourcingDemo project from the command line. Just see the repository README for instructions on setting up the database.
Marten is using a set of naming conventions to “know” how to pass event data to the IncidentDetails objects. As you can probably guess, Marten is calling the Apply() overloads to mutate the InvoiceDetails object for each event based on the event type. Those conventions are documented here — and yes, there are plenty of other options for using more explicit code instead of the conventional approach if you don’t care for that.
This time, with immutability!
In the example above, I purposely chose the simplest possible approach, and that led me to using a mutable structure for InvoiceDetails that kept all the details of how to project the events in the InvoiceDetails class itself. As an alternative, let’s make the InvoiceDetails be immutable as a C# record instead like so:
public record IncidentDetails(
Guid Id,
Guid CustomerId,
IncidentStatus Status,
IncidentNote[] Notes,
IncidentCategory? Category = null,
IncidentPriority? Priority = null,
Guid? AgentId = null,
int Version = 1
);
And as another alternative, let’s say you’d rather have the Marten projection logic external to the nice, clean IncidentDetails code above. That’s still possible by creating a separate class. The most common projection type is to project the events of a single stream, and for that you can subclass the Marten SingleStreamProjection base class to create your projection logic as shown below:
public class IncidentDetailsProjection: SingleStreamProjection<IncidentDetails>
{
public static IncidentDetails Create(IEvent<IncidentLogged> logged) =>
new(logged.StreamId, logged.Data.CustomerId, IncidentStatus.Pending, Array.Empty<IncidentNote>());
public IncidentDetails Apply(IncidentCategorised categorised, IncidentDetails current) =>
current with { Category = categorised.Category };
public IncidentDetails Apply(IncidentPrioritised prioritised, IncidentDetails current) =>
current with { Priority = prioritised.Priority };
public IncidentDetails Apply(AgentAssignedToIncident prioritised, IncidentDetails current) =>
current with { AgentId = prioritised.AgentId };
public IncidentDetails Apply(IncidentResolved resolved, IncidentDetails current) =>
current with { Status = IncidentStatus.Resolved };
public IncidentDetails Apply(ResolutionAcknowledgedByCustomer acknowledged, IncidentDetails current) =>
current with { Status = IncidentStatus.ResolutionAcknowledgedByCustomer };
public IncidentDetails Apply(IncidentClosed closed, IncidentDetails current) =>
current with { Status = IncidentStatus.Closed };
}
The exact same set of naming conventions still apply here, with Apply() methods creating a new revision of the IncidentDetails for each event, and the Create() method helping Marten to start an IncidentDetails object for the first event in the stream.
This usage does require you to register the custom projection class upfront in the Marten configuration like this:
var connectionString = "Host=localhost;Port=5433;Database=postgres;Username=postgres;password=postgres";
await using var store = DocumentStore.For(opts =>
{
opts.Connection(connectionString);
// Telling Marten about the projection logic for the IncidentDetails
// view of the events
opts.Projections.Add<IncidentDetailsProjection>(ProjectionLifecycle.Live);
});
Don’t worry too much about that “Live” option, we’ll dive deeper into projection lifecycles as we progress in this series.
Summary and What’s Next
Projections are a Marten feature that enable you to create usable views out of the raw event data. We used the simplest projection recipes in this post to create an IncidentDetails vew out of the raw incident events that we will use later on to build our web service.
In this sample, I was showing Marten’s ability to evaluate projected views on the fly by loading the events into memory and combining them into the final projection result on demand. Marten also has the ability to persist these projected data views ahead of time for faster querying (“Inline” or “Async” projections). If you’re familiar with the concept of materialized views in databases that support that, projections running inline or in a background process are a close analogue.
In the next post, I think I just want to talk about how to integrate Marten into an ASP.Net Core application and utilize Marten in a simple MVC Core controller — but don’t worry, before we’re done, we’re going to replace the MVC Core code with much slimmer code using Wolverine, but one new concept or tool at a time!
The Shade Tree Developer 