Microsoft.Orleans.EventSourcing 9.2.0-preview3

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-preview3
                    


                    

                
NuGet\Install-Package Microsoft.Orleans.EventSourcing -Version 9.2.0-preview3
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-preview3" />
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-preview3" />
                    


                            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-preview3
                    


                    

                
#r "nuget: Microsoft.Orleans.EventSourcing, 9.2.0-preview3"
#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-preview3
#: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-preview3&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Microsoft.Orleans.EventSourcing&version=9.2.0-preview3&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
Orleans.Functional

Package Description

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 3,342 7/16/2025
9.2.0 666 7/14/2025
9.2.0-preview3 334 6/10/2025
9.2.0-preview2 175 6/4/2025
9.2.0-preview1 3,550 4/4/2025
9.1.2 42,602 2/13/2025
9.0.1 30,347 11/23/2024
9.0.0 3,423 11/14/2024
8.2.0 64,306 7/12/2024
8.2.0-preview1 209 5/22/2024
8.1.0 52,078 4/17/2024
8.1.0-preview3 337 3/11/2024
8.1.0-preview2 254 2/23/2024
8.1.0-preview1 302 2/13/2024
8.0.0 42,517 1/5/2024
8.0.0-rc2 499 12/20/2023
8.0.0-rc1 651 12/4/2023
7.2.7 187 10/15/2024
7.2.6 1,167 3/9/2024
7.2.5 586 2/22/2024
7.2.4 5,696 12/2/2023
7.2.3 3,157 11/3/2023
7.2.2 4,685 10/16/2023
7.2.1 14,070 7/11/2023
7.2.0 1,140 7/7/2023
7.1.2 8,300 4/19/2023
7.1.1 2,605 3/23/2023
7.1.0 8,652 2/1/2023
7.0.0 2,445 11/8/2022
7.0.0-rc2 790 10/19/2022
4.0.0-preview2 1,455 8/4/2022
4.0.0-preview1 3,408 2/10/2022
3.8.0 173 5/6/2025
3.8.0-preview5 225 5/12/2025
3.8.0-preview3 181 4/8/2025
3.8.0-preview2 123 4/4/2025
3.8.0-preview1 188 3/31/2025
3.7.2 3,564 5/10/2024
3.7.1 46,453 5/27/2023
3.7.0 14,949 3/23/2023
3.6.5 98,412 8/15/2022
3.6.4 12,491 8/10/2022
3.6.3 2,992 8/4/2022
3.6.2 26,847 4/15/2022
3.6.1 23,256 4/5/2022
3.6.0 25,633 1/20/2022
3.5.1 61,698 11/8/2021
3.5.0 56,209 9/3/2021
3.4.4 2,368 10/4/2021
3.4.3 31,821 6/3/2021
3.4.2 65,653 4/5/2021
3.4.1 25,942 2/3/2021
3.4.0 14,142 1/6/2021
3.4.0-rc1 1,033 12/9/2020
3.3.0 21,756 9/9/2020
3.3.0-rc2 1,078 9/2/2020
3.3.0-rc1 1,060 8/19/2020
3.2.2 6,875 7/22/2020
3.2.1 8,052 7/2/2020
3.2.0 4,783 6/4/2020
3.2.0-rc2 1,076 5/20/2020
3.2.0-rc1 1,121 5/7/2020
3.1.7 5,049 5/19/2020
3.1.6 47,504 4/16/2020
3.1.5 2,578 4/9/2020
3.1.4 2,091 3/26/2020
3.1.3 3,362 3/16/2020
3.1.2 3,720 3/5/2020
3.1.0 2,143 2/23/2020
3.1.0-rc3 1,113 2/13/2020
3.1.0-rc2 1,137 2/12/2020
3.1.0-rc1 1,161 2/10/2020
3.0.2 5,114 12/12/2019
3.0.1 3,677 11/27/2019
3.0.0 7,489 10/24/2019
3.0.0-rc2 1,121 10/16/2019
3.0.0-rc1 1,095 10/9/2019
3.0.0-beta1 1,307 8/16/2019
2.4.5 2,016 12/29/2019
2.4.4 1,482 11/27/2019
2.4.3 3,007 10/10/2019
2.4.2 10,524 8/31/2019
2.4.1 4,163 8/14/2019
2.4.0 1,983 8/8/2019
2.3.6 6,676 7/24/2019
2.3.5 24,816 6/14/2019
2.3.4 10,062 6/4/2019
2.3.3 1,768 6/2/2019
2.3.2 7,330 5/9/2019
2.3.1 8,292 4/26/2019
2.3.0 29,933 3/20/2019
2.3.0-rc2 1,189 3/13/2019
2.3.0-rc1 1,172 3/4/2019
2.2.4 3,015 2/25/2019
2.2.0 8,980 12/13/2018
2.2.0-rc1 1,275 12/4/2018
2.2.0-beta1 1,797 10/21/2018
2.1.2 4,406 10/11/2018
2.1.0 2,262 9/28/2018
2.1.0-rc2 1,632 9/21/2018
2.1.0-rc1 1,738 9/14/2018
2.1.0-beta1 1,778 8/27/2018
2.0.0 5,482 3/28/2018
2.0.0-rc2 1,648 3/13/2018
2.0.0-rc1 1,614 2/26/2018
2.0.0-beta3 2,453 12/21/2017
2.0.0-beta2 1,835 12/11/2017
2.0.0-beta1 1,711 10/26/2017
1.5.10 1,517 10/10/2019
1.5.9 1,407 9/1/2019
1.5.8 1,510 5/31/2019
1.5.7 1,494 2/28/2019
1.5.6 1,971 9/28/2018
1.5.5 1,871 9/8/2018
1.5.4 1,971 6/13/2018
1.5.3 2,454 12/9/2017
1.5.2 2,979 10/17/2017
1.5.1 2,334 8/28/2017
1.5.0 10,742 7/6/2017
1.5.0-rc 1,629 6/20/2017
1.5.0-beta1 1,646 4/29/2017
1.4.2 1,970 6/9/2017
1.4.1 2,428 3/27/2017
1.4.0 2,401 2/16/2017
1.4.0-beta 1,618 2/1/2017
1.3.1 2,140 11/11/2016
1.3.0 1,929 10/12/2016
1.3.0-beta2 1,839 9/24/2016
1.3.0-beta1 1,936 7/28/2016
1.2.4 1,933 10/5/2016
1.2.3 2,174 7/12/2016
1.2.2 2,020 6/14/2016
1.2.1 2,001 5/18/2016
1.2.0 1,910 5/2/2016
1.2.0-beta 1,773 4/19/2016
1.1.3 2,073 3/9/2016
1.1.2 2,113 1/20/2016
1.1.1 2,014 1/11/2016
1.1.0 2,410 12/14/2015
1.1.0-beta2 1,672 12/3/2015
1.1.0-beta1 1,656 11/3/2015