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
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 7,575 7/16/2025
9.2.0 1,412 7/14/2025
9.2.0-preview3 354 6/10/2025
9.2.0-preview2 192 6/4/2025
9.2.0-preview1 3,568 4/4/2025
9.1.2 51,874 2/13/2025
9.0.1 33,858 11/23/2024
9.0.0 3,923 11/14/2024
8.2.0 65,343 7/12/2024
8.2.0-preview1 220 5/22/2024
8.1.0 52,841 4/17/2024
8.1.0-preview3 360 3/11/2024
8.1.0-preview2 270 2/23/2024
8.1.0-preview1 315 2/13/2024
8.0.0 43,192 1/5/2024
8.0.0-rc2 520 12/20/2023
8.0.0-rc1 666 12/4/2023
7.2.7 217 10/15/2024
7.2.6 1,210 3/9/2024
7.2.5 612 2/22/2024
7.2.4 5,724 12/2/2023
7.2.3 3,176 11/3/2023
7.2.2 4,699 10/16/2023
7.2.1 14,190 7/11/2023
7.2.0 1,166 7/7/2023
7.1.2 8,322 4/19/2023
7.1.1 2,625 3/23/2023
7.1.0 8,702 2/1/2023
7.0.0 2,470 11/8/2022
7.0.0-rc2 818 10/19/2022
4.0.0-preview2 1,482 8/4/2022
4.0.0-preview1 3,430 2/10/2022
3.8.0 199 5/6/2025
3.8.0-preview5 246 5/12/2025
3.8.0-preview3 192 4/8/2025
3.8.0-preview2 136 4/4/2025
3.8.0-preview1 204 3/31/2025
3.7.2 3,671 5/10/2024
3.7.1 47,255 5/27/2023
3.7.0 14,981 3/23/2023
3.6.5 101,693 8/15/2022
3.6.4 12,520 8/10/2022
3.6.3 3,019 8/4/2022
3.6.2 26,894 4/15/2022
3.6.1 23,409 4/5/2022
3.6.0 25,675 1/20/2022
3.5.1 62,005 11/8/2021
3.5.0 56,486 9/3/2021
3.4.4 2,389 10/4/2021
3.4.3 33,357 6/3/2021
3.4.2 69,524 4/5/2021
3.4.1 25,965 2/3/2021
3.4.0 14,216 1/6/2021
3.4.0-rc1 1,054 12/9/2020
3.3.0 21,793 9/9/2020
3.3.0-rc2 1,109 9/2/2020
3.3.0-rc1 1,095 8/19/2020
3.2.2 6,908 7/22/2020
3.2.1 8,084 7/2/2020
3.2.0 4,812 6/4/2020
3.2.0-rc2 1,110 5/20/2020
3.2.0-rc1 1,149 5/7/2020
3.1.7 5,072 5/19/2020
3.1.6 47,994 4/16/2020
3.1.5 2,610 4/9/2020
3.1.4 2,121 3/26/2020
3.1.3 3,391 3/16/2020
3.1.2 3,746 3/5/2020
3.1.0 2,165 2/23/2020
3.1.0-rc3 1,148 2/13/2020
3.1.0-rc2 1,168 2/12/2020
3.1.0-rc1 1,184 2/10/2020
3.0.2 5,183 12/12/2019
3.0.1 3,701 11/27/2019
3.0.0 7,578 10/24/2019
3.0.0-rc2 1,134 10/16/2019
3.0.0-rc1 1,119 10/9/2019
3.0.0-beta1 1,337 8/16/2019
2.4.5 2,037 12/29/2019
2.4.4 1,504 11/27/2019
2.4.3 3,027 10/10/2019
2.4.2 10,605 8/31/2019
2.4.1 4,186 8/14/2019
2.4.0 1,997 8/8/2019
2.3.6 6,707 7/24/2019
2.3.5 24,861 6/14/2019
2.3.4 10,091 6/4/2019
2.3.3 1,797 6/2/2019
2.3.2 7,358 5/9/2019
2.3.1 8,333 4/26/2019
2.3.0 29,980 3/20/2019
2.3.0-rc2 1,216 3/13/2019
2.3.0-rc1 1,201 3/4/2019
2.2.4 3,033 2/25/2019
2.2.0 9,019 12/13/2018
2.2.0-rc1 1,306 12/4/2018
2.2.0-beta1 1,829 10/21/2018
2.1.2 4,443 10/11/2018
2.1.0 2,285 9/28/2018
2.1.0-rc2 1,672 9/21/2018
2.1.0-rc1 1,766 9/14/2018
2.1.0-beta1 1,824 8/27/2018
2.0.0 5,540 3/28/2018
2.0.0-rc2 1,684 3/13/2018
2.0.0-rc1 1,658 2/26/2018
2.0.0-beta3 2,499 12/21/2017
2.0.0-beta2 1,884 12/11/2017
2.0.0-beta1 1,753 10/26/2017
1.5.10 1,549 10/10/2019
1.5.9 1,430 9/1/2019
1.5.8 1,550 5/31/2019
1.5.7 1,516 2/28/2019
1.5.6 2,011 9/28/2018
1.5.5 1,906 9/8/2018
1.5.4 2,011 6/13/2018
1.5.3 2,501 12/9/2017
1.5.2 3,013 10/17/2017
1.5.1 2,387 8/28/2017
1.5.0 10,777 7/6/2017
1.5.0-rc 1,653 6/20/2017
1.5.0-beta1 1,690 4/29/2017
1.4.2 2,017 6/9/2017
1.4.1 2,486 3/27/2017
1.4.0 2,430 2/16/2017
1.4.0-beta 1,660 2/1/2017
1.3.1 2,183 11/11/2016
1.3.0 1,967 10/12/2016
1.3.0-beta2 1,882 9/24/2016
1.3.0-beta1 1,977 7/28/2016
1.2.4 1,968 10/5/2016
1.2.3 2,213 7/12/2016
1.2.2 2,062 6/14/2016
1.2.1 2,037 5/18/2016
1.2.0 1,945 5/2/2016
1.2.0-beta 1,813 4/19/2016
1.1.3 2,112 3/9/2016
1.1.2 2,152 1/20/2016
1.1.1 2,048 1/11/2016
1.1.0 2,453 12/14/2015
1.1.0-beta2 1,714 12/3/2015
1.1.0-beta1 1,692 11/3/2015