We just released a new batch of improvements in the Marten 8.4 release that improved Marten‘s already strong support for tracking metadata on event persistence.
Override Event Metadata on Individual Events
This work was done at the behest of a JasperFx Software client. They only needed to vary header values between events, but while the hood was popped up on event metadata, we finally addressed the long awaited ability to explicitly set event timestamps.
First, we finally have the ability to allow users to modify metadata on an event by event basis including the event timestamp. This has been a long standing request from many folks to either facilitate testing scenarios or to enable easier data importing from other databases or event stores. And especially now that Marten is arguably the best event sourcing solution for .NET, folks really should have a viable path to import data from external sources.
You can do that either by grabbing the IEvent wrapper and modifying the timestamp, causation, correlation, event id (valuable for tracing event data back to external systems), or headers like this sample:
public static async Task override_metadata(IDocumentSession session)
{
var started = new QuestStarted { Name = "Find the Orb" };
var joined = new MembersJoined
{
Day = 2, Location = "Faldor's Farm", Members = new string[] { "Garion", "Polgara", "Belgarath" }
};
var slayed1 = new MonsterSlayed { Name = "Troll" };
var slayed2 = new MonsterSlayed { Name = "Dragon" };
var joined2 = new MembersJoined { Day = 5, Location = "Sendaria", Members = new string[] { "Silk", "Barak" } };
var action = session.Events
.StartStream<QuestParty>(started, joined, slayed1, slayed2, joined2);
// I'm grabbing the IEvent wrapper for the first event in the action
var wrapper = action.Events[0];
wrapper.Timestamp = DateTimeOffset.UtcNow.Subtract(1.Hours());
wrapper.SetHeader("category", "important");
wrapper.Id = Guid.NewGuid(); // Just showing that you *can* override this value
wrapper.CausationId = wrapper.CorrelationId = Activity.Current?.Id;
await session.SaveChangesAsync();
}
Or by appending an already wrapped IEvent as I’m showing here, along with some new convenience wrapper extension methods to make the mechanics a little more declarative:
public static async Task override_metadata2(IDocumentSession session)
{
var started = new QuestStarted { Name = "Find the Orb" };
var joined = new MembersJoined
{
Day = 2, Location = "Faldor's Farm", Members = new string[] { "Garion", "Polgara", "Belgarath" }
};
var slayed1 = new MonsterSlayed { Name = "Troll" };
var slayed2 = new MonsterSlayed { Name = "Dragon" };
var joined2 = new MembersJoined { Day = 5, Location = "Sendaria", Members = new string[] { "Silk", "Barak" } };
// The result of this is an IEvent wrapper around the
// started data with an overridden timestamp
// and a value for the "color" header
var wrapper = started.AsEvent()
.AtTimestamp(DateTimeOffset.UtcNow.Subtract(1.Hours()))
.WithHeader("color", "blue");
session.Events
.StartStream<QuestParty>(wrapper, joined, slayed1, slayed2, joined2);
await session.SaveChangesAsync();
}
The second approach is going to be necessary if you are appending events with the FetchForWriting() API (and you should be within any kind of CQRS “write” handler).
There is of course a catch. If you use the “QuickAppend” option in Marten and want to be able to override the event timestamps, you’ll need this slightly different option instead:
var builder = Host.CreateApplicationBuilder();
builder.Services.AddMarten(opts =>
{
opts.Connection(builder.Configuration.GetConnectionString("marten"));
// This is important!
opts.Events.AppendMode = EventAppendMode.QuickWithServerTimestamps;
});
To avoid causing database breaking changes when upgrading, the ability to override timestamps with the “QuickAppend” option required this new “opt in” setting because this forces Marten to generate both “glue” code and a database function a little differently.
Capturing the User Name on Persisted Events
These kinds of features have to be “opt in” so that we don’t cause database changes in a minor release when people upgrade. Having to worry about “opt in” or “opt out” mechanics and backwards compatibility is both the curse and enabler of long running software tool projects like Marten.
Another request from the back log was to have a first class tracking of the user name (or process name) in events based on the current user of whatever operation appended the events. Following along with the “opt in” support for tracking correlation and causation ids, we’ll first need to opt into storing the user name with events:
var builder = Host.CreateApplicationBuilder();
builder.Services.AddMarten(opts =>
{
opts.Connection(builder.Configuration.GetConnectionString("marten"));
opts.Events.MetadataConfig.UserNameEnabled = true;
});
And now we can apply the user name to persisted events something like this:
public static async Task Handle(StartInvoice command, IDocumentSession session, ClaimsPrincipal principal)
{
// Marking the session as being modified by this active user
session.LastModifiedBy = principal.Identity.Name;
// Any events persisted by this session will be tagged with the current user
// in the database
session.Events.StartStream(new InvoiceStarted(command.Name, command.Amount));
await session.SaveChangesAsync();
}
And while this should probably only be used for diagnostics mostly, you can now query against the raw event data with LINQ for the user name (assuming that it’s captured of course!) like this sample from our tests:
[Theory]
[InlineData(JasperFx.Events.EventAppendMode.Rich)]
[InlineData(JasperFx.Events.EventAppendMode.Quick)]
public async Task capture_user_name_information(EventAppendMode mode)
{
EventAppendMode = mode;
var streamId = Guid.NewGuid();
theSession.LastModifiedBy = "Larry Bird";
// Just need a time that will be easy to assert on that is in the past
var timestamp = (DateTimeOffset)DateTime.Today.Subtract(1.Hours()).ToUniversalTime();
var action = theSession.Events.StartStream(streamId, new AEvent(), new BEvent(), new CEvent());
action.Events[0].UserName = "Kevin McHale";
await theSession.SaveChangesAsync();
using var query = theStore.QuerySession();
var events = await query.Events.FetchStreamAsync(streamId);
events[0].UserName.ShouldBe("Kevin McHale");
events[1].UserName.ShouldBe("Larry Bird");
events[2].UserName.ShouldBe("Larry Bird");
// Should write another test, but I'm doing it here!
var celtics = await query.Events.QueryAllRawEvents().Where(x => x.UserName == "Larry Bird").ToListAsync();
celtics.Count.ShouldBeGreaterThanOrEqualTo(2);
}
Summary
Projects like Marten are never, ever completed and we have no intentions of abandoning Marten anytime soon. The features above have been requested for quite awhile, but didn’t make the cut for Marten 8.0. I’m happy to see them hit now, and this could be the basis of a long waited formal support for efficient data imports to Marten from other event stores.
And of course, if there’s something that Marten or Wolverine doesn’t do today that you need, please reach out to JasperFx Software and we can talk about an engagement to build out your features.
The Shade Tree Developer 