NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet, #2397 most downloaded on NuGet
Library of built-in persistence and stream providers included in Microsoft Orleans.
Latest stable
3.8.1
Last release 6 months ago
24 Apr 2026
Release timing varies
gaps range from 1 weeks to 12 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
127 years old
119 releases · first in 1900
Drag across the ruler to compare, or tap a release to open it.
Refactored stream batch behaviors to support batch consumption. (#5425) technically a breaking change due to the changes to the batch streaming API. H…
IHostEnvironmentStatistics on Linux, which enables CPU and memory metrics as well as load shedding. Thanks to @martinothamar!This release is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
Three new NuGet packages were added:
Breaking changes
Refactored stream batch behaviors to support batch consumption. (#5425) technically a breaking change due to the changes to the batch streaming API. However, it shouldn't break any working application code because the batching functionality wasn't fully wired previously.
This release is backward-compatible with 2.x releases.Non-breaking improvements
LoadShedding. (#5387)Non-breaking bug fixes
Your coding agent can read these notes before it upgrades. Set up the MCP server →
…functionality wasn't fully wired previously. No breaking change in the wire protocol or persistence. This release is backward-compatible with 2.x rele…
Changes since 2.3.0-rc1.
Refactored stream batch behaviors to support batch consumption. (#5425) is the only change. While technically it is breaking due to the changes to the batch streaming API, it shouldn't break any working application code because the batching functionality wasn't fully wired previously. No breaking change in the wire protocol or persistence. This release is backward-compatible with 2.x releases.
Support for the ASP.NET Core hosting API (Microsoft.Extensions.Hosting).
Major improvements
Breaking changes
Non-breaking improvements
LoadShedding. (#5387)Non-breaking bug fixes
Improvements and bug fixes since 2.2.3.
Improvements and bug fixes since 2.2.3.
Non-breaking improvements
LoadShedding. (#5387)Non-breaking bug fixes
Updated packages: all but Microsoft.Orleans.Core.Abstractions.
Improvements and bug fixes since 2.2.2. The most important ones are in silo shutdown sequence (#5268 and #5276). Server side, code generation, and som
Improvements and bug fixes since 2.2.2. The most important ones are in silo shutdown sequence (#5268 and #5276). Server side, code generation, and some extension packages have been updated. Core and client stayed unchanged.
Non-breaking improvements
Non-breaking bug fixes
Updated packages:
This release includes no breaking changes and is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
This release is primarily about bringing support for ACID cross-grain transactions to production-ready quality. Other improvements and fixes are listed below.
This release includes no breaking changes and is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
Warning: If you are using Orleans with .NET Core 2.1, do not enable TieredCompilation for Orleans silo and client projects. We recently discovered a CLR bug that is breaking Orleans when TieredCompilation is enabled. See #4990 for more details.
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Major performance (up to 4x) and stability improvements in transactions compared to 2.2.0-beta1.
Major performance (up to 4x) and stability improvements in transactions compared to 2.2.0-beta1.
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Avoid lazy initialization when disposing OutboundMessageQueue
Changes since v2.1.0.
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.1.1.
Improvements and bug fixes since 2.1.1.
This release includes no breaking changes and is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
This release includes a number of performance improvements, the biggest one being the new scheduler, that all add up in our tests to up to 30% throughput increase on the same hardware.
It also brings the support for distributed transaction to what we consider "release candidate" quality, with the new Distributed Transaction Manager at its core. We plan to declare transactions production ready in a subsequent release, after another round of testing and improvements.
Lastly, this release includes a new code generation package Microsoft.Orleans.CodeGenerator.MSBuild that can be used as an alternative to Microsoft.Orleans.OrleansCodeGenerator.Build. The new code generator leverages Roslyn Code Analysis functionality to avoid loading application binaries. As a result, it avoid issues caused by clashing dependency versions and multiple versions of the .NET Core SDK.
This release includes no breaking changes and is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
Warning: If you are using Orleans with .NET Core 2.1, do not enable TieredCompilation for Orleans silo and client projects. We recently discovered a CLR bug that is breaking Orleans when TieredCompilation is enabled. See #4990 for more details.
Major changes
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Warning: If you are using Orleans with .NET Core 2.1, *do not enable* TieredCompilation for Orleans silo and client projects. We recently discovered a
Warning: If you are using Orleans with .NET Core 2.1, do not enable TieredCompilation for Orleans silo and client projects. We recently discovered a CLR bug that is breaking Orleans when TieredCompilation is enabled. See #4990 for more details.
Major changes
Microsoft.Orleans.CodeGenerator.MSBuild NuGet package can be used instead of Microsoft.Orleans.OrleansCodeGenerator.Build. We plan to eventually retire Microsoft.Orleans.OrleansCodeGenerator.Build.Breaking changes
Non-breaking bug fixes
Transactions (beta2) (#4851, #4923, #4951, #4950, #4953)
Major changes
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Distributed Transaction Manager (beta) (#3820, #4502, #4538, #4566, #4568, #4591, #4599, #4613, #4609, #4616, #4608, #4628, #4638, #4685, #4714, #4739
Major changes
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
All included providers obtain ServiceId and ClusterId from the global ClusterOptions and do not have those properties on their own options classes (#4
Major changes
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Know Issue If you are using the ADO.NET provider for reminders, there is a bug in the configuration extension method UseAdoNetReminderService that pre
UseAdoNetReminderService that prevents it from working properly. The workaround is to explicitly configure the settings as in the following example:.UseAdoNetReminderService((AdoNetReminderTableOptions options) => { })
.Configure<AdoNetReminderTableOptions>(options =>
{
options.ConnectionString = ConnectionString;
options.Invariant = "System.Data.SqlClient";
})
Major changes (since 2.0.0-rc1)
Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Add startup tasks to replace deprecated bootstrap providers
Major changes (since 2.0.0-beta3)
Known issues
OrleansProviders.dll is added and inspected for grain types. In a non-default case, when silo configuration code explicitly adds application assemblies (via ConfigureApplicationParts) but doesn't include OrleansProviders.dll in the list, the memory grain storage provider will not function. The workaround is to add OrleansProviders.dll to the list via ConfigureApplicationParts. The default case, when ConfigureApplicationParts isn't explicitly called and all assemblies in the silo folder are scanned, works as expeted.Breaking changes
Non-breaking improvements
Non-breaking bug fixes
Remove legacy initialization from Silo class
Breaking changes
Non-breaking improvements
Code generation is too aggressive in generating serializers for most available types instead of just those that are directly used in grain methods (#3
Known issues
Breaking changes
IGrainInvokeInterceptor that got replaced with IGrainCallFilter (#3647)Non-breaking improvements
SiloHostBuilder (#3638)OrleansAzureUtils assembly and NuGet package into more granular assemblies and packages (#3668, #3719)CreateObjectReference from within a grain (#3757)Created a Microsoft.Orleans.Core.Abstractions nuget package and moved/refactored several types into it. We plan to rev and do breaking changes to this…
Improvements and bug fixes since 1.5.2
Breaking changes
Microsoft.Orleans.TestingSiloHost, Microsoft.Orleans.ServiceFabric, Microsoft.Orleans.OrleansTelemetryConsumers.Counters, Microsoft.Orleans.OrleansTelemetryConsumers.NewRelic and the PowerShell module.Microsoft.Extensions.Logging abstractions package (MEL for short from now on).Logger abstraction is preserved as obsolete for backwards compatibility in a new Microsoft.Orleans.Logging.Legacy package, but it's just a wrapper that forwards to ILogger from MEL. It is recommended that you migrate to it directly.ILogConsumer, in case the end-user has a custom implementation of that legacy interface. Similarly, it is recommended to rewrite the custom log consumer or telemetry consumer and implement ILoggerProvider from MEL instead.Logger were separated into a new ITelemetryProducer interface, and it's currently only being used by Orleans to publish metrics. #3390Microsoft.Orleans.Core.Abstractions nuget package and moved/refactored several types into it. We plan to rev and do breaking changes to this package very infrequently.Microsoft.Orleans.OrleansCodeGenerator package). You should use build-time codegen by installing the Microsoft.Orleans.OrleansCodeGenerator.Build package in the grain implementations' and interfaces' projects.SiloHostBuilder and ClientBuilder are intended to replace the previous ways of initializing Orleans. They are not at 100% parity with ClusterConfiguration and ClientConfiguration so these are still required for beta1, but they will be eventually deprecated.SiloHostBuilder and ClientBuilder, Orleans will no longer scan every single assembly loaded in the AppDomain by default, and instead you need to be explicit to which ones you use by calling the AddApplicationPartXXX methods from each of the builders.MessagingOptions can be configured using the utilities in the Microsoft.Extensions.Options package. Before the final 2.0.0 release, the plan is to have everything moved to that configuration infrastructure.IGrainActivationContext that can be injected into Transient or Scoped service to get access to activation specific information and lifecycle events #2856 #3270 #3385Grain.OnActivateAsync to callers #3315GrainState class #3167Non-breaking improvements
TestCluster to spin up in-memory clusters all the time #3518Non-breaking bug fixes
Remove activation from message target list if constructor threw an exception
Backported #5958 from 2.4.3.
Do not call release header/body on a message in the dispatcher
Backported #5920 from 2.4.2.
Add handling when pulling agent fails RegisterAsProducer to pubsub
Two fixes backported from v2.x
Fixes for Multi-Cluster Support
Two fixes backported from v2.x
Improvements and bug fixes since 1.5.5.
Improvements and bug fixes since 1.5.5.
Add StreamSubscriptionHandleFactory to subscribe on behalf feature (#4943 - #3851). While technically a breaking change, it only impacts users of the…
Improvements and bug fixes since 1.5.4.
Improvements and bug fixes since 1.5.3.
Improvements and bug fixes since 1.5.3.
CodeGen: support builds which use reference assemblies
Improvements since 1.5.2.
Improvements and bug fixes since 1.5.1.
Improvements and bug fixes since 1.5.1.
Non-breaking bug fixes
NullReferenceException during activation collection #3399Non-breaking improvements
*Known issue (not new to 1.5.1): if your Orleans client project uses ASP.NET Core, there is a breaking change in the Microsoft.Extensions.DependencyIn…
Known issue (not new to 1.5.1): if your Orleans client project uses ASP.NET Core, there is a breaking change in the Microsoft.Extensions.DependencyInjection package when upgrading to 2.0.0 of it (which is required in ASP.NET Core 2). See https://github.com/dotnet/orleans/issues/3325 for more info.
Improvements and bug fixes since 1.5.0
IServiceProvider during client shutdown #3249ClusterClient.Dispose() is now equivalent to Abort() #3306BadImageFormatException from being written in the log during Silo or client startup #3216Microsoft.Orleans.OrleansServiceBus package #3344…namespace as the grain key extension (subtle breaking change: previous to 1.5 IGrainWithGuidCompoundKey wasn't technically supported, but if you did u…
Breaking changes
InconsistenStateException instead of StorageException when eTags do not match #2971InconsistentStateException (thrown when there is an optimistic concurrency conflict when writing to storage) #2959grain.BindGrainReference(grainFactory) on it or you would get GrainReferenceNotBoundException when attempting to use it #2738RegisterSerializerAttribute (and corresponding static Register method for registering a custom serializer). If you were using that, please read https://dotnet.github.io/orleans/Documentation/Advanced-Concepts/Serialization.html#writing-custom-serializers for alternative ways to register your custom serializer #2941Type values (but can cause compatibility issues if these were persisted by using the Serialziation Manager) #2952CacheSizeInMb setting with DataMaxAgeInCache and DataMinTimeInCache in stream providers #3126Catalog.Activation.DuplicateActivations counter to Catalog.Activation.ConcurrentRegistrationAttempts to more accurately reflect what it tracks and its benign nature #3130IGrainWithGuidCompoundKey as implicit subscription grain, and sets the stream namespace as the grain key extension (subtle breaking change: previous to 1.5 IGrainWithGuidCompoundKey wasn't technically supported, but if you did use it, the grain key extension would have had a null string) #3011GrainReference.FromKeyString method is no longer accessible, it has been replaced with IGrainReferenceConverter.GetGrainFromKeyString, which is accessible from the IServiceProvider.Non-breaking improvements
[OneWay] method attribute #2993CallContext.LogicalSetData with AsyncLocal #2200 #2961FabricClient when deploying to Service Fabric #2954TestCluster #2779TestingSiloHost in favor of TestCluster (although the former is still available for this version) #2919DuplicateActivationException from showing up in the logs #3130ImplicitStreamSubscriptionAttribute #2988StreamQueueBalancer pluggable #3152ISiloStatusOracle implementation in ServiceCollection #3160Non-breaking bug fixes
GrainCancellationTokenSource #3168NullReferenceException when no LogConsistencyProvider attribute is provided #3158…namespace as the grain key extension (subtle breaking change: previous to 1.5 IGrainWithGuidCompoundKey wasn't technically supported, but if you did u…
Improvements and bug fixes since 1.5.0-beta1 (checkout v1.5.0-beta1 release notes for changes since 1.4.X)
InconsistenStateException instead of StorageException when eTags do not match #2971Catalog.Activation.DuplicateActivations counter to Catalog.Activation.ConcurrentRegistrationAttempts to more accurately reflect what it tracks and its benign nature #3130WindowsAzure.ServiceBus package dependency to 4.1.0 #3127CacheSizeInMb setting with DataMaxAgeInCache and DataMinTimeInCache in stream providers #3126IGrainWithGuidCompoundKey as implicit subscription grain, and sets the stream namespace as the grain key extension (subtle breaking change: previous to 1.5 IGrainWithGuidCompoundKey wasn't technically supported, but if you did use it, the grain key extension would have had a null string) #3011ImplicitStreamSubscriptionAttribute #2988[OneWay] method attribute #2993Deactivating state for too long and remove it from the directory if needed #3082+ symbols #2956TimeSpan.MaxValue in configuration #2985CultureInfo via built-in serializer #3036DuplicateActivationException from showing up in the logs #3130Deprecated TestingSiloHost in favor of TestCluster (although the former is still available for this version) #2919
Improvements and bug fixes since 1.4.1.
grain.BindGrainReference(grainFactory) on it or you would get GrainReferenceNotBoundException when attempting to use it #2738RegisterSerializerAttribute (and corresponding static Register method for registering a custom serializer). If you were using that, please read https://dotnet.github.io/orleans/Documentation/Advanced-Concepts/Serialization.html#writing-custom-serializers for alternative ways to register your custom serializer #2941Type values (but can cause compatibility issues if these were persisted by using the Serialization Manager) #2952InconsistentStateException (thrown when there is an optimistic concurrency conflict when writing to storage) #2959InconsistenStateException instead of StorageException when eTags do not match #2971CallContext.LogicalSetData with AsyncLocal #2200 #2961FabricClient when deploying to Service Fabric #2954TestCluster #2779TestingSiloHost in favor of TestCluster (although the former is still available for this version) #2919Improvements and bug fixes since 1.4.1
Improvements and bug fixes since 1.4.1
Deactivating state for too long and remove it from the directory if needed #3082+ symbols #2956TimeSpan.MaxValue in configuration #2985CultureInfo via built-in serializer #3036Improvements and bug fixes since 1.4.0. Addressed the known issue in 1.4.0: "*When the silo starts up, it will register IServiceProvider in the contai
Improvements and bug fixes since 1.4.0. Addressed the known issue in 1.4.0: "When the silo starts up, it will register IServiceProvider in the container, which can be a circular reference registration when using 3rd party containers such as AutoFac."
Update to Consul 0.7.0.3 nuget package, because of breaking change in Consul API. #2498
Properties\orleans.codegen.cs to the project where codegen was being ran. The new MSBuild targets no longer do that, so when upgrading a solution with a previous version of Orleans, you should delete this orleans.codegen.cs file from your grain projects.JournaledGrain API #2651 #2720For the full changelog and up-to-date known issues, see Changelog
Update to Consul 0.7.0.3 nuget package, because of breaking change in Consul API. #2498
Improvements and bug fixes since 1.3.0.
Improvements and bug fixes since 1.3.0.
NB: There is a subtle breaking change in this release, which is unfortunately easy to miss. _If you are using AzureSilo.Start(ClusterConfiguration con…
NB: There is a subtle breaking change in this release, which is unfortunately easy to miss.
If you are using AzureSilo.Start(ClusterConfiguration config, string deploymentId) in your code, that overload has been removed, but the new one that replaced it has the same argument signature with a different second argument: (ClusterConfiguration config, string connectionString). Deployment ID now has to be passed as part of the config argument: config.Globals.DeploymentId. This removed the ambiguous possibility of passing two different Deployment IDs, but unfortunately at the cost of the breaking API change.
NB: There is a subtle breaking change in this release, which is unfortunately easy to miss. _If you are using AzureSilo.Start(ClusterConfiguration con…
NB: There is a subtle breaking change in this release, which is unfortunately easy to miss.
If you are using AzureSilo.Start(ClusterConfiguration config, string deploymentId) in your code, that overload has been removed, but the new one that replaced it has the same argument signature with a different second argument: (ClusterConfiguration config, string connectionString). Deployment ID now has to be passed as part of the config argument: config.Globals.DeploymentId. This removed the ambiguous possibility of passing two different Deployment IDs, but unfortunately at the cost of the breaking API change.
OrleansPerfCounterTelemetryConsumer either by code or XML. More information in #2122 and docs will come later. Microsoft.Orleans.CounterControl can still be used to install the performance counters or you can use InstallUtil.exe OrleansTelemetryConsumers.Counters.dll to install it without depending on OrleansCounterControl.exeBeta1 release of Microsoft Orleans v1.3.0 It does not yet include all the features that will go into the final 1.3.0 release. Most notably, the Global
Beta1 release of Microsoft Orleans v1.3.0 It does not yet include all the features that will go into the final 1.3.0 release. Most notably, the Global Single Instance protocol for Multi-Clusters (#1800).
See https://github.com/dotnet/orleans/issues/1972 for pending work that should go into the final release of 1.3.0
Bug fix: Prevent null reference exception after clearing PubSubRendezvousGrain state #2040
Bug fix: Prevent null reference exception after clearing PubSubRendezvousGrain state #2040
Ability to force creation of Orleans serializers for types not marked with [Serializable] by using GenerateSerializer, KnownType or KnownAssembly.Trea
Bugfix: Remote stacktrace is once again being included in the exception that bubbles up to the caller (bug introduced in 1.2.0). https://github.com/do
SupressDuplicateDeads: Use SiloAddress.Endpoint instead of InstanceName. https://github.com/dotnet/orleans/pull/1728
Bug fixes:
In addition to all the changes in 1.2.0-beta.
In addition to all the changes in 1.2.0-beta.
Added an EventHub stream provider based on the same code that is used in Halo 5.
GrainState anymore (marked as [Obsolete]) and can be a simple POCO class.IAsyncObserver<T>. https://github.com/dotnet/orleans/pull/1319Microsoft.Orleans.OrleansCodeGenerator.Build. Microsoft.Orleans.Templates.Interfaces and Microsoft.Orleans.Templates.Grains are now meta-packages for backward compatibility only. https://github.com/dotnet/orleans/pull/1501AzureClient and AzureSilo for easier programmatic config. https://github.com/dotnet/orleans/pull/1622AggregateException wrapping it. https://github.com/dotnet/orleans/pull/1356OrleansContrib). https://github.com/dotnet/orleans/pull/1376IAddressable. https://github.com/dotnet/orleans/pull/1675A patch release with a set of bug fixes.
A patch release with a set of bug fixes.
A patch release with bug fixes, primarily for codegen and serializer corner cases.
A patch release with bug fixes, primarily for codegen and serializer corner cases.
A patch release for two bug fixes.
A patch release for two bug fixes.
New Roslyn-based codegen, compile time and run time
Grain class are now virtualOrleansSQLUtils.dll for SQL-related functionality[KnownType] attribute for generating serializers for arbitrary typesNew Roslyn-based codegen, compile time and run time
OrleansSQLUtils.dll for SQL-related functionalityGrain class are now virtual[KnownType] attribute for generating serializers for arbitrary typesNew Roslyn-based codegen, compile time and run time
OrleansSQLUtils.dll for SQL-related functionalityGrain class are now virtualNo SDK msi anymore, only NuGets from now on
General:
MyGrainFactory.GetGrain() factory methodsStorageProvider attribute is now optionalObserverSubscriptionManagerStatelessWorker activations per siloStreaming:
ImplicitSubscription attributes for streamsDeprecated generated per-interface GetGrain static factory methods.
IGrainIdentity and IGrainRuntime to constructor.IGrainRuntime is a mockable interface that includes a set of system service interfaces, also mockable.GrainFactory is a non-static class that is accessed via base.GrainFactory from within a grain and via GrainClient.GrainFactory on the client.GetGrain static factory methods.Read/Write/ClearStateAsync methods from IGrainState and moved them to Grain<T>.ZooKeeper based cluster membership storage option.Microsoft.WindowsAzure.ServiceRuntime.dll.OrleansAzureUtils.dll, which is now optional.Fixed versions of references Orleans NuGet packages to match the current one. Switched message header keys from strings to enums for performance. Fixe
Fixed versions of references Orleans NuGet packages to match the current one. Switched message header keys from strings to enums for performance. Fixed a deadlock issue in deactivation process. Added a NuGet package to simplify testing of grain projects - Microsoft.Orleans.TestingHost. Fixed regression of reporting codegen error to Visual Studio Errors window. Added version to SDK msi product and folder name. Other fixes and improvements.
Major refactoring of the stream adapter API. Improvements to the steaming API to support subscription multiplicity. Made IAddressable.AsReference stro
Major refactoring of the stream adapter API. Improvements to the steaming API to support subscription multiplicity. Made IAddressable.AsReference strongly-typed. Added a Chocolatey package. Added support for private storage keys for testing. Replaced ExtendedPrimaryKeyAttribute with IGrainWithGuidCompoundKey and IGrainWithIntegerCompoundKey. Added support for grain classes that are implementations of generic grain interfaces with concrete type arguments. Numerous other fixes and improvements.
Major reorganization of NuGet packages and project templates. Fixes to reflection-only assembly inspection and loading for side-by-side versioning. Im
Major reorganization of NuGet packages and project templates. Fixes to reflection-only assembly inspection and loading for side-by-side versioning. Improved scalability of observers. Programmatic configuration of providers. Numerous other fixes and improvements.
Nothing published for this version
Initial stable production-quality release.
Initial stable production-quality release.
One column per quarter.