Microsoft.Orleans.EventSourcing 9.2.1

Prefix Reserved

dotnet add package Microsoft.Orleans.EventSourcing --version 9.2.1

NuGet\Install-Package Microsoft.Orleans.EventSourcing -Version 9.2.1

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.1" />

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.1" />
                    

                            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.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Microsoft.Orleans.EventSourcing, 9.2.1"

#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.1

#: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.1
                    

                            Install as a Cake Addin

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

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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

If you have any issues or would like to provide feedback, please open an issue on GitHub
Join our community on Discord
Follow the @msftorleans Twitter account for Orleans announcements
Contributions are welcome! Please review our contribution guidelines
This project is licensed under the MIT license

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.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- Microsoft.AspNetCore.Connections.Abstractions (>= 8.0.11)
- Microsoft.CodeAnalysis.Analyzers (>= 3.11.0)
- Microsoft.CodeAnalysis.Common (>= 4.5.0)
- Microsoft.CodeAnalysis.Workspaces.Common (>= 4.5.0)
- Microsoft.Extensions.Configuration (>= 8.0.0)
- Microsoft.Extensions.Configuration.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 8.0.2)
- Microsoft.Extensions.Configuration.Json (>= 8.0.1)
- Microsoft.Extensions.DependencyInjection (>= 8.0.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.DependencyModel (>= 8.0.2)
- Microsoft.Extensions.Hosting (>= 8.0.1)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Logging (>= 8.0.1)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.3)
- Microsoft.Extensions.Logging.Console (>= 8.0.1)
- Microsoft.Extensions.Logging.Debug (>= 8.0.1)
- Microsoft.Extensions.ObjectPool (>= 8.0.11)
- Microsoft.Extensions.Options (>= 8.0.2)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 8.0.0)
- Microsoft.Orleans.Analyzers (>= 9.2.1)
- Microsoft.Orleans.CodeGenerator (>= 9.2.1)
- Microsoft.Orleans.Runtime (>= 9.2.1)
- Newtonsoft.Json (>= 13.0.3)
- System.Collections.Immutable (>= 8.0.0)
- System.IO.Hashing (>= 8.0.0)
- System.IO.Pipelines (>= 8.0.0)
- System.Memory.Data (>= 8.0.1)

NuGet packages (14)

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

Package	Downloads
Mtl.Autumn 利用Orleans简单封装的基于RabitMQ的CQRS框架(还未完善)	148.3K
ZLSoft.QWPlatform.WebBasics 基础服务	91.8K
iTool.ClusterComponent 为NetCore提供 In Process 可靠的/高速的缓存、队列等常用分布式组件。无第三方依赖的开发友好、运维友好型框架	23.9K
Orleans.EventSourcing.Snapshot Snapshot storage provider for orleans event sourcing	15.6K
Fuxion.Orleans Fuxion infrastructure for Orleans frameowrk	13.8K

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为主，一部分对以前案例进行升级，一部分将以前的工作经验总结出来，以供大家参考！	361

Version	Downloads	Last Updated
9.2.1	13,846	7/16/2025
9.2.0	2,301	7/14/2025
9.2.0-preview3	381	6/10/2025
9.2.0-preview2	217	6/4/2025
9.2.0-preview1	3,594	4/4/2025
9.1.2	60,375	2/13/2025
9.0.1	35,590	11/23/2024
9.0.0	4,490	11/14/2024
8.2.0	66,305	7/12/2024
8.2.0-preview1	237	5/22/2024
8.1.0	53,462	4/17/2024
8.1.0-preview3	379	3/11/2024
8.1.0-preview2	292	2/23/2024
8.1.0-preview1	328	2/13/2024
8.0.0	43,808	1/5/2024
8.0.0-rc2	540	12/20/2023
8.0.0-rc1	680	12/4/2023
7.2.7	241	10/15/2024
7.2.6	1,268	3/9/2024
7.2.5	631	2/22/2024
7.2.4	5,747	12/2/2023
7.2.3	3,296	11/3/2023
7.2.2	4,718	10/16/2023
7.2.1	14,349	7/11/2023
7.2.0	1,186	7/7/2023
7.1.2	8,394	4/19/2023
7.1.1	2,661	3/23/2023
7.1.0	8,804	2/1/2023
7.0.0	2,496	11/8/2022
7.0.0-rc2	850	10/19/2022
4.0.0-preview2	1,512	8/4/2022
4.0.0-preview1	3,456	2/10/2022
3.8.0	220	5/6/2025
3.8.0-preview5	271	5/12/2025
3.8.0-preview3	207	4/8/2025
3.8.0-preview2	157	4/4/2025
3.8.0-preview1	244	3/31/2025
3.7.2	3,876	5/10/2024
3.7.1	48,391	5/27/2023
3.7.0	15,013	3/23/2023
3.6.5	105,562	8/15/2022
3.6.4	12,547	8/10/2022
3.6.3	3,043	8/4/2022
3.6.2	26,987	4/15/2022
3.6.1	23,575	4/5/2022
3.6.0	25,708	1/20/2022
3.5.1	62,957	11/8/2021
3.5.0	56,756	9/3/2021
3.4.4	2,436	10/4/2021
3.4.3	34,883	6/3/2021
3.4.2	72,109	4/5/2021
3.4.1	25,988	2/3/2021
3.4.0	14,266	1/6/2021
3.4.0-rc1	1,090	12/9/2020
3.3.0	21,839	9/9/2020
3.3.0-rc2	1,140	9/2/2020
3.3.0-rc1	1,142	8/19/2020
3.2.2	6,949	7/22/2020
3.2.1	8,165	7/2/2020
3.2.0	4,844	6/4/2020
3.2.0-rc2	1,164	5/20/2020
3.2.0-rc1	1,187	5/7/2020
3.1.7	5,097	5/19/2020
3.1.6	48,799	4/16/2020
3.1.5	2,646	4/9/2020
3.1.4	2,177	3/26/2020
3.1.3	3,431	3/16/2020
3.1.2	3,776	3/5/2020
3.1.0	2,193	2/23/2020
3.1.0-rc3	1,191	2/13/2020
3.1.0-rc2	1,230	2/12/2020
3.1.0-rc1	1,219	2/10/2020
3.0.2	5,239	12/12/2019
3.0.1	3,901	11/27/2019
3.0.0	7,815	10/24/2019
3.0.0-rc2	1,177	10/16/2019
3.0.0-rc1	1,148	10/9/2019
3.0.0-beta1	1,374	8/16/2019
2.4.5	2,092	12/29/2019
2.4.4	1,563	11/27/2019
2.4.3	3,074	10/10/2019
2.4.2	10,961	8/31/2019
2.4.1	4,350	8/14/2019
2.4.0	2,075	8/8/2019
2.3.6	7,235	7/24/2019
2.3.5	25,726	6/14/2019
2.3.4	10,965	6/4/2019
2.3.3	1,854	6/2/2019
2.3.2	7,792	5/9/2019
2.3.1	9,016	4/26/2019
2.3.0	33,232	3/20/2019
2.3.0-rc2	1,281	3/13/2019
2.3.0-rc1	1,270	3/4/2019
2.2.4	3,091	2/25/2019
2.2.0	9,112	12/13/2018
2.2.0-rc1	1,357	12/4/2018
2.2.0-beta1	1,873	10/21/2018
2.1.2	4,498	10/11/2018
2.1.0	2,334	9/28/2018
2.1.0-rc2	1,744	9/21/2018
2.1.0-rc1	1,837	9/14/2018
2.1.0-beta1	1,880	8/27/2018
2.0.0	5,626	3/28/2018
2.0.0-rc2	1,743	3/13/2018
2.0.0-rc1	1,718	2/26/2018
2.0.0-beta3	2,558	12/21/2017
2.0.0-beta2	1,978	12/11/2017
2.0.0-beta1	1,808	10/26/2017
1.5.10	1,577	10/10/2019
1.5.9	1,477	9/1/2019
1.5.8	1,616	5/31/2019
1.5.7	1,541	2/28/2019
1.5.6	2,068	9/28/2018
1.5.5	1,944	9/8/2018
1.5.4	2,077	6/13/2018
1.5.3	2,553	12/9/2017
1.5.2	3,053	10/17/2017
1.5.1	2,472	8/28/2017
1.5.0	10,824	7/6/2017
1.5.0-rc	1,703	6/20/2017
1.5.0-beta1	1,737	4/29/2017
1.4.2	2,067	6/9/2017
1.4.1	2,548	3/27/2017
1.4.0	2,482	2/16/2017
1.4.0-beta	1,718	2/1/2017
1.3.1	2,233	11/11/2016
1.3.0	2,019	10/12/2016
1.3.0-beta2	1,933	9/24/2016
1.3.0-beta1	2,025	7/28/2016
1.2.4	2,018	10/5/2016
1.2.3	2,264	7/12/2016
1.2.2	2,108	6/14/2016
1.2.1	2,079	5/18/2016
1.2.0	1,996	5/2/2016
1.2.0-beta	1,860	4/19/2016
1.1.3	2,160	3/9/2016
1.1.2	2,197	1/20/2016
1.1.1	2,090	1/11/2016
1.1.0	2,505	12/14/2015
1.1.0-beta2	1,764	12/3/2015
1.1.0-beta1	1,733	11/3/2015