Microsoft.Orleans.EventSourcing 9.2.0

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
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
                    


                    

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


                            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
                    


                    

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


                            Install as a Cake Addin
                        

                    

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


                            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 (12)

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 179 7/16/2025
9.2.0 223 7/14/2025
9.2.0-preview3 327 6/10/2025
9.2.0-preview2 166 6/4/2025
9.2.0-preview1 3,421 4/4/2025
9.1.2 36,126 2/13/2025
9.0.1 27,840 11/23/2024
9.0.0 3,147 11/14/2024
8.2.0 63,717 7/12/2024
8.2.0-preview1 203 5/22/2024
8.1.0 51,729 4/17/2024
8.1.0-preview3 330 3/11/2024
8.1.0-preview2 249 2/23/2024
8.1.0-preview1 297 2/13/2024
8.0.0 42,296 1/5/2024
8.0.0-rc2 494 12/20/2023
8.0.0-rc1 647 12/4/2023
7.2.7 174 10/15/2024
7.2.6 1,162 3/9/2024
7.2.5 580 2/22/2024
7.2.4 5,690 12/2/2023
7.2.3 3,150 11/3/2023
7.2.2 4,676 10/16/2023
7.2.1 14,011 7/11/2023
7.2.0 1,127 7/7/2023
7.1.2 8,281 4/19/2023
7.1.1 2,591 3/23/2023
7.1.0 8,625 2/1/2023
7.0.0 2,417 11/8/2022
7.0.0-rc2 774 10/19/2022
4.0.0-preview2 1,439 8/4/2022
4.0.0-preview1 3,394 2/10/2022
3.8.0 165 5/6/2025
3.8.0-preview5 219 5/12/2025
3.8.0-preview3 176 4/8/2025
3.8.0-preview2 118 4/4/2025
3.8.0-preview1 181 3/31/2025
3.7.2 3,487 5/10/2024
3.7.1 45,862 5/27/2023
3.7.0 14,928 3/23/2023
3.6.5 95,612 8/15/2022
3.6.4 12,475 8/10/2022
3.6.3 2,978 8/4/2022
3.6.2 26,778 4/15/2022
3.6.1 23,033 4/5/2022
3.6.0 25,610 1/20/2022
3.5.1 61,561 11/8/2021
3.5.0 56,148 9/3/2021
3.4.4 2,351 10/4/2021
3.4.3 30,581 6/3/2021
3.4.2 63,515 4/5/2021
3.4.1 25,922 2/3/2021
3.4.0 14,120 1/6/2021
3.4.0-rc1 1,015 12/9/2020
3.3.0 21,733 9/9/2020
3.3.0-rc2 1,060 9/2/2020
3.3.0-rc1 1,043 8/19/2020
3.2.2 6,858 7/22/2020
3.2.1 8,033 7/2/2020
3.2.0 4,765 6/4/2020
3.2.0-rc2 1,058 5/20/2020
3.2.0-rc1 1,102 5/7/2020
3.1.7 5,030 5/19/2020
3.1.6 47,485 4/16/2020
3.1.5 2,563 4/9/2020
3.1.4 2,075 3/26/2020
3.1.3 3,345 3/16/2020
3.1.2 3,705 3/5/2020
3.1.0 2,127 2/23/2020
3.1.0-rc3 1,098 2/13/2020
3.1.0-rc2 1,121 2/12/2020
3.1.0-rc1 1,146 2/10/2020
3.0.2 5,058 12/12/2019
3.0.1 3,662 11/27/2019
3.0.0 7,471 10/24/2019
3.0.0-rc2 1,105 10/16/2019
3.0.0-rc1 1,080 10/9/2019
3.0.0-beta1 1,291 8/16/2019
2.4.5 1,999 12/29/2019
2.4.4 1,465 11/27/2019
2.4.3 2,990 10/10/2019
2.4.2 10,506 8/31/2019
2.4.1 4,147 8/14/2019
2.4.0 1,966 8/8/2019
2.3.6 6,660 7/24/2019
2.3.5 24,795 6/14/2019
2.3.4 10,045 6/4/2019
2.3.3 1,752 6/2/2019
2.3.2 7,315 5/9/2019
2.3.1 8,276 4/26/2019
2.3.0 29,900 3/20/2019
2.3.0-rc2 1,174 3/13/2019
2.3.0-rc1 1,156 3/4/2019
2.2.4 3,000 2/25/2019
2.2.0 8,963 12/13/2018
2.2.0-rc1 1,260 12/4/2018
2.2.0-beta1 1,780 10/21/2018
2.1.2 4,389 10/11/2018
2.1.0 2,236 9/28/2018
2.1.0-rc2 1,606 9/21/2018
2.1.0-rc1 1,712 9/14/2018
2.1.0-beta1 1,750 8/27/2018
2.0.0 5,445 3/28/2018
2.0.0-rc2 1,620 3/13/2018
2.0.0-rc1 1,588 2/26/2018
2.0.0-beta3 2,415 12/21/2017
2.0.0-beta2 1,797 12/11/2017
2.0.0-beta1 1,682 10/26/2017
1.5.10 1,501 10/10/2019
1.5.9 1,391 9/1/2019
1.5.8 1,494 5/31/2019
1.5.7 1,478 2/28/2019
1.5.6 1,944 9/28/2018
1.5.5 1,846 9/8/2018
1.5.4 1,944 6/13/2018
1.5.3 2,420 12/9/2017
1.5.2 2,951 10/17/2017
1.5.1 2,297 8/28/2017
1.5.0 10,714 7/6/2017
1.5.0-rc 1,602 6/20/2017
1.5.0-beta1 1,620 4/29/2017
1.4.2 1,940 6/9/2017
1.4.1 2,377 3/27/2017
1.4.0 2,373 2/16/2017
1.4.0-beta 1,591 2/1/2017
1.3.1 2,111 11/11/2016
1.3.0 1,894 10/12/2016
1.3.0-beta2 1,811 9/24/2016
1.3.0-beta1 1,907 7/28/2016
1.2.4 1,905 10/5/2016
1.2.3 2,146 7/12/2016
1.2.2 1,992 6/14/2016
1.2.1 1,972 5/18/2016
1.2.0 1,883 5/2/2016
1.2.0-beta 1,745 4/19/2016
1.1.3 2,042 3/9/2016
1.1.2 2,082 1/20/2016
1.1.1 1,982 1/11/2016
1.1.0 2,365 12/14/2015
1.1.0-beta2 1,643 12/3/2015
1.1.0-beta1 1,628 11/3/2015