Base types for creating Microsoft Orleans grains with event-sourced state.
Get Started
$ dotnet add package Microsoft.Orleans.EventSourcingReadme
Microsoft Orleans Event Sourcing
Introduction
Microsoft Orleans Event Sourcing provides support for implementing event-sourced grains. Event sourcing is a pattern where state changes are recorded as a sequence of events rather than just storing the current state. This provides a complete history of changes and allows for powerful capabilities like replaying events, temporal querying, and more robust auditing.
Getting Started
To use this package, install it via NuGet:
dotnet add package Microsoft.Orleans.EventSourcing
Example - Creating an Event-Sourced Grain
using Orleans;
using Orleans.EventSourcing;
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Linq;
// Define grain state and events
namespace BankAccount;
public class BankAccountState
{
public decimal Balance { get; set; }
public string AccountHolder { get; set; }
public int Version { get; set; }
}
public class DepositEvent
{
public decimal Amount { get; set; }
}
public class WithdrawalEvent
{
public decimal Amount { get; set; }
}
// Grain interface
public interface IBankAccountGrain : IGrainWithStringKey
{
Task<decimal> GetBalance();
Task Deposit(decimal amount);
Task Withdraw(decimal amount);
Task<IReadOnlyList<object>> GetHistory();
}
// Event-sourced grain implementation using JournaledGrain
public class BankAccountGrain : JournaledGrain<BankAccountState, object>, IBankAccountGrain
{
public async Task<decimal> GetBalance()
{
// The state is automatically hydrated from the event log
return State.Balance;
}
public async Task Deposit(decimal amount)
{
if (amount <= 0)
throw new ArgumentException("Deposit amount must be positive");
// Record the event - this will be persisted and applied to state
RaiseEvent(new DepositEvent { Amount = amount });
// Confirm the event is persisted
await ConfirmEvents();
}
public async Task Withdraw(decimal amount)
{
if (amount <= 0)
throw new ArgumentException("Withdrawal amount must be positive");
if (State.Balance < amount)
throw new InvalidOperationException("Insufficient funds");
// Record the event
RaiseEvent(new WithdrawalEvent { Amount = amount });
// Confirm the event is persisted
await ConfirmEvents();
}
public Task<IReadOnlyList<object>> GetHistory()
{
// Return the complete history of events
return Task.FromResult<IReadOnlyList<object>>(RetrieveConfirmedEvents(0, Version).ToList());
}
// Event handlers to update the state based on events
protected override void ApplyEvent(object @event)
{
switch (@event)
{
case DepositEvent deposit:
State.Balance += deposit.Amount;
break;
case WithdrawalEvent withdrawal:
State.Balance -= withdrawal.Amount;
break;
}
}
}