NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet
NuGet, #2409 most downloaded on NuGet
Library of built-in persistence and stream providers included in Microsoft Orleans.
Latest stable
3.8.1
Last release 7 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.
Nothing published for this version
[3.x] Implement CleanupDefunctSiloEntries for ZooKeeper clustring by @EugeneKrapivin in https://github.com/dotnet/orleans/pull/9236
CleanupDefunctSiloEntries for ZooKeeper clustring by @EugeneKrapivin in https://github.com/dotnet/orleans/pull/9236ValidateInitialConnectivity to MaxJoinAttemptTime (#9312) by @ReubenBond in https://github.com/dotnet/orleans/pull/9473Full Changelog: https://github.com/dotnet/orleans/compare/v3.7.2...v3.8.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
[3.x] Fix directory/cache validation for defunct silos by @ReubenBond in https://github.com/dotnet/orleans/pull/8498
Full Changelog: https://github.com/dotnet/orleans/compare/v3.7.1...v3.7.2
This release fixes a reliability bug in Orleans.Transactions
This release fixes a reliability bug in Orleans.Transactions
readyTask failures are recovered from by @ReubenBond in https://github.com/dotnet/orleans/pull/8443Full Changelog: https://github.com/dotnet/orleans/compare/v3.7.0...v3.7.1
[3.x] implement cleanup defunct silo entries ado net clustering by @ElanHasson in https://github.com/dotnet/orleans/pull/7929
IGrainActivationContextAccessor, providing access to IGrainActivationContext by @ReubenBond in https://github.com/dotnet/orleans/pull/8076Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.5...v3.7.0
Add azure pipeline yaml file for 3.x to build and test PR by @benjaminpetit in https://github.com/dotnet/orleans/pull/7914
NullReferenceException when too many instances of a [StatelessWorker] are created and Debug logging is enabled by @ReubenBond in https://github.com/dotnet/orleans/pull/7918Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.4...v3.6.5
Fix: GrainDirectoryPartition should allow overwriting an invalid entry by @benjaminpetit in https://github.com/dotnet/orleans/pull/7905
Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.3...v3.6.4
Fix generic method by @phynalle in https://github.com/dotnet/orleans/pull/7697
Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.2...v3.6.3
DynamoDB optional table create / update and update corner cases by @smiron in https://github.com/dotnet/orleans/pull/7681
Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.1...v3.6.2
Ignore value loaded in EventHubCheckpointer if it's obviously corrupted by @benjaminpetit in https://github.com/dotnet/orleans/pull/7529
Full Changelog: https://github.com/dotnet/orleans/compare/v3.6.0...v3.6.1
Breaking and potentially breaking changes
Authentication to Azure services has evolved and connection strings are typically deemphasized in favor of managed identities. In this release, we've migrated Azure providers to newer libraries which support managed identities and other authentication methods and we've updated options to expose this functionality. Since there are a large number of potential authentication methods requiring various combinations of options, we moved away from exposing each property and instead added configuration methods to the provider options.
For example, AzureStorageOperationOptions has a ConfigureTableServiceClient method with the following overloads:
void ConfigureTableServiceClient(string connectionString)void ConfigureTableServiceClient(Uri serviceUri)void ConfigureTableServiceClient(Func<Task<TableServiceClient>> createClientCallback)void ConfigureTableServiceClient(Uri serviceUri, TokenCredential tokenCredential)void ConfigureTableServiceClient(Uri serviceUri, AzureSasCredential azureSasCredential)void ConfigureTableServiceClient(Uri serviceUri, TableSharedKeyCredential sharedKeyCredential)Configuration methods help to ensure that the right combination of parameters are provided.
Note, if you are using ASP.NET Core 2.1, please note that we have had reports of users running into an incompatibility issue in Microsoft.Extensions, preventing the upgrade. Please see https://github.com/dotnet/extensions/issues/3800, https://github.com/dotnet/aspnetcore/issues/40255, and https://github.com/dotnet/orleans/issues/7608
Breaking and potentially breaking changes
Non-breaking improvements
Non-breaking bug fixes
Thank you to the following community members for your PR contributions and to everyone else who contributed: @mjameson-se @dave-b-code @michaeltdaniels @EdeMeijer @shmurchi
Full Changelog: https://github.com/dotnet/orleans/compare/v3.5.1...v3.6.0
Support ILBasedSerializer as a fallback only after trying the configured fallback
Potentially-breaking changes
Non-breaking improvements
Microsoft.Orleans.Kubernetes.Hosting package (Fix: Orleans.Hosting.KubernetesHosting: System.MissingMethodException (#7364))Non-breaking bug fixes
Add C# 9.0 record support to serializer
Non-breaking improvements
ILBasedSerializer when BinaryFormatter is disabled (#7198)TokenCredential support on Azure Event Hubs Stream Provider (#7166)MembershipVersion in GrainAddress (#7133)ValueTask and ValueTask<T> to be used in generic grain methods (#7190)Non-breaking bug fixes
PooledQueueCache, avoid cache miss if we know that we didn't miss any event (#7060)GenericMethodInvoker now correctly handles generic methods with overloads (#6844)EventHubReceiverProxy: ignore if offset isn't valid (#7192)GrainTimer (#7234)This release is based on 3.4.3, but without some changes made in 3.5.0, noticeably the Event Hubs library upgrade.
This release is based on 3.4.3, but without some changes made in 3.5.0, noticeably the Event Hubs library upgrade.
If possible, users should upgrade to 3.5.0 instead.
Prevent diagnostic notification messages from being dropped prematurely
Close connections asynchronously and improve gracefulness
Non-breaking improvements
Non-breaking bug fixes
The `Microsoft.Orleans.Kubernetes.Hosting` package is now marked as stable. This package is intended to help users who are deploying to Kubernetes by
The Microsoft.Orleans.Kubernetes.Hosting package is now marked as stable. This package is intended to help users who are deploying to Kubernetes by automating configuration of silos, monitoring Kubernetes for changes in the active pods, and terminating pods which are marked as defunct by the Orleans cluster. Please try it and give us your feedback. Documentation is available here and a sample project is available here.
Non-breaking improvements
LRU.Add() (#6872)IStorage that is not generic (#6928) (#6931)Non-breaking bug fixes
RunningRequestSenders (#6903)LinuxEnvironmentStatistics (#6842) (#6887)GrainDirectoryPartition, throw an exception instead of returning null if trying to register an activation on a non-valid silo (#6896) (#6901)OnActivateAsync() (#6891) (#6893)This release includes improvements to the cluster membership algorithm which are *opt-in* in this initial release. These changes are aimed at improvin
This release includes improvements to the cluster membership algorithm which are opt-in in this initial release. These changes are aimed at improving the accuracy of cluster membership when some or all nodes are in a degraded state. Details follow.
This PR implements some of the ideas from Lifeguard (paper, talk, blog) which can help during times of catastrophe, where a large portion of a cluster is in a state of partial failure. One cause for these kinds of partial failures is large scale thread pool starvation, which can cause a node to run slowly enough to not process messages in a timely manner. Slow nodes can therefore suspect healthy nodes simply because the slow node is not able to process the healthy node's timely response. If a sufficiently proportion of nodes in a cluster are slow (eg, due to an application bug), then healthy nodes may have trouble joining and remaining in the cluster, since the slow nodes can evict them. In this scenario, slow nodes will also be evicting each other. The intention is to improve cluster stability in these scenarios.
This PR introduces LocalSiloHealthMonitor which uses heuristics to score the local silo's health. A low score (0) represents a healthy node and a high score (1 to 8) represents an unhealthy node.
LocalSiloHealthMonitor implements the following heuristics:
Active in membershipFailing heuristics contribute to increased probe timeouts, which has two effects:
This effects of this feature are disabled by default in this release, with only passive background monitoring being enabled. The extended probe timeouts feature can be enabled by setting ClusterMembershipOptions.ExtendProbeTimeoutDuringDegradation to true. The passive background monitoring period can be configured by changing ClusterMembershipOptions.LocalHealthDegradationMonitoringPeriod from its default value of 10 seconds.
This PR adds support for indirectly pinging silos before suspecting/declaring them dead. When a silo is one missed probe away from being voted, the monitoring silo switches to indirect pings. In this mode, the silo picks a random other silo and sends it a request to probe the target silo. If that silo responds promptly with a negative acknowledgement (after waiting for a specified timeout), then the silo will be suspected/declared dead.
Additionally, when the vote limit to declare a silo dead is 2 silos, a negative acknowledgement counts for both required votes and the silos is unilaterally declared dead.
The feature is disabled by default in this release - only direct probes are used by-default - but could be enabled in a later release, or by users by setting ClusterMembershipOptions.EnableIndirectProbes to true.
This release includes improvements to the cluster membership algorithm which are *opt-in* in this initial release. These changes are aimed at improvin
This release includes improvements to the cluster membership algorithm which are opt-in in this initial release. These changes are aimed at improving the accuracy of cluster membership when some or all nodes are in a degraded state. Details follow.
This PR implements some of the ideas from Lifeguard (paper, talk, blog) which can help during times of catastrophe, where a large portion of a cluster is in a state of partial failure. One cause for these kinds of partial failures is large scale thread pool starvation, which can cause a node to run slowly enough to not process messages in a timely manner. Slow nodes can therefore suspect healthy nodes simply because the slow node is not able to process the healthy node's timely response. If a sufficiently proportion of nodes in a cluster are slow (eg, due to an application bug), then healthy nodes may have trouble joining and remaining in the cluster, since the slow nodes can evict them. In this scenario, slow nodes will also be evicting each other. The intention is to improve cluster stability in these scenarios.
This PR introduces LocalSiloHealthMonitor which uses heuristics to score the local silo's health. A low score (0) represents a healthy node and a high score (1 to 8) represents an unhealthy node.
LocalSiloHealthMonitor implements the following heuristics:
Active in membershipFailing heuristics contribute to increased probe timeouts, which has two effects:
This effects of this feature are disabled by default in this release, with only passive background monitoring being enabled. The extended probe timeouts feature can be enabled by setting ClusterMembershipOptions.ExtendProbeTimeoutDuringDegradation to true. The passive background monitoring period can be configured by changing ClusterMembershipOptions.LocalHealthDegradationMonitoringPeriod from its default value of 10 seconds.
This PR adds support for indirectly pinging silos before suspecting/declaring them dead. When a silo is one missed probe away from being voted, the monitoring silo switches to indirect pings. In this mode, the silo picks a random other silo and sends it a request to probe the target silo. If that silo responds promptly with a negative acknowledgement (after waiting for a specified timeout), then the silo will be suspected/declared dead.
Additionally, when the vote limit to declare a silo dead is 2 silos, a negative acknowledgement counts for both required votes and the silos is unilaterally declared dead.
The feature is disabled by default in this release - only direct probes are used by-default - but could be enabled in a later release, or by users by setting ClusterMembershipOptions.EnableIndirectProbes to true.
This release includes improvements to give developers additional context when a request does not return promptly. PR #6672 added these improvements. O
This release includes improvements to give developers additional context when a request does not return promptly. PR #6672 added these improvements. Orleans will periodically probe active grains to inspect their message queues and send status updates for certain requests which have been enqueued or executing for too long. These status messages will appear as warnings in the logs and will also be included in exceptions when a request timeout occurs. The information included can help a developer to identify what the grain is doing at the time of the request. For example, which messages are enqueued ahead of this message, and which messages are executing, how long they have been executing, how long this message has been enqueued, and the status of the grain's TaskScheduler.
This release adds a new pre-release package, Microsoft.Orleans.Hosting.Kubernetes, which adds richer integration for users hosting on Kubernetes. The package assists users by monitoring Kubernetes for silo pods and reflecting changes in cluster membership. For example, when a Pod is deleted, it is immediately removed from Orleans' membership. In addition, the package configures EndpointOptions and `ClusterOptions' to match the Pod's environments. Documentation and a sample project are expected in the coming weeks, and in the meantime, please see the original PR for more information: #6707.
Potentially breaking change
IStorage<TState> and IGrainState need to be updated to add a RecordExists property.)Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.3.0-rc1.
Improvements and bug fixes since 3.3.0-rc1.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.2.2.
Improvements and bug fixes since 3.2.2.
This release includes improvements to give developers additional context when a request does not return promptly. PR #6672 added these improvements. Orleans will periodically probe active grains to inspect their message queues and send status updates for certain requests which have been enqueued or executing for too long. These status messages will appear as warnings in the logs and will also be included in exceptions when a request timeout occurs. The information included can help a developer to identify what the grain is doing at the time of the request. For example, which messages are enqueued ahead of this message, and which messages are executing, how long they have been executing, how long this message has been enqueued, and the status of the grain's TaskScheduler.
Improvements and bug fixes since 3.2.1.
Improvements and bug fixes since 3.2.1.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.2.0.
Improvements and bug fixes since 3.2.0.
Non-breaking improvements
Non-breaking bug fixes
We intend to bring it back as a grain directory plugin at a later time. Removal of multi-clustering is the only breaking change, and only if you used…
This feature allows to use external storage as an option for keeping grain directory information. Directory plugins can be configured for different grain classes independently, so that different consistency/availability tradeoffs can be made for different grain classes. As part of this change, we had to remove support for multi-cluster functionality. We intend to bring it back as a grain directory plugin at a later time. Removal of multi-clustering is the only breaking change, and only if you used the feature previously.
Since the initial release, Orleans has been using its own custom thread pool implementation to make up for the deficiencies in the .NET thread pool. Since then, the .NET thread pool has improved significantly, and there is no need any more for a separate solution within Orleans.
We measured a performance increase of 3.2.0 compared to 3.1.6 of 12% to 20% depending on the test scenario.
Other improvements and bug fixes since 3.1.0.
Breaking changes
Non-breaking improvements
READ COMMITTED to avoid Gap Lock issues (#6331)Non-breaking bug fixes
Improvements and bug fixes since 3.2.0-rc2
Improvements and bug fixes since 3.2.0-rc2
We intend to bring it back as a grain directory plugin at a later time. Removal of multi-clustering is the only breaking change, and only if you used…
This feature allows to use external storage as an option for keeping grain directory information. Directory plugins can be configured for different grain classes independently, so that different consistency/availability tradeoffs can be made for different grain classes. As part of this change, we had to remove support for multi-cluster functionality. We intend to bring it back as a grain directory plugin at a later time. Removal of multi-clustering is the only breaking change, and only if you used the feature previously.
Since first version, Orleans has been using its own custom thread pool implementation to make up for the deficiencies in the .NET thread pool. Since then, the .NET thread pool has improved significantly, and there is no need any more for a separate solution within Orleans.
We measured a performance increase of 3.2.0-rc1 compared to 3.1.6 of 12% to 20% depending on the test scenario.
Other improvements and bug fixes since 3.1.6.
Breaking changes
Non-breaking improvements
READ COMMITED to avoid Gap Lock issues (#6331)Non-breaking bug fixes
Improvements and bug fixes since 3.1.6.
Improvements and bug fixes since 3.1.6.
Improvements and bug fixes since 3.1.5.
Improvements and bug fixes since 3.1.5.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.1.4.
Improvements and bug fixes since 3.1.4.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.1.3.
Improvements and bug fixes since 3.1.3.
Non-breaking improvements
Non-breaking bug fixes
Breaking changes (for rolling upgrades from 3.1.0 and 3.1.2 running on .NET Core 3.1)
This release fixes the partial backward compatibility regression introduced in 3.1.0. See #6392 for more details.
If your application targets .NET Core 3.1, rolling upgrade to 3.1.3 can be performed from all versions except for 3.1.0 and 3.1.2 For all other .NET versions, there are no known compatibility issues with rolling upgrades to 3.1.3
Improvements and bug fixes since 3.1.2.
Breaking changes (for rolling upgrades from 3.1.0 and 3.1.2 running on .NET Core 3.1)
Non-breaking improvements
Known issue: We discovered a partial backward compatibility regression in this release. If your application targets .NET Core 3.1, a rolling upgrade f
Known issue: We discovered a partial backward compatibility regression in this release. If your application targets .NET Core 3.1, a rolling upgrade from previous versions to 3.1.2 will fail. See #6392 for more details. The regression is fixed in 3.1.3.
Improvements and bug fixes since 3.1.0.
Non-breaking improvements
Non-breaking bug fixes
Nothing published for this version
Microsoft.Orleans.OrleansCodeGenerator.Build package has been marked as deprecated in favor of Microsoft.Orleans.CodeGenerator.MSBuild. We don't plan…
Known issue: We discovered a partial backward compatibility regression in this release. If your application targets .NET Core 3.1, a rolling upgrade from previous versions to 3.1.0 will fail. See #6392 for more details. The regression is fixed in 3.1.3.
Improvements and bug fixes since 3.0.0.
In this release we enabled multi-targeting, nestandard2.0 and netcoreapp3.1, for Microsoft.Orleans.Core, Microsoft.Orleans.OrleansRuntime, and Microsoft.Orleans.Connections.Security packages to leverage some performance features available in netcoreapp3.1.
Microsoft.Orleans.OrleansCodeGenerator.Build package has been marked as deprecated in favor of Microsoft.Orleans.CodeGenerator.MSBuild. We don't plan future releases of Microsoft.Orleans.OrleansCodeGenerator.Build.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.1.0-rc2.
Improvements and bug fixes since 3.1.0-rc2.
Improvements and bug fixes since 3.1.0-rc1.
Improvements and bug fixes since 3.1.0-rc1.
In this release we enabled multi-targeting, nestandard2.0 and netcoreapp3.1, for Microsoft.Orleans.Core, Microsoft.Orleans.OrleansRuntime, and Microsoft.Orleans.Connections.Security packages to leverage some performance features available in netcoreapp3.1.
Improvements and bug fixes since 3.0.2.
Improvements and bug fixes since 3.0.2.
In this release we enabled multi-targeting, nestandard2.0 and netcoreapp3.1, for Microsoft.Orleans.Core, Microsoft.Orleans.OrleansRuntime, and Microsoft.Orleans.Connections.Security packages to leverage some performance features available in netcoreapp3.1.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.0.1.
Improvements and bug fixes since 3.0.1.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 3.0.0.
Improvements and bug fixes since 3.0.0.
Non-breaking improvements
Non-breaking bug fixes
…of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
Major improvements since 2.0.0
This release is backward compatible, over the wire messaging wise, with 2.* releases, which allows for in-place upgrade of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
Tested on .NET Framework 4.7.2, .NET Core 2.2 and .NET Core 3.0.
Changes since 2.3.0:
Non-breaking improvements
Non-breaking bug fixes
…of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
This release is backward compatible, over the wire messaging wise, with 2.* releases, which allows for in-place upgrade of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
Tested on .NET Framework 4.7.2, .NET Core 2.2 and .NET Core 3.0.
This release is ready for production use.
Changes since 3.0.0-rc1:
Non-breaking improvements
Non-breaking bug fixes
…of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
This release is backward compatible, over the wire messaging wise, with 2.* releases, which allows for in-place upgrade of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
We measured significant performance gains with this release over 2.* versions, ranging from 8% to 93% depending on the test, mostly due to the network stack rewrite.
Tested on .NET Framework 4.7.2, .NET Core 2.2 and .NET Core 3.0.
This release is ready for production use.
Known issue. If you get the following run time error on .NET Core 3.0
An exception of type 'System.IO.FileNotFoundException' occurred in Orleans.Runtime.dll but was not handled in user code: 'Could not load file or assembly 'Microsoft.Bcl.AsyncInterfaces, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'.
add an explicit reference to Microsoft.Bcl.AsyncInterfaces NuGet package to your project. See #6028 for details.
Changes since 3.0.0-beta1:
Non-breaking improvements
Non-breaking bug fixes
…of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
This release is backward compatible, over the wire messaging wise, with 2.* releases, which allows for in-place upgrade of a running cluster. However, there are several breaking changes in the APIs that might require minor adjustments for application code to compile.
We measured significant performance gains with this release over 2.* versions, ranging from 8% to 93% depending on the test, mostly due to the network stack rewrite.
Changes since 2.3.0:
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.4.4.
Improvements and bug fixes since 2.4.4.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.4.3.
Improvements and bug fixes since 2.4.3.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.4.2.
Improvements and bug fixes since 2.4.2.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.4.1.
Improvements and bug fixes since 2.4.1.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.4.0. The most important one is #5863 that relaxes the requirements for clustering providers that do not support mem
Improvements and bug fixes since 2.4.0. The most important one is #5863 that relaxes the requirements for clustering providers that do not support membership table version. See more details on that in the release notes for 2.4.0.
Non-breaking improvements
Non-breaking bug fixes
Reduced reliance on cluster membership table and speed up clustering convergence by sending versioned snapshots of the table as part of gossip message
Important: An incompatibility was reported of 2.4.0 with clustering providers, such as MongoDB and DynamoDB, that do not implement correctly or at all membership table version. This issue has been addressed via #5863 in v2.4.1.
This release is backward compatible with 2.0.* releases, which allows for in-place upgrade of a running cluster.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.3.5
Improvements and bug fixes since 2.3.5
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.3.4.
Improvements and bug fixes since 2.3.4.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.3.3.
Improvements and bug fixes since 2.3.3.
Improvements and bug fixes since 2.3.2.
Improvements and bug fixes since 2.3.2.
Non-breaking improvements
Non-breaking bug fixes
Improvements and bug fixes since 2.3.1.
Improvements and bug fixes since 2.3.1.
Improvements and bug fixes since 2.3.0. The important change is bringing back the batch stream production API that got removed in 2.3.0 by mistake.
Improvements and bug fixes since 2.3.0. The important change is bringing back the batch stream production API that got removed in 2.3.0 by mistake.
Non-breaking improvements
Non-breaking bug fixes
All packages have been updated.
One column per quarter.