Microsoft.Orleans.EventSourcing 9.2.0-preview2

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of Microsoft.Orleans.EventSourcing.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Microsoft.Orleans.EventSourcing --version 9.2.0-preview2
                    


                    

                
NuGet\Install-Package Microsoft.Orleans.EventSourcing -Version 9.2.0-preview2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Microsoft.Orleans.EventSourcing" Version="9.2.0-preview2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Microsoft.Orleans.EventSourcing" Version="9.2.0-preview2" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Microsoft.Orleans.EventSourcing" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Microsoft.Orleans.EventSourcing --version 9.2.0-preview2
                    


                    

                
#r "nuget: Microsoft.Orleans.EventSourcing, 9.2.0-preview2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Microsoft.Orleans.EventSourcing@9.2.0-preview2
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Microsoft.Orleans.EventSourcing&version=9.2.0-preview2&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Microsoft.Orleans.EventSourcing&version=9.2.0-preview2&prerelease
                    


                            Install as a Cake Tool

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;
        }
    }
}

Example - Configuring Event Sourcing with Storage

using Microsoft.Extensions.Hosting;
using Orleans.Configuration;
using Orleans.Hosting;
using Orleans.EventSourcing;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Threading.Tasks;

var builder = Host.CreateApplicationBuilder(args)
    .UseOrleans(siloBuilder =>
    {
        siloBuilder
            .UseLocalhostClustering()
            // Configure the log consistency provider for event sourcing
            .AddLogStorageBasedLogConsistencyProvider("LogStorage")
            // Configure a storage provider to store the events
            .AddMemoryGrainStorage("PubSubStore")
            .ConfigureServices(services =>
            {
                // Configure default log consistency provider
                services.Configure<JournaledGrainOptions>(options =>
                {
                    options.DefaultLogConsistencyProvider = "LogStorage";
                });
            });
    });

var host = builder.Build();
await host.StartAsync();

// Get a reference to a grain and call it
var client = host.Services.GetRequiredService<IClusterClient>();
var bankAccount = client.GetGrain<IBankAccountGrain>("account-123");

// Call grain methods
await bankAccount.Deposit(100);
await bankAccount.Withdraw(25);
var balance = await bankAccount.GetBalance();

// Print the result
Console.WriteLine($"Account balance: ${balance}");

var history = await bankAccount.GetHistory();
Console.WriteLine($"Transaction history: {history.Count} events");

// Keep the host running until the application is shut down
await host.WaitForShutdownAsync();

Documentation

For more comprehensive documentation, please refer to:

Feedback & Contributing

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (13)

Showing the top 5 NuGet packages that depend on Microsoft.Orleans.EventSourcing:

Package Downloads
Mtl.Autumn

利用Orleans简单封装的基于RabitMQ的CQRS框架(还未完善)
ZLSoft.QWPlatform.WebBasics

基础服务
iTool.ClusterComponent

为NetCore提供 In Process 可靠的/高速的 缓存、队列等常用分布式组件。 无第三方依赖的开发友好、运维友好型框架
Orleans.EventSourcing.Snapshot

Snapshot storage provider for orleans event sourcing
Fuxion.Orleans

Fuxion infrastructure for Orleans frameowrk

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Microsoft.Orleans.EventSourcing:

Repository Stars
axzxs2001/Asp.NetCoreExperiment
原来所有项目都移动到**OleVersion**目录下进行保留。新的案例装以.net 5.0为主，一部分对以前案例进行升级，一部分将以前的工作经验总结出来，以供大家参考！
Version Downloads Last Updated
9.2.1 5,130 7/16/2025
9.2.0 952 7/14/2025
9.2.0-preview3 337 6/10/2025
9.2.0-preview2 178 6/4/2025
9.2.0-preview1 3,553 4/4/2025
9.1.2 47,722 2/13/2025
9.0.1 32,556 11/23/2024
9.0.0 3,644 11/14/2024
8.2.0 64,792 7/12/2024
8.2.0-preview1 210 5/22/2024
8.1.0 52,485 4/17/2024
8.1.0-preview3 346 3/11/2024
8.1.0-preview2 257 2/23/2024
8.1.0-preview1 303 2/13/2024
8.0.0 42,892 1/5/2024
8.0.0-rc2 501 12/20/2023
8.0.0-rc1 653 12/4/2023
7.2.7 197 10/15/2024
7.2.6 1,175 3/9/2024
7.2.5 594 2/22/2024
7.2.4 5,704 12/2/2023
7.2.3 3,163 11/3/2023
7.2.2 4,687 10/16/2023
7.2.1 14,117 7/11/2023
7.2.0 1,148 7/7/2023
7.1.2 8,306 4/19/2023
7.1.1 2,611 3/23/2023
7.1.0 8,669 2/1/2023
7.0.0 2,454 11/8/2022
7.0.0-rc2 798 10/19/2022
4.0.0-preview2 1,462 8/4/2022
4.0.0-preview1 3,414 2/10/2022
3.8.0 179 5/6/2025
3.8.0-preview5 231 5/12/2025
3.8.0-preview3 182 4/8/2025
3.8.0-preview2 125 4/4/2025
3.8.0-preview1 193 3/31/2025
3.7.2 3,608 5/10/2024
3.7.1 46,798 5/27/2023
3.7.0 14,959 3/23/2023
3.6.5 99,774 8/15/2022
3.6.4 12,501 8/10/2022
3.6.3 3,001 8/4/2022
3.6.2 26,877 4/15/2022
3.6.1 23,336 4/5/2022
3.6.0 25,651 1/20/2022
3.5.1 61,831 11/8/2021
3.5.0 56,284 9/3/2021
3.4.4 2,378 10/4/2021
3.4.3 32,793 6/3/2021
3.4.2 67,990 4/5/2021
3.4.1 25,950 2/3/2021
3.4.0 14,166 1/6/2021
3.4.0-rc1 1,041 12/9/2020
3.3.0 21,772 9/9/2020
3.3.0-rc2 1,090 9/2/2020
3.3.0-rc1 1,069 8/19/2020
3.2.2 6,884 7/22/2020
3.2.1 8,061 7/2/2020
3.2.0 4,793 6/4/2020
3.2.0-rc2 1,089 5/20/2020
3.2.0-rc1 1,130 5/7/2020
3.1.7 5,058 5/19/2020
3.1.6 47,512 4/16/2020
3.1.5 2,593 4/9/2020
3.1.4 2,102 3/26/2020
3.1.3 3,372 3/16/2020
3.1.2 3,730 3/5/2020
3.1.0 2,151 2/23/2020
3.1.0-rc3 1,123 2/13/2020
3.1.0-rc2 1,147 2/12/2020
3.1.0-rc1 1,169 2/10/2020
3.0.2 5,146 12/12/2019
3.0.1 3,686 11/27/2019
3.0.0 7,504 10/24/2019
3.0.0-rc2 1,130 10/16/2019
3.0.0-rc1 1,105 10/9/2019
3.0.0-beta1 1,321 8/16/2019
2.4.5 2,024 12/29/2019
2.4.4 1,490 11/27/2019
2.4.3 3,019 10/10/2019
2.4.2 10,546 8/31/2019
2.4.1 4,171 8/14/2019
2.4.0 1,991 8/8/2019
2.3.6 6,684 7/24/2019
2.3.5 24,835 6/14/2019
2.3.4 10,075 6/4/2019
2.3.3 1,776 6/2/2019
2.3.2 7,344 5/9/2019
2.3.1 8,305 4/26/2019
2.3.0 29,953 3/20/2019
2.3.0-rc2 1,199 3/13/2019
2.3.0-rc1 1,184 3/4/2019
2.2.4 3,027 2/25/2019
2.2.0 8,997 12/13/2018
2.2.0-rc1 1,289 12/4/2018
2.2.0-beta1 1,810 10/21/2018
2.1.2 4,424 10/11/2018
2.1.0 2,279 9/28/2018
2.1.0-rc2 1,648 9/21/2018
2.1.0-rc1 1,757 9/14/2018
2.1.0-beta1 1,797 8/27/2018
2.0.0 5,510 3/28/2018
2.0.0-rc2 1,666 3/13/2018
2.0.0-rc1 1,632 2/26/2018
2.0.0-beta3 2,481 12/21/2017
2.0.0-beta2 1,864 12/11/2017
2.0.0-beta1 1,736 10/26/2017
1.5.10 1,525 10/10/2019
1.5.9 1,416 9/1/2019
1.5.8 1,522 5/31/2019
1.5.7 1,502 2/28/2019
1.5.6 1,990 9/28/2018
1.5.5 1,888 9/8/2018
1.5.4 1,990 6/13/2018
1.5.3 2,482 12/9/2017
1.5.2 2,997 10/17/2017
1.5.1 2,362 8/28/2017
1.5.0 10,761 7/6/2017
1.5.0-rc 1,647 6/20/2017
1.5.0-beta1 1,671 4/29/2017
1.4.2 1,993 6/9/2017
1.4.1 2,468 3/27/2017
1.4.0 2,422 2/16/2017
1.4.0-beta 1,641 2/1/2017
1.3.1 2,164 11/11/2016
1.3.0 1,950 10/12/2016
1.3.0-beta2 1,861 9/24/2016
1.3.0-beta1 1,959 7/28/2016
1.2.4 1,952 10/5/2016
1.2.3 2,195 7/12/2016
1.2.2 2,042 6/14/2016
1.2.1 2,020 5/18/2016
1.2.0 1,930 5/2/2016
1.2.0-beta 1,794 4/19/2016
1.1.3 2,095 3/9/2016
1.1.2 2,133 1/20/2016
1.1.1 2,033 1/11/2016
1.1.0 2,433 12/14/2015
1.1.0-beta2 1,698 12/3/2015
1.1.0-beta1 1,675 11/3/2015