NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet
NuGet, #2282 most downloaded on NuGet
Fast, flexible, and version-tolerant serializer for .NET
Latest stable
10.4.2
Last release 23 days ago
30 Oct 2026
Release timing varies
gaps range from 2 weeks to 6 months
Nearly every release is documented
notes for 31 of 31 stable releases
2 versions withdrawn
withdrawn after publishing
127 years old
42 releases · first in 1900
Drag across the ruler to compare, or tap a release to open it.
[10.x] fix(azure): tolerate legacy membership writers during rolling upgrades by @ReubenBond in https://github.com/dotnet/orleans/pull/11624
Full Changelog: https://github.com/dotnet/orleans/compare/v10.4.1...v10.4.2
Update MessagePack to 3.1.11, incorporating nested-array, regex backtracking, and LZ4 integer-overflow security fixes. #11519
Orleans 10.4.1 improves cluster membership, grain scheduling, graceful shutdown, client startup, serialization, and provider reliability. It also restores standalone serializer code generation, fixes ADO.NET streaming message loss, and improves dashboard statistics and navigation.
[!IMPORTANT] Public API compatibility:
SiloAddress.GetUniformHashCodes(int)now returnsImmutableArray<uint>instead ofuint[]. This is a source- and binary-breaking change for code which calls this method. Rebuild affected applications and libraries against 10.4.1. UseToArray()when a mutable array is required, orSort()for an immutable sorted result. See #11425.
GrainDirectoryOptions.GetPartitionBoundaries callback supports configuring the mapping used by an existing cluster, including the older sorted-hash mapping. Partition defaults remain unchanged. See #11425.IManagementGrain.DeactivateGrain operation after all active silos have been upgraded to support it. See #11483.UseVirtualBucketsConsistentRing = false receive corrected request routing. During a rolling upgrade, older callers can still route reminder operations to the wrong owner. Persisted reminders are reconciled on the owner's next successful refresh, which defaults to five minutes; early occurrences can be missed before reconciliation. Custom grain services using this ring need application-specific upgrade handling. The default virtual-buckets provider retains its existing behavior. See #11598.The release preparation PR, #11566, bundles multiple backports. Those changes are expanded below, with links to their original PRs alongside the subsequent 10.x fixes.
[ReadOnly] requests and correctly handling mixed MayInterleave workloads. #10809Change calls made during that interval apply the latest schedule after the callback completes. #11464SiloUnavailableException failures when a retiring silo departs, while preserving callers' original deadlines. Applications should continue to account for ambiguous outcomes when an acceptance acknowledgement is lost. #11460IManagementGrain.DeactivateGrain(GrainId, CancellationToken) locates existing activations directly and waits for their deactivation callbacks. This supports lifecycle operations on grains whose persisted state cannot currently be read. #11483[21.0.8,22.0.0). #11503Microsoft.Orleans.Serialization receive the transitive source-generator and analyzer dependencies needed for [GenerateSerializer] types, fixing runtime CodecNotFoundException failures caused by missing generated codecs. #11603Full changelog: https://github.com/dotnet/orleans/compare/v10.4.0...v10.4.1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
This release strengthens cluster membership consistency, extends cooperative cancellation across framework APIs, and gives streaming applications more
This release strengthens cluster membership consistency, extends cooperative cancellation across framework APIs, and gives streaming applications more control over subscription start positions and dequeue sizes. This release also fixes SQLite persistence under contention, modernizes request-latency metrics, improves serialization and source-generation efficiency, and expands the preview journaling and Durable Jobs capabilities.
[!IMPORTANT] Review the SQLite query updates and metric schema changes when upgrading.
Histogram<double> named orleans-app-requests-latency, measured in fractional milliseconds. It replaces the separate orleans-app-requests-latency-bucket, -count, and -sum instruments and their duration attribute. Configure histogram boundaries through an OpenTelemetry View and update dashboards, alerts, and recording rules for the exporter representation. Use matching boundaries across instances whose distributions are aggregated.orleans-grains now uses grain_type, containing the canonical GrainId.Type identity, in place of type, which contained the CLR implementation name. Activation lifecycle metrics also gain this dimension. Update queries and label filters accordingly.[Id] attributes now control serialized argument IDs, and automatic IDs count serialized parameters. Place CancellationToken last. Existing contracts with parameter [Id] attributes or non-last cancellation tokens can change argument wire IDs relative to 10.3.1; coordinate their client/silo contract upgrade or introduce versioned contracts. Method-level [Id] attributes and ordinary unannotated, token-last contracts retain their existing identities and argument numbering.10.4.0-alpha.1. Custom integrations should adopt the updated durable-state/state-machine contracts and streamed catalog enumeration APIs. Named-provider migration is an opt-in capability for moving Durable Jobs between storage backends; existing default-provider convenience registrations remain available.ClusterManifestOptions.EnableContentAddressedRetrieval selects the retrieval mode (#11239).StreamSubscriptionStartPosition.Latest and EarliestAvailable provide per-subscription control, with a provider default through StreamPullingAgentOptions.InitialSubscriptionStartPosition. EarliestAvailable starts at the oldest retained message for the stream in the local queue cache. An explicit sequence token takes precedence, and Latest remains the default. Enable the new controls after pulling-agent silos have been upgraded (#10936).MemoryStreamCacheOptions.MaxAddCount controls the maximum number of queue records requested per dequeue, allowing applications to balance response size and queue-call overhead. The default remains 100 (#11238).Microsoft.Orleans.Journaling.S3 adds append-based write-ahead logs, conditional metadata/checkpoint publication, catalog discovery, and provider metrics. A conditional-rewrite mode supports S3-compatible development environments (#10161).UnsafeAccessor methods for private, readonly, and backing fields on supported targets. Grain activation constructors are preserved, non-generic grain references gain native construction, and serialization constructors can initialize existing objects under NativeAOT. Default serializer activation uses a shared construction path with consistent exception propagation (#11372, #11383, #11371, #11373, #11390).<OrleansHotReload>true</OrleansHotReload> to generate stable member/dependency identities and lazily initialize dependencies added to existing serializers and copiers. Supported updates add strongly typed serialized members to classes and records; restart to refresh manifests when adding new polymorphic or collection-element types (#10932).Microsoft.Orleans.Clustering.TestKit provides framework-neutral membership-provider conformance scenarios and generated operation histories for validating custom providers (#11308).Full Changelog: https://github.com/dotnet/orleans/compare/v10.3.1...v10.4.0
The most significant change in this release over 10.3.0 is the format used by the version contract compatibility analyzers. The other changes are test
The most significant change in this release over 10.3.0 is the format used by the version contract compatibility analyzers. The other changes are test and docs fixes.
Full Changelog: https://github.com/dotnet/orleans/compare/v10.3.0...v10.3.1
Update vulnerable SSH.NET and nanoid dependencies by @ReubenBond in https://github.com/dotnet/orleans/pull/10678
Orleans 10.3.0 expands the platform across clustering, streaming, persistence, integrations, serialization, and developer tooling while delivering a broad reliability and performance pass. Major outcomes include stronger distributed-directory and membership behavior, new streaming and storage providers, hardened transactions and durable jobs, incremental source generation, safer JSON storage deserialization, and new application templates. Alongside these features and fixes, the release optimizes key runtime paths, comprehensively refreshes the docs, strengthens testing and CI, and updates dependencies and repository maintenance.
[!IMPORTANT] Review these changes before upgrading. This release contains three intentionally behavior-changing updates.
$type metadata only for types permitted by Orleans' configured type filters and manifest. Existing wire data remains readable when its types are allowed; [GenerateSerializer] types and standard permitted BCL types continue to work without changes. If persisted, streamed, or transactional JSON contains other types, reads now fail with an actionable JsonSerializationException. Prefer registering those types through TypeManifestOptions.AllowedTypes, [GenerateSerializer], ITypeNameFilter, or ITypeFilter; OrleansJsonSerializerOptions.AllowAllTypes = true restores the former permissive JSON behavior when a narrowly scoped allow-list is not practical.rpc.system.name; Orleans-specific service, target, and source metadata move to orleans.rpc.service, orleans.rpc.target_id, and orleans.rpc.source_id. The runtime-side rpc.method value is now qualified as <interface>/<method>, and affected ActivitySource versions are incremented. Update dashboards, alerts, collectors, and queries which depend on the legacy rpc.system, rpc.service, rpc.orleans.target_id, or rpc.orleans.source_id keys or the previous method value.IConfigureGrainContext actions before grain construction, so constructors can observe fully configured context state. Custom IGrainContextActivator implementations must migrate from CreateContext(GrainAddress) to CreateContext(GrainAddress, IConfigureGrainContext[]) and apply the supplied configurators before constructing the grain. Stateless-worker configurators continue to apply to the outer stateless-worker context.DbDataSource support, and improved Azure, ZooKeeper, Redis, NATS, and relational-provider behavior extend and stabilize integrations (#8462, #8699, #10326, #10429, #10381, #10437, #10835, #10422, #10505, #10276).Every change from the autogenerated changelog is listed once below.
<details> <summary><strong>Runtime, clustering, reminders & resilience (34)</strong></summary>
</details>
<details> <summary><strong>Streaming (21)</strong></summary>
</details>
<details> <summary><strong>Storage, persistence, journaling, durable jobs & transactions (26)</strong></summary>
</details>
<details> <summary><strong>Providers & integrations (12)</strong></summary>
</details>
<details> <summary><strong>Serialization, code generation & analyzers (15)</strong></summary>
</details>
<details> <summary><strong>Developer experience, templates & samples (4)</strong></summary>
</details>
<details> <summary><strong>Documentation (89)</strong></summary>
</details>
<details> <summary><strong>Testing (117)</strong></summary>
</details>
<details> <summary><strong>CI, build, dependencies & repository maintenance (34)</strong></summary>
</details>
Full Changelog: https://github.com/dotnet/orleans/compare/v10.2.2...v10.3.0
test: speed up shutdown timer readiness tests by @ReubenBond in https://github.com/dotnet/orleans/pull/10214
Full Changelog: https://github.com/dotnet/orleans/compare/v10.2.0...v10.2.2
a575888
This commit was created on GitHub.com and signed with GitHub’s verified signature .
GPG key ID: B5690EEEBB952194
Verified Learn about vigilant mode .
test: speed up shutdown timer readiness tests by @ReubenBond in #10214
fix: respect placement hints in local-first directors by @ReubenBond in #10217
fix: serialize immutable dictionary value comparers by @ReubenBond in #10225
perf(manifest): reduce cluster manifest payload size by @ReubenBond in #10224
fix: exclude non-Active silos from placement by @ReubenBond in #10219
fix(azure): allow configuring journal blob names by @ReubenBond in #10230
feat: prune excess defunct membership entries by @ReubenBond in #10231
fix: clear stale message receiver cache for forwarded silo messages by @ReubenBond in #10235
revert: remove fast-path message destination cache by @ReubenBond in #10243
chore(deps): bump dompurify from 3.4.7 to 3.4.11 in /src/Dashboard/Orleans.Dashboard.App by @dependabot [bot] in #10233
chore(deps-dev): bump vite from 8.0.11 to 8.0.16 in /src/Dashboard/Orleans.Dashboard.App by @dependabot [bot] in #10229
serialization: Allow enums when no type filter has an opinion by @Tragetaschen in #10234
chore(deps-dev): bump js-yaml from 4.1.1 to 4.3.0 in /src/Dashboard/Orleans.Dashboard.App by @dependabot [bot] in #10240
perf: add span formatting for membership snapshots by @ReubenBond in #10248
chore(deps-dev): bump @babel/core from 7.29.0 to 7.29.7 in /src/Dashboard/Orleans.Dashboard.App by @dependabot [bot] in #10241
fix(streaming): use overflow-safe comparison for cached message sequence numbers by @fernando-takeshi in #10245
[Automated] Update API Surface Area by @github-actions[bot] in #10223
Auto-generated baselines by 1ES Pipeline Templates by @ReubenBond in #10250
fix: update MessagePack dependency by @ReubenBond in #10251
feat: add SiloAddress parse interfaces by @ReubenBond in #10256
fix: use explicit address equality by @ReubenBond in #10257
fix(reminders): fix scheduling for long due times by @ReubenBond in #10260
fix(runtime): stop retrying dead directory members by @ReubenBond in #10261
fix: fence silos missing from newer membership views by @ReubenBond in #10262
[Automated] Update API Surface Area by @github-actions[bot] in #10252
fix(streaming): don't recycle in-flight pooled buffers mid-batch by @ReubenBond in #10264
[Automated] Update API Surface Area by @github-actions[bot] in #10265
fix(streaming): refresh idle EventHub cursors to avoid QueueCacheMissException by @ReubenBond in #10266
fix(membership): retain recently-declared-dead entries during pruning by @ReubenBond in #10269
fix(runtime): fault outstanding callbacks when a host shuts down by @ReubenBond in #10275
feat(serialization): add codecs for FrozenDictionary and FrozenSet by @ReubenBond in #10270
fix(testinghost): dispose stopped in-process silo hosts without leaking or hanging by @ReubenBond in #10272
chore(deps): bump dotnet-sdk from 10.0.301 to 10.0.302 by @dependabot [bot] in #10267
Resolve TimeProvider via keyed DI per subsystem (fixes FakeTimeProvider timer test CI hang) by @ReubenBond in #10271
[Automated] Update API Surface Area by @github-actions[bot] in #10277
fix(runtime): close callback admission during shutdown by @ReubenBond in #10290
fix(streaming): bound Event Hubs shutdown by @ReubenBond in #10288
fix(durable-jobs): treat shutdown cancellation as normal by @ReubenBond in #10285
fix: resolve component governance dependency alerts by @ReubenBond in #10287
chore(ci): complete 1ES autobaselining and branch controls by @ReubenBond in #10284
fix(streaming): avoid LeaseBasedQueueBalancer timer disposal race during shutdown by @ReubenBond in #10286
fix(runtime): avoid service resolution after silo shutdown by @ReubenBond in #10289
[Automated] Update API Surface Area by @github-actions[bot] in #10293
fix(runtime): transition silo status before grain deactivation by @ReubenBond in #10294
chore(deps-dev): bump brace-expansion from 1.1.12 to 1.1.16 in /src/Dashboard/Orleans.Dashboard.App by @dependabot [bot] in #10292
fix(ci): upload CodeQL results together by @ReubenBond in #10295
Full Changelog : v10.2.0...v10.2.2
ReubenBond, Tragetaschen, and 2 other contributors
Reverts the message destination receiver cache changes from https://github.com/dotnet/orleans/pull/10064 (commit: https://github.com/dotnet/orleans/co
Reverts the message destination receiver cache changes from https://github.com/dotnet/orleans/pull/10064 (commit: https://github.com/dotnet/orleans/commit/d3c2af3007e949869f3a858da11e75b2fd0a9ab4)
Full Changelog: https://github.com/dotnet/orleans/compare/v10.2.0...v10.2.1
Orleans v10.2.0 focuses on runtime reliability, grain directory correctness, observability, Durable Jobs and journaling improvements, provider fixes,
Orleans v10.2.0 focuses on runtime reliability, grain directory correctness, observability, Durable Jobs and journaling improvements, provider fixes, and a broad test/CI stabilization push.
grain_type tags on request timeout/cancel counters (#10178), a Dashboard lifecycle dependency graph (#10145), and migration of Orleans metrics to IMeterFactory (#10201).ArcBuffer support (#10066), built-in codecs for collection interface types (#10104, #10106), serializer conformance baselines (#10034), and safer request-context deserialization (#10017).IConnectionMultiplexer via ServiceKey no longer dispose that shared multiplexer on shutdown. Providers which create their own multiplexer still own and dispose it. (#10146, #10182)Orleans.Runtime.Instruments.Meter should resolve OrleansInstruments from DI and use its Meter instead. (#10201)JournaledStateManagerOptions.JournalFormatKey = "orleans-binary" to retain the old format for new writes. (#9973)ValidateInitialConnectivity stage runs before BecomeActive, keeping silos in Joining until initial peer connectivity is validated. (#10153)OrleansMessageRejectionException and ConnectionFailedException, with a longer default retry window. (#10140)GrainLifecycleEvents.ListenerName is now correctly "Orleans.GrainLifecycle"; code subscribing by the previous string literal should update. (#10121)IJournalStorageCatalog. (#10112, #10148)StorageType enum values are rejected at startup. (#10176)PlacementService workers during silo shutdown. (#9993)InsideRuntimeClient response handling, and removing locks from activation response processing. (#10118, #10119, #10129, #10127, #10128, #10139, #10141)ITimerRegistry on SystemTarget instances, enabling grain services/system targets to use features such as async enumerable cleanup timers without manual registration. (#10038)JsonConvert.DefaultSettings by moving reminder row serialization to System.Text.Json. (#10099)File or Memory) and validation for invalid storage-type values. (#10028, #10176)Confirm when storage failures occur, and improved classification of conflict/precondition responses. (#10123)TransactionResponse diagnostic formatting. (#10083)TypeConverter.ParseInternal alias resolution, enabled nullable annotations, and added support for JSON framework types in type conversion. (#10032)ArcBuffer support across serialization reader/writer/deserializer paths for lower-copy high-throughput scenarios. (#10066)IEnumerable<T>, IReadOnlyList<T>, ISet<T>, and dictionary interfaces. (#10104, #10106)System.Text.Json source-generated metadata. (#9973)IJournalStorageCatalog and optional journal metadata operations to support storage discovery and metadata updates. (#10112)DurableJob, and metrics for scheduling, dispatch lag, attempts, handler execution, shard processing, storage batches, and ownership checks. (#10151)[LoggerMessage] methods, reducing disabled-log overhead and allocations. (#10018, #10019, #10020, #10021, #10022, #10023, #10024, #10025, #10026)ObservableGauge, matching point-in-time memory semantics for exporters such as Prometheus. (#10029)grain_type tags to application request timeout and cancellation counters. (#10178)IMeterFactory for correct DI scoping, listener registration, test isolation, and multi-host scenarios. This covered networking, watchdog, gateway, scheduler, consistent ring, storage, catalog, client, reminder, directory, grain, stream, messaging, messaging processing, Durable Jobs, Azure Blob journal storage, journaling, environment statistics, stream cache, Event Hubs receiver/cache, and stream receiver metrics. (#10137, #10138, #10142, #10143, #10144, #10162, #10168, #10169, #10172, #10173, #10175, #10177, #10179, #10180, #10181, #10183, #10184, #10193, #10194, #10195, #10199, #10200)IMeterFactory migration. (#10201)AdaptivePing benchmark with hill-climbing concurrency tuning and improved convergence rules for more reproducible throughput measurements. (#10069, #10076)minimatch, picomatch, flatted, postcss, rollup, and vite. (#9956, #9974, #9967, #10043, #9957, #9998)StatelessWorkerGrainContext by @ReubenBond in https://github.com/dotnet/orleans/pull/10016ITimerRegistry component on SystemTargets by @ledjon-behluli in https://github.com/dotnet/orleans/pull/10038Full Changelog: https://github.com/dotnet/orleans/compare/v10.1.0...v10.2.0
Source link on dashboard to main orleans repo by @hendrikdevloed in https://github.com/dotnet/orleans/pull/9911
ConfigureAwait analyzer for grain code (ORLEANS0014) by @ReubenBond in https://github.com/dotnet/orleans/pull/9845IServiceLifecycle interface with lifecycle hooks for client and silo by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9792Full Changelog: https://github.com/dotnet/orleans/compare/v10.0.1...v10.1.0
Fix DynamoDB ExclusiveStartKey handling for AWS SDK v4 by @ReubenBond in https://github.com/dotnet/orleans/pull/9884
PooledBuffer cleanup by @pentp in https://github.com/dotnet/orleans/pull/9871Full Changelog: https://github.com/dotnet/orleans/compare/v10.0.0...v10.0.1
[Breaking Change] ADO.NET providers: replace obsolete System.Data.SqlClient with Microsoft.Data.SqlClient by @ReubenBond in https://github.com/dotnet/…
Orleans version 10 multi-targets .NET 8.0 and .NET 10.0
provider_type_name storage instrumentation metric tag by @cdemi in https://github.com/dotnet/orleans/pull/9615DurableState by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9628DurableTaskCompletionSource by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9626StatelessWorkerGrainContext when it contains no more workers by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9636ActivationDataActivatorProvider: run grain constructor on grain scheduler by @ReubenBond in https://github.com/dotnet/orleans/pull/9726ActivationCollector by @DeagleGross in https://github.com/dotnet/orleans/pull/9740LocalScheduledJobManager: avoid overlapping calls to PeriodicTimer.WaitForNextTickAsync, handle exceptions during shutdown. by @ReubenBond in https://github.com/dotnet/orleans/pull/9761IGrainManagementExtension.MigrateOnIdle completes by @ReubenBond in https://github.com/dotnet/orleans/pull/9758HostName, add NegotiatedCipherSuite by @ReubenBond in https://github.com/dotnet/orleans/pull/9788ActivityPropagationGrainCallFilter: minor cleanup by @ReubenBond in https://github.com/dotnet/orleans/pull/9789OrleansConstructorAttribute as obsolete by @ReubenBond in https://github.com/dotnet/orleans/pull/9790IGrainMigrationParticipant implementations by @ReubenBond in https://github.com/dotnet/orleans/pull/9786IAsyncEnumerable<T> requests by @ReubenBond in https://github.com/dotnet/orleans/pull/9630ActivationTaskScheduler tests by @ReubenBond in https://github.com/dotnet/orleans/pull/9810CancelUnknownRequestOnStatusUpdate option, default CancelRequestOnTimeout to false by @ReubenBond in https://github.com/dotnet/orleans/pull/9831CancellationToken & [AlwaysInterleave] support for grain observers by @ReubenBond in https://github.com/dotnet/orleans/pull/9834CancellationToken support for system targets by @ReubenBond in https://github.com/dotnet/orleans/pull/9837MinIdleCyclesBeforeRemoval to default value in StatelessWorkerOptions by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9860IAsyncEnumerableGrainExtension by @ReubenBond in https://github.com/dotnet/orleans/pull/9872AddDashboard method across ISiloBuilder and IClientBuilder by @ReubenBond in https://github.com/dotnet/orleans/pull/9873ITargetHolder methods non-generic to avoid costly lookup at runtime by @ReubenBond in https://github.com/dotnet/orleans/pull/9168Full Changelog: https://github.com/dotnet/orleans/compare/v9.2.1...v10.0.0
Fix load score calculation in ResourceOptimizedPlacementDirector by @ReubenBond in https://github.com/dotnet/orleans/pull/9611
ResourceOptimizedPlacementDirector by @ReubenBond in https://github.com/dotnet/orleans/pull/9611Full Changelog: https://github.com/dotnet/orleans/compare/v9.2.0...v9.2.1
Adaptive Directory Caching Obsoleted (#9542) - This strategy has been deprecated and removed
Orleans v9.2.0 includes significant new features, performance improvements, and enhanced developer experience. This release introduces native .NET CancellationToken support, new storage providers, improved placement strategies, and numerous performance optimizations.
The following is an AI-authored summary of the changes, with a full list of PRs at the bottom.
Orleans now has full support for .NET's CancellationToken in grain methods, aligning with standard .NET async patterns and making it easier to handle cancellation scenarios in your grain operations.
A new high-performance storage provider that uses a log-structured approach for improved write performance and reduced storage overhead.
Introduces a database-backed grain directory implementation, providing an alternative to in-memory directory storage with support for various relational databases. This enables persistent grain location information across cluster restarts and supports larger clusters with reduced memory overhead.
Automatic grain deactivation under memory pressure helps prevent out-of-memory conditions by intelligently shedding grain activations when memory usage is high.
Enhanced placement control allowing you to filter silo selection based on custom metadata, enabling more sophisticated deployment scenarios.
ResourceOptimizedPlacement for better resource utilizationThe new ADO.NET Grain Directory (#9263) provides:
ResourceOptimizedPlacement is now the default instead of RandomPlacementRequestProcessingWarningTime and RequestQueueDelayWarningTime have higher defaultsNullReferenceException in PlacementWorker by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9386IConfiguration support for Azure Cosmos DB Clustering Provider by @OmnipotentOwl in https://github.com/dotnet/orleans/pull/9204RequestProcessingWarningTime & RequestQueueDelayWarningTime by @ReubenBond in https://github.com/dotnet/orleans/pull/9398IGrainState<T> properties by @ReubenBond in https://github.com/dotnet/orleans/pull/9417PerformUpdate method should not be called within a read-only transaction by @scalalang2 in https://github.com/dotnet/orleans/pull/9492GrainId as PropertyName by @DeagleGross in https://github.com/dotnet/orleans/pull/9494InvalidOperationException in ActivationData when cancelling operations by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9475ConcurrentLru by @ReubenBond in https://github.com/dotnet/orleans/pull/9530ResourceOptimizedPlacement by default by @ReubenBond in https://github.com/dotnet/orleans/pull/9533RuntimeMessagingTrace by @ReubenBond in https://github.com/dotnet/orleans/pull/9548EnvironmentStatistics and add assertions by @ReubenBond in https://github.com/dotnet/orleans/pull/9603IGrainLocator nullability by @ReubenBond in https://github.com/dotnet/orleans/pull/9604ORLEANS0004 severity to Error by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9576Full Changelog: https://github.com/dotnet/orleans/compare/v9.1.2...v9.2.0
chore(Orleans.Core): Use [LoggerMessage] p2 by @Meir017 in https://github.com/dotnet/orleans/pull/9540
ResourceOptimizedPlacement by default by @ReubenBond in https://github.com/dotnet/orleans/pull/9533RuntimeMessagingTrace by @ReubenBond in https://github.com/dotnet/orleans/pull/9548Full Changelog: https://github.com/dotnet/orleans/compare/v9.2.0-preview2...v9.2.0-preview3
Fix for CancelationToken cancel after finishing by @ColinBradley in https://github.com/dotnet/orleans/pull/9424
PerformUpdate method should not be called within a read-only transaction by @scalalang2 in https://github.com/dotnet/orleans/pull/9492GrainId as PropertyName by @DeagleGross in https://github.com/dotnet/orleans/pull/9494InvalidOperationException in ActivationData when cancelling operations by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9475ConcurrentLru by @ReubenBond in https://github.com/dotnet/orleans/pull/9530Full Changelog: https://github.com/dotnet/orleans/compare/v9.2.0-preview1...v9.2.0-preview2
Silo Metadata and Placement Filtering by @rkargMsft in https://github.com/dotnet/orleans/pull/9271
NullReferenceException in PlacementWorker by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9386IConfiguration support for Azure Cosmos DB Clustering Provider by @OmnipotentOwl in https://github.com/dotnet/orleans/pull/9204RequestProcessingWarningTime & RequestQueueDelayWarningTime by @ReubenBond in https://github.com/dotnet/orleans/pull/9398IGrainState<T> properties by @ReubenBond in https://github.com/dotnet/orleans/pull/9417Full Changelog: https://github.com/dotnet/orleans/compare/v9.1.2...v9.2.0-preview1
[Test] Skip flaky Rem_Azure_Basic test by @ReubenBond in https://github.com/dotnet/orleans/pull/9345
RuntimeTypeNameParser by @ReubenBond in https://github.com/dotnet/orleans/pull/9343Full Changelog: https://github.com/dotnet/orleans/compare/v9.1.1...v9.1.2
Fix packaging of Microsoft.Orleans.Sdk (#9338) by @ReubenBond in https://github.com/dotnet/orleans/pull/9339
Full Changelog: https://github.com/dotnet/orleans/compare/v9.1.0...v9.1.1
Add dependabot configuration for .NET SDK updates by @JamieMagee in https://github.com/dotnet/orleans/pull/9249
CorrelationId generation in MessageFactory by @ReubenBond in https://github.com/dotnet/orleans/pull/9300CancellationTokenSource hygiene and use preferred LINQ & StringBuilder methods by @ivanvyd in https://github.com/dotnet/orleans/pull/9080OnCompletedAsync implementations for IAsyncObserver and IAsyncBatchObserver by @bluexo in https://github.com/dotnet/orleans/pull/8783ValidateInitialConnectivity to MaxJoinAttemptTime by @ReubenBond in https://github.com/dotnet/orleans/pull/9312IServiceProvider after disposal in Catalog and MembershipGossiper by @ReubenBond in https://github.com/dotnet/orleans/pull/9334Full Changelog: https://github.com/dotnet/orleans/compare/v9.0.1...v9.1.0
Change EventCounterIntervalSec to 1 sec to fix issue caused in dotnet-counters by @ntovas in https://github.com/dotnet/orleans/pull/9235
Full Changelog: https://github.com/dotnet/orleans/compare/v9.0.0...v9.0.1
Switch to pre-built Cassandra Docker image by @rkargMsft in https://github.com/dotnet/orleans/pull/9076
IGrainWithStringKey by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9111ArgumentOutOfRangeException in LeaseBasedQueueBalancer by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9112IPEndPoint in RedisGatewayListProvider by @ReubenBond in https://github.com/dotnet/orleans/pull/9146GrainReferences with null or empty GrainInterfaceType by @ReubenBond in https://github.com/dotnet/orleans/pull/9178SendingSilo when sending messages to clients by @ReubenBond in https://github.com/dotnet/orleans/pull/9189ClientClusterManifestProvider when OutsideRuntimeClient is stopping by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9211ImmovableAttribute configurable by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9205IHashPicker customization API + Orleans v3-compatible IHashPicker implementation by @vladislav-prishchepa in https://github.com/dotnet/orleans/pull/9217Full Changelog: https://github.com/dotnet/orleans/compare/v8.2.0...v9.0.0
Avoid changing soon-to-be-deprecated RegisterTimer method return type by @ReubenBond in https://github.com/dotnet/orleans/pull/9020
!Activation Repartitioning in action
Above: a demonstration showing Activation Repartitioning in action. The red lines represent cross-silo communication. As the red lines are eliminated by the partitioning algorithm, throughput improves to over 2x the initial throughput.
Ledjon Behluli and @ReubenBond implemented activation repartitioning in #8877. When enabled, activation repartitioning collocates grains based on observed communication patterns to improve performance while keeping load balanced across your cluster. In initial benchmarks, we observe throughput improvements in the range of 30% to 110%. The following paragraphs provide more background and implementation details for those who are interested. The feature is currently experimental and to enable it you need to opt-in on every silo in your cluster using the ISiloBuilder.AddActivationRepartitioner() extension method, suppressing the experimental feature warning:
#pragma warning disable ORLEANSEXP001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
siloBuilder.AddActivationRepartitioner();
#pragma warning restore ORLEANSEXP001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
The fastest and cheapest grains calls are ones which don't cross process boundaries. These grain calls do not need to be serialized and do not need to incur network transmission costs. For that reason, collocating related grains within the same host can significantly improve the performance of your application. On the other hand, if all grains were placed in a single host, that host may become overloaded and crash, and you would not be able to scale your application across multiple hosts. How can we maximize collocation of related grains while keeping load across your hosts balanced? Before describing our solution, we need to provide some background.
Grain placement in Orleans is flexible: Orleans executes a user-defined function when deciding where in a cluster to place each grain, providing your function with a list of the compatible silos in your cluster, that is, the silos which support the grain type and interface version which triggered placement. Grains calls are location-transparent, so callers do not need to know where a grain is located, allowing grains to be placed anywhere across your cluster of hosts. Each grain's current location is stored in a distributed directory and lookups to the directory are cached for performance.
Resource-optimized placement was implemented by @ledjon-behluli in #8815. Resource-optimized placement uses runtime statistics such as total and available memory, CPU usage, and grain count, collected from all hosts in the cluster, smooths them, and combines them to calculate a load score. It selects the least-loaded silo from a subset of hosts to balance load evenly across the cluster[^4]. If the load score of the local silo is within some configured range of the best candidate's load score, the local silo is chosen preferentially. This improves grain locality by leveraging the knowledge that the local silo initiated a call to the grain and therefore has some relation to that grain. Ledjon wrote more about Resource-optimized placement in this blog post.
Originally, there was no straightforward way to move an active grain from one host to another without needing to fully deactivate the grain, unregister it from the grain directory, contend with concurrent callers on where to place the new activation, and reload its state from the database when the new activation is created. Live grain migration was introduced in #8452, allowing grains to transparently migrate from one silo to another on-demand without needing to reload state from the database, and without affecting pending requests. Live grain migration introduced two new lifecycle stages: dehydration and rehydration. The grain's in-memory state (application state, enqueued messages, metadata) is dehydrated into a migration packet which is sent to the destination silo where it's rehydrated. Live grain migration provided the mechanism for grains to migrate across hosts, but did not provide any out-of-the-box policies to automate migration. Users trigger grain migration by calling this.MigrateOnIdle() from within a grain, optionally providing a placement hint which the grain's configured placement director can use to select a destination host for the grain activation.
Finally, we have the pieces in place for activation repartitioning: grain activations are load-balanced across the cluster, and they are able to migrate from host to host quickly. While live grain migration gives developers a mechanism to migrate grain activations from one host to another, it does not provide any automated policy to do so. Remember, we want grains to be balanced across the cluster and collocated with related grains to reduce networking and serialization cost. This is a difficult challenge since:
Folks at Microsoft Research studied this problem and proposed a solution in a paper titled Optimizing Distributed Actor Systems for Dynamic Interactive Services. The paper, dubbed ActOp, proposes a decentralized approximate solution which achieves good results in their benchmarks. Their implementation was never merged into Orleans and we were unable to find the original implementation on Microsoft's internal network. So, after first implementing resource-optimized placement, community contributor @ledjon-behluli set out to implement activation repartitioning from scratch based on the ActOp paper. The following paragraphs describe the algorithm and the enhancements we made along the way.
The activation repartitioning algorithm involves pair-wise exchange of grains between two hosts at a time. Silos compute a candidate set of grains to send to a peer, then the peer does similarly, and uses a greedy algorithm to determine a final exchange set which minimizes cost while keeping silos balanced.
To compute the candidate sets, silos track which grains communicate with which other grains and how frequently. The whole graph would be unwieldy, so we only maintain the top-K communication edges using a variant of the Space-Saving[^1] algorithm. Messages are sampled via a multi-producer, single consumer ring buffer which drops messages if the partition is full. They are then processed by a single thread, which yields frequently to give other threads CPU time. When the distribution has low skew and the K parameter is fairly small, Space-Saving can require a lot of costly shuffling at the bottom of its max-heap (we use the heap variant to reduce memory). To address this, we use Filtered Space-Saving[^2] instead of Space-Saving. Filtered Space-Saving involves putting a 'sketch' data structure at the bottom of the max heap for the lower end of the distribution, which can greatly reduce churn at the bottom and improve performance by up to ~2x in our tests.
If the top-K communication edges are all internal (eg, because the algorithm has already optimized partitioning somewhat), silos won't find many good transfer candidates. We need to track internal edges to work out which grains should/shouldn't be transferred (cost vs benefit). To address this, we introduced a bloom filter to track grains where the cost of movement is greater than the benefit, removing them from the top-K data structure. From our experiments, this works very well with even a 10x smaller K. This performance improvement will come with a reduced ability to handle dynamic graphs, so in the future we may need to implement a decay strategy to address this as the bloom filter becomes saturated. To improve lookup performance, @ledjon-behluli implemented a blocked bloom filter[^3], which is used instead of a classic bloom filter.
[^1]: Efficient Computation of Frequent and Top-k Elements in Data Streams by Metwally, Agrawal, and Abbadi [^2]: Finding top-k elements in data streams by Nuno Homem & Joao Paulo Carvalho [^3]: Cache-, Hash- and Space-Efficient Bloom Filters by Felix Putze, Peter Sanders and Johannes Single [^4]: The Power of Two Choices in Randomized Load Balancing by Michael David Mitzenmacher
Orleans v8.2.0 introduces a new API, RegisterGrainTimer, for managing grain timers. For compatibility, the existing RegisterTimer API is still available, but it is marked [Obsolete] and developers should migrate to the new grain timer API, RegisterGrainTimer.
Grain timers have been a common source of confusion for new and experienced developers because grain timer callbacks can execute concurrently with other grain calls, rather than being executed one-by-one like grain calls are. That is, timer callbacks are interleaving. With v8.2.0, this issue can be avoided by using the new RegisterGrainTimer API. The new API has the following advantages:
Change(TimeSpan, TimeSpan) method on the returned IGrainTimer instance.Interleave to true on GrainTimerCreationOptions.KeepAlive to true on GrainTimerCreationOptions.CancellationToken which is canceled when the timer is disposed or the grain starts to deactivate.Grain) can register grain timers using the RegisterGrainTimer extension method.The core API is as-follows:
public static IGrainTimer RegisterGrainTimer<TState>(this IGrainBase grain, Func<TState, CancellationToken, Task> callback, TState state, GrainTimerCreationOptions options);
There are various overloads for convenience:
public static IGrainTimer RegisterGrainTimer<TState>(this IGrainBase grain, Func<TState, CancellationToken, Task> callback, TState state, GrainTimerCreationOptions options);
public static IGrainTimer RegisterGrainTimer(this IGrainBase grain, Func<CancellationToken, Task> callback, GrainTimerCreationOptions options);
public static IGrainTimer RegisterGrainTimer(this IGrainBase grain, Func<Task> callback, GrainTimerCreationOptions options);
public static IGrainTimer RegisterGrainTimer<TState>(this IGrainBase grain, Func<TState, Task> callback, TState state, GrainTimerCreationOptions options);
public static IGrainTimer RegisterGrainTimer(this IGrainBase grain, Func<Task> callback, TimeSpan dueTime, TimeSpan period);
public static IGrainTimer RegisterGrainTimer(this IGrainBase grain, Func<CancellationToken, Task> callback, TimeSpan dueTime, TimeSpan period);
public static IGrainTimer RegisterGrainTimer<TState>(this IGrainBase grain, Func<TState, Task> callback, TState state, TimeSpan dueTime, TimeSpan period);
public static IGrainTimer RegisterGrainTimer<TState>(this IGrainBase grain, Func<TState, CancellationToken, Task> callback, TState state, TimeSpan dueTime, TimeSpan period);
The RegisterGrainTimer API returns instances of IGrainTimer instead of IDisposable:
/// <summary>
/// Represents a timer belonging to a grain.
/// </summary>
public interface IGrainTimer : IDisposable
{
/// <summary>Changes the start time and the interval between method invocations for a timer, using <see cref="TimeSpan"/> values to measure time intervals.</summary>
/// <param name="dueTime">
/// A <see cref="TimeSpan"/> representing the amount of time to delay before invoking the callback method specified when the <see cref="IGrainTimer"/> was constructed.
/// Specify <see cref="Timeout.InfiniteTimeSpan"/> to prevent the timer from restarting.
/// Specify <see cref="TimeSpan.Zero"/> to restart the timer immediately.
/// </param>
/// <param name="period">
/// The time interval between invocations of the callback method specified when the timer was constructed.
/// Specify <see cref="Timeout.InfiniteTimeSpan"/> to disable periodic signaling.
/// </param>
/// <exception cref="ArgumentOutOfRangeException">The <paramref name="dueTime"/> or <paramref name="period"/> parameter, in milliseconds, is less than -1 or greater than 4294967294.</exception>
void Change(TimeSpan dueTime, TimeSpan period);
}
@n-sidorov implemented support for serializing messages using MessagePack.
To use MessagePack for message serialization, you will need to install Microsoft.Orleans.Serialization.MessagePack by inserting the following into your project files:
<ItemGroup>
<PackageReference Include="Microsoft.Orleans.Serialization.MessagePack" Version="8.2.0" />
</ItemGroup>
Enable MessagePack serialization by calling ISerializerBuilder.AddMessagePackSerializer() on your clients and silos:
builder.AddSerializer(serializer => serializer.AddMessagePackSerializer());
Upon doing so, Orleans will be able to serialize types with the [MessagePackObject] attribute, for example:
[MessagePackObject]
public sealed record MyMessagePackClass
{
[Key(0)]
public int IntProperty { get; init; }
[Key(1)]
public string StringProperty { get; init; }
[Key(2)]
public MyMessagePackSubClass SubClass { get; init; }
}
@rkargMsft implemented support for using Cassandra as a backing store for clustering in https://github.com/dotnet/orleans/pull/8925.
To use Cassandra for clustering, you will need to install Microsoft.Orleans.Clustering.Cassandra by inserting the following into your project files:
<ItemGroup>
<PackageReference Include="Microsoft.Orleans.Clustering.Cassandra" Version="8.2.0" />
</ItemGroup>
On your clients and silos, you can enable Cassandra clustering by calling:
builder.UseCassandraClustering(connectionString);
@JorgeCandeias implemented an ADO.NET streams provider in https://github.com/dotnet/orleans/pull/8974.
ADO.NET streaming is currently an alpha version. You can add it to your project files like so:
<ItemGroup>
<PackageReference Include="Microsoft.Orleans.Streaming.AdoNet" Version="8.2.0-alpha.1" />
</ItemGroup>
Configure ADO.NET streaming like so:
builder.AddAdoNetStreams("provider name", options =>
{
options.Invariant = "ADO.NET invariant name";
options.ConnectionString = "Connection string";
});
SafeTimer usage, replace with PeriodicTimer where possible by @ReubenBond in https://github.com/dotnet/orleans/pull/8953Dictionary<K,V> which add values in their constructor by @ReubenBond in https://github.com/dotnet/orleans/pull/8993ConsistentRingProvider & VirtualBucketsRingProvider from ISiloStatusOracle on shutdown by @ReubenBond in https://github.com/dotnet/orleans/pull/8997Interlocked.Or in SingleWaiterAutoResetEvent by @ReubenBond in https://github.com/dotnet/orleans/pull/9003List<T> and HashSet<T> by @ReubenBond in https://github.com/dotnet/orleans/pull/9005PeriodicTimer instead of GrainTimer in LeaseBasedQueueBalancer by @ReubenBond in https://github.com/dotnet/orleans/pull/9002ActivationData shutdown process by @ReubenBond in https://github.com/dotnet/orleans/pull/9018StringData in ATS provider by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8965MaxAvailableMemory, add ActivationCount factor by @ReubenBond in https://github.com/dotnet/orleans/pull/9028PersistentStreamPullingAgent by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9035MayInterleave with StatelessWorker grains by @ledjon-behluli in https://github.com/dotnet/orleans/pull/9050RemoveStaleConditionalUpdates by @zbarrier in https://github.com/dotnet/orleans/pull/8623null for no-op message observer to avoid interface call by @ReubenBond in https://github.com/dotnet/orleans/pull/9056GetHashCode implementations with HashCode.Combine by @ReubenBond in https://github.com/dotnet/orleans/pull/9059Full Changelog: https://github.com/dotnet/orleans/compare/v8.1.0...v8.2.0
Fix potential grain timer deadlock during disposal by @ReubenBond in https://github.com/dotnet/orleans/pull/8950
SafeTimer usage, replace with PeriodicTimer where possible by @ReubenBond in https://github.com/dotnet/orleans/pull/8953Dictionary<K,V> which add values in their constructor by @ReubenBond in https://github.com/dotnet/orleans/pull/8993ConsistentRingProvider & VirtualBucketsRingProvider from ISiloStatusOracle on shutdown by @ReubenBond in https://github.com/dotnet/orleans/pull/8997Interlocked.Or in SingleWaiterAutoResetEvent by @ReubenBond in https://github.com/dotnet/orleans/pull/9003List<T> and HashSet<T> by @ReubenBond in https://github.com/dotnet/orleans/pull/9005PeriodicTimer instead of GrainTimer in LeaseBasedQueueBalancer by @ReubenBond in https://github.com/dotnet/orleans/pull/9002ActivationData shutdown process by @ReubenBond in https://github.com/dotnet/orleans/pull/9018Full Changelog: https://github.com/dotnet/orleans/compare/v8.1.0...v8.2.0-preview1
This release includes initial integration with .NET Aspire, allowing you to configure an Orleans cluster in your Aspire app host, specifying the resou
This release includes initial integration with .NET Aspire, allowing you to configure an Orleans cluster in your Aspire app host, specifying the resources the cluster uses. For example, you can specify that an Azure Table will be used for cluster membership, an Azure Redis resource will be used for the grain directory, and an Azure Blob Storage resource will be used to store grain state. The integration currently supports Redis and Azure Table & Blob storage resources. Support for other resources will be added later.
In the app host project, an Orleans cluster can be declared using the AddOrleans method, and then configured with clustering, grain storage, grain directory, and other providers using methods on the returned builder:
var storage = builder.AddAzureStorage("storage");
var clusteringTable = storage.AddTables("clustering");
var defaultStorage = storage.AddBlobs("grainstate");
var cartStorage = builder.AddRedis("redis-cart");
var orleans = builder.AddOrleans("my-app")
.WithClustering(clusteringTable)
.WithGrainStorage("Default", grainStorage)
.WithGrainStorage("cart", cartStorage);
// Add a server project (also called "silo")
builder.AddProject<Projects.OrleansServer>("silo")
.WithReference(orleans);
// Add a project with a reference to the Orleans client
builder.AddProject<Projects.FrontEnd>("frontend")
.WithReference(orleans);
In the client and server projects, add Orleans to the host builder as usual.
// For an Orleans server:
builder.UseOrleans();
// Or, for an Orleans client:
builder.UseOrleansClient();
Orleans will read configuration created by your Aspire app host project and configure the providers specified therein. To allow Orleans to access the configured resources, add them as keyed services using the corresponding Aspire component:
builder.AddKeyedAzureTableService("clustering");
builder.AddKeyedAzureBlobService("grainstate");
builder.AddKeyedRedis("redis-cart");
Resource-optimized placement, enabled via the [ResourceOptimizedPlacement] attribute on a grain class, balances grains across hosts based on available memory and CPU usage. For more details, see the PR: https://github.com/dotnet/orleans/pull/8815.
ResourceOptimizedPlacementOptions to Orleans.Configuration by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8892StatelessWorkerAttribute.MaxLocal property is accounted for by @ReubenBond in https://github.com/dotnet/orleans/pull/8885PooledBuffer serialization by @ReubenBond in https://github.com/dotnet/orleans/pull/8852RuntimeContext to previous value after use by @ReubenBond in https://github.com/dotnet/orleans/pull/8864LinearBackoffClientConnectionRetryFilter in the default client services by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8793GenerateAliasAttribtuesAnalyzer needs to account for file-scoped namespaces by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8809System.Data.SqlClient by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8821OverloadDetector to account for memory too by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8820RedisMembershipTable by @ReubenBond in https://github.com/dotnet/orleans/pull/8848Full Changelog: https://github.com/dotnet/orleans/compare/v8.0.0...v8.1.0
Clean up WorkItemGroup and ActivationTaskScheduler logic by @ReubenBond in https://github.com/dotnet/orleans/pull/8865
ResourceOptimizedPlacementOptions to Orleans.Configuration by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8892StatelessWorkerAttribute.MaxLocal property is accounted for by @ReubenBond in https://github.com/dotnet/orleans/pull/8885Full Changelog: https://github.com/dotnet/orleans/compare/v8.1.0-preview2...v8.1.0-preview3
Fix PooledBuffer serialization by @ReubenBond in https://github.com/dotnet/orleans/pull/8852
PooledBuffer serialization by @ReubenBond in https://github.com/dotnet/orleans/pull/8852RuntimeContext to previous value after use by @ReubenBond in https://github.com/dotnet/orleans/pull/8864Full Changelog: https://github.com/dotnet/orleans/compare/v8.1.0-preview1...v8.1.0-preview2
This release includes initial integration with Aspire Preview 3 and later, allowing you to configure an Orleans cluster in your Aspire app host, speci
This release includes initial integration with Aspire Preview 3 and later, allowing you to configure an Orleans cluster in your Aspire app host, specifying the resources the cluster uses. For example, you can specify that an Azure Table will be used for cluster membership, an Azure Redis resource will be used for the grain directory, and an Azure Blob Storage resource will be used to store grain state. The integration currently support Redis and Azure Table & Blob storage resources. Support for other resources will be added later.
In the app host project, an Orleans cluster can be declared using the AddOrleans method, and then configured with clustering, grain storage, grain directory, and other providers using methods on the returned builder:
var storage = builder.AddAzureStorage("storage");
var clusteringTable = storage.AddTables("clustering");
var defaultStorage = storage.AddBlobs("grainstate");
var cartStorage = builder.AddRedis("redis-cart");
var orleans = builder.AddOrleans("my-app")
.WithClustering(clusteringTable)
.WithGrainStorage("Default", grainStorage)
.WithGrainStorage("cart", cartStorage);
// Add a server project (also called "silo")
builder.AddProject<Projects.OrleansServer>("silo")
.WithReference(orleans);
// Add a project with a reference to the Orleans client
builder.AddProject<Projects.FrontEnd>("frontend")
.WithReference(orleans);
In the client and server projects, add Orleans to the host builder as usual.
// For an Orleans server:
builder.UseOrleans();
// Or, for an Orleans client:
builder.UseOrleansClient();
Orleans will read configuration created by your Aspire app host project and configure the providers specified therein. To allow Orleans to access the configured resources, add them as keyed services using the corresponding Aspire component:
builder.AddKeyedAzureTableService("clustering");
builder.AddKeyedAzureBlobService("grainstate");
builder.AddKeyedRedis("redis-cart");
Resource-optimized placement, enabled via the [ResourceOptimizedPlacement] attribute on a grain class, balances grains across hosts based on available memory and CPU usage. For more details, see the PR: https://github.com/dotnet/orleans/pull/8815.
LinearBackoffClientConnectionRetryFilter in the default client services by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8793GenerateAliasAttribtuesAnalyzer needs to account for file-scoped namespaces by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8809System.Data.SqlClient by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8821OverloadDetector to account for memory too by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8820RedisMembershipTable by @ReubenBond in https://github.com/dotnet/orleans/pull/8848Full Changelog: https://github.com/dotnet/orleans/compare/v8.0.0...v8.1.0-preview1
Fix version suffix in build.yaml by @benjaminpetit in https://github.com/dotnet/orleans/pull/8113
EndpointOptions by @IEvangelist in https://github.com/dotnet/orleans/pull/8209AddJsonSerializer by @ReubenBond in https://github.com/dotnet/orleans/pull/8228Collection<T> serialization codec by @ReubenBond in https://github.com/dotnet/orleans/pull/8238IGrainStorageSerializer for memory grain storage by @shoneefd in https://github.com/dotnet/orleans/pull/8250DeleteStateOnClear for Redis grain storage. by @ReubenBond in https://github.com/dotnet/orleans/pull/8296PooledArrayBufferWriter.AsMemory by @ReubenBond in https://github.com/dotnet/orleans/pull/8300IGrainFactory.GetGrain<T> for unimplemented generic interfaces by @ReubenBond in https://github.com/dotnet/orleans/pull/8301ActivationWorkingSet by @ReubenBond in https://github.com/dotnet/orleans/pull/8321null in constructor by @bradygaster in https://github.com/dotnet/orleans/pull/8358FormatterServices to RuntimeHelpers in preparation for .NET 8 by @ReubenBond in https://github.com/dotnet/orleans/pull/8362DefaultOptionsFormatter and DefaultOptionsFormatterResolver by @ReubenBond in https://github.com/dotnet/orleans/pull/8384DefaultStreamIdMapper by @nichvolodov in https://github.com/dotnet/orleans/pull/8378IAsyncEnumerable<T> support for grain calls by @ReubenBond in https://github.com/dotnet/orleans/pull/8416PooledArrayBufferWriter more versatile, rename by @ReubenBond in https://github.com/dotnet/orleans/pull/8453void methods: VoidRequest implies OneWay by @ReubenBond in https://github.com/dotnet/orleans/pull/8468HostApplicationBuilder extensions by @IEvangelist in https://github.com/dotnet/orleans/pull/8466UsingDirective insertion in [NonSerialized] codefix by @ReubenBond in https://github.com/dotnet/orleans/pull/8557readonly where applicable by @ReubenBond in https://github.com/dotnet/orleans/pull/8587required members by @ReubenBond in https://github.com/dotnet/orleans/pull/8595[RegexImplicitChannelSubscription(...)] and [RegexImplicitStreamSubscription(...)] by @ReubenBond in https://github.com/dotnet/orleans/pull/8597ImplicitStreamSubscriptionAttribute.StreamIdMapper to be initialized by subclasses by @ReubenBond in https://github.com/dotnet/orleans/pull/8592ClusterMembershipOptions.NumVotesForDeathDeclaration is not greater than NumProbedSilos on startup by @ReubenBond in https://github.com/dotnet/orleans/pull/8679CollectionAgeLimitAttribute by @ReubenBond in https://github.com/dotnet/orleans/pull/8681Service comment by @qin-guan in https://github.com/dotnet/orleans/pull/8745CompoundTypeAliasTree with isolated base interface(s) by @ledjon-behluli in https://github.com/dotnet/orleans/pull/8788Full Changelog: https://github.com/dotnet/orleans/compare/v7.0.0...v8.0.0
Fix potential grain timer deadlock during disposal by @ReubenBond in https://github.com/dotnet/orleans/pull/8951
Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.6...v7.2.7
Fix StatelessWorker MaxLocal for Orleans 7.x by @isaachili in https://github.com/dotnet/orleans/pull/8887
Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.5...v7.2.6
Avoid resending unchanged ClusterManifest to clients by @ReubenBond in https://github.com/dotnet/orleans/pull/8772
PooledBuffer serialization & initialize ActivationMigrationManager on startup by @ReubenBond in https://github.com/dotnet/orleans/pull/8861Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.4...v7.2.5
Avoid hiding the stack of exceptions thrown from user code by @ReubenBond in https://github.com/dotnet/orleans/pull/8706
Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.3...v7.2.4
Add value type support to IActivator #8682 by @AdrianoAE in https://github.com/dotnet/orleans/pull/8683
ClusterMembershipOptions.NumVotesForDeathDeclaration is not greater than NumProbedSilos on startup by @ReubenBond in https://github.com/dotnet/orleans/pull/8679CollectionAgeLimitAttribute by @ReubenBond in https://github.com/dotnet/orleans/pull/8681Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.2...v7.2.3
Added support for instanced versions of MayInterleave predicates by @blazknuplez in https://github.com/dotnet/orleans/pull/8548
MayInterleave predicates by @blazknuplez in https://github.com/dotnet/orleans/pull/8548Dictionary<K,V> by @ReubenBond in https://github.com/dotnet/orleans/pull/8552DefaultGrainActivator and GrainConstructorArgumentFactory for customization by @ReubenBond in https://github.com/dotnet/orleans/pull/8550ValueTuple tests by @Romanx in https://github.com/dotnet/orleans/pull/8566ISpanParsable on to GrainId by @Romanx in https://github.com/dotnet/orleans/pull/8565UsingDirective insertion in [NonSerialized] codefix by @ReubenBond in https://github.com/dotnet/orleans/pull/8557IGrainDirectory and implementers. by @Romanx in https://github.com/dotnet/orleans/pull/8570IGrainReminder in GrainReminderExtensions by @JRWinter1 in https://github.com/dotnet/orleans/pull/8544CachedGrainLocator Unregister Ordering by @JohnMorman in https://github.com/dotnet/orleans/pull/8547StreamId keys by @AdrianoAE in https://github.com/dotnet/orleans/pull/8578readonly where applicable by @ReubenBond in https://github.com/dotnet/orleans/pull/8587IRemoteGrainDirectory API by @ReubenBond in https://github.com/dotnet/orleans/pull/8593required members by @ReubenBond in https://github.com/dotnet/orleans/pull/8595PubSubPublisherState by @ReubenBond in https://github.com/dotnet/orleans/pull/8594TimeSpan string syntax by @ReubenBond in https://github.com/dotnet/orleans/pull/8596[RegexImplicitChannelSubscription(...)] and [RegexImplicitStreamSubscription(...)] by @ReubenBond in https://github.com/dotnet/orleans/pull/8597ImplicitStreamSubscriptionAttribute.StreamIdMapper to be initialized by subclasses by @ReubenBond in https://github.com/dotnet/orleans/pull/8592IActivator<T> instead of Activator.CreateInstance to handle unserializable types by @AdrianoAE in https://github.com/dotnet/orleans/pull/8626GrainDirectoryResolver, replace HasNonDefaultDirectory with IsUsingDhtDirectory by @benjaminpetit in https://github.com/dotnet/orleans/pull/8660Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.1...v7.2.2
Fix Cosmos DB grain storage constructor for DI by @ReubenBond in https://github.com/dotnet/orleans/pull/8539
Full Changelog: https://github.com/dotnet/orleans/compare/v7.2.0...v7.2.1
Redis providers are now marked as stable. Note that there is a breaking change in Redis grain state storage from the beta releases. The break can be a…
IAsyncEnumerable<T> (PR: https://github.com/dotnet/orleans/pull/8416)IAsyncEnumerable<T> support for grain calls by @ReubenBond in https://github.com/dotnet/orleans/pull/8416PooledArrayBufferWriter more versatile, rename by @ReubenBond in https://github.com/dotnet/orleans/pull/8453void methods: VoidRequest implies OneWay by @ReubenBond in https://github.com/dotnet/orleans/pull/8468HostApplicationBuilder extensions by @IEvangelist in https://github.com/dotnet/orleans/pull/8466Full Changelog: https://github.com/dotnet/orleans/compare/v7.1.2...v7.2.0
Prevent analyzer exception on aliased attribute names by @tboby in https://github.com/dotnet/orleans/pull/8355
null in constructor by @bradygaster in https://github.com/dotnet/orleans/pull/8358FormatterServices to RuntimeHelpers in preparation for .NET 8 by @ReubenBond in https://github.com/dotnet/orleans/pull/8362DefaultOptionsFormatter and DefaultOptionsFormatterResolver by @ReubenBond in https://github.com/dotnet/orleans/pull/8384DefaultStreamIdMapper by @nichvolodov in https://github.com/dotnet/orleans/pull/8378Full Changelog: https://github.com/dotnet/orleans/compare/v7.1.1...v7.1.2
Fix Issue #8325 Redis options-validators unable to resolve options by @zeinali0 in https://github.com/dotnet/orleans/pull/8326
ITypeFilter and ITypeNameFilter by @ReubenBond in https://github.com/dotnet/orleans/pull/8328ActivationWorkingSet by @ReubenBond in https://github.com/dotnet/orleans/pull/8321Full Changelog: https://github.com/dotnet/orleans/compare/v7.1.0...v7.1.1
The Orleans release team would like to thank everyone who contributed issues, PRs, reviews, and comments.
The Orleans release team would like to thank everyone who contributed issues, PRs, reviews, and comments.
Collection<T> (https://github.com/dotnet/orleans/pull/8238)IGrainStorageSerializer in memory storage (https://github.com/dotnet/orleans/pull/8250)EndpointOptions by @IEvangelist in https://github.com/dotnet/orleans/pull/8209AddJsonSerializer by @ReubenBond in https://github.com/dotnet/orleans/pull/8228Collection<T> serialization codec by @ReubenBond in https://github.com/dotnet/orleans/pull/8238IGrainStorageSerializer for memory grain storage by @shoneefd in https://github.com/dotnet/orleans/pull/8250DeleteStateOnClear for Redis grain storage. by @ReubenBond in https://github.com/dotnet/orleans/pull/8296PooledArrayBufferWriter.AsMemory by @ReubenBond in https://github.com/dotnet/orleans/pull/8300IGrainFactory.GetGrain<T> for unimplemented generic interfaces by @ReubenBond in https://github.com/dotnet/orleans/pull/8301Full Changelog: https://github.com/dotnet/orleans/compare/v7.0.0...v7.1.0
Update release notes for 3.3.0 to reflect the fact that addition of RecordExists is a potentially breaking change by @sergeybykov in https://github.co…
Release announcement post: https://devblogs.microsoft.com/dotnet/whats-new-in-orleans-7/ Migration notes: https://learn.microsoft.com/en-us/dotnet/orleans/whats-new-in-orleans
ServiceUrl when region is provided. by @icanhasjonas in https://github.com/dotnet/orleans/pull/6327UseProvisionedThroughput by @icanhasjonas in https://github.com/dotnet/orleans/pull/6328Catalog and ActivationDirectory by @ReubenBond in https://github.com/dotnet/orleans/pull/7231CoarseStopwatch using Environment.TickCount64 and use on hot paths by @ReubenBond in https://github.com/dotnet/orleans/pull/7246ConcurrentObjectPool instead of DefaultObjectPool by @ReubenBond in https://github.com/dotnet/orleans/pull/7247ValueTask methods by @ReubenBond in https://github.com/dotnet/orleans/pull/7250MemoryStreamBufferWriter by @ReubenBond in https://github.com/dotnet/orleans/pull/7270PersistentStreamPullingAgent instances by @ReubenBond in https://github.com/dotnet/orleans/pull/7263Response.ToString() by @ReubenBond in https://github.com/dotnet/orleans/pull/7296IGrainStorage in DI unless there is a provider named "Default" by @ReubenBond in https://github.com/dotnet/orleans/pull/7409CpuLimit if deltaTotalTime is zero in LinuxEnvironmentStatistics by @ElanHasson in https://github.com/dotnet/orleans/pull/7526servideId -> serviceId by @khalidabuhakmeh in https://github.com/dotnet/orleans/pull/7559IGrainFactory.CreateObjectReference and IGrainFactory.DeleteObjectReference synchronous by @benjaminpetit in https://github.com/dotnet/orleans/pull/7552PerformanceTuningOptions by @ReubenBond in https://github.com/dotnet/orleans/pull/7586IGrainCallContext for distributed tracing by @ReubenBond in https://github.com/dotnet/orleans/pull/7646LocalGrainDirectory calls while shutting down by @ReubenBond in https://github.com/dotnet/orleans/pull/7670AzureGrainDirectory and AzureTableDataManager tests in emulator by @ReubenBond in https://github.com/dotnet/orleans/pull/7729ServiceCollectionExtensions.AddFromExisting when ... by @ElanHasson in https://github.com/dotnet/orleans/pull/7724is not null over is object by @ReubenBond in https://github.com/dotnet/orleans/pull/7779ExecutionContext when interacting with reminders by @ReubenBond in https://github.com/dotnet/orleans/pull/7789GrainType and GrainInterfaceType by @ReubenBond in https://github.com/dotnet/orleans/pull/7821IConsistentRingProvider implementations should notify immediately on subscribe by @ReubenBond in https://github.com/dotnet/orleans/pull/7847LocalReminderService, and tests by @ReubenBond in https://github.com/dotnet/orleans/pull/7855Microsoft.Orleans.OrleansRuntime package to Microsoft.Orleans.Runtime by @ReubenBond in https://github.com/dotnet/orleans/pull/7912Message object by @ReubenBond in https://github.com/dotnet/orleans/pull/7857ActivationDataExtra to reduce overhead by @ReubenBond in https://github.com/dotnet/orleans/pull/7976StatelessWorkerGrainContext.GetComponent implementation. by @ReubenBond in https://github.com/dotnet/orleans/pull/7975scoped refs) & migrate to .NET 7.0 by @ReubenBond in https://github.com/dotnet/orleans/pull/7987Note truncated.
Don't set CpuLimit if deltaTotalTime is zero in LinuxEnvironmentStatistics by @ElanHasson in https://github.com/dotnet/orleans/pull/7526
CpuLimit if deltaTotalTime is zero in LinuxEnvironmentStatistics by @ElanHasson in https://github.com/dotnet/orleans/pull/7526servideId -> serviceId by @khalidabuhakmeh in https://github.com/dotnet/orleans/pull/7559IGrainFactory.CreateObjectReference and IGrainFactory.DeleteObjectReference synchronous by @benjaminpetit in https://github.com/dotnet/orleans/pull/7552PerformanceTuningOptions by @ReubenBond in https://github.com/dotnet/orleans/pull/7586IGrainCallContext for distributed tracing by @ReubenBond in https://github.com/dotnet/orleans/pull/7646LocalGrainDirectory calls while shutting down by @ReubenBond in https://github.com/dotnet/orleans/pull/7670AzureGrainDirectory and AzureTableDataManager tests in emulator by @ReubenBond in https://github.com/dotnet/orleans/pull/7729ServiceCollectionExtensions.AddFromExisting when ... by @ElanHasson in https://github.com/dotnet/orleans/pull/7724is not null over is object by @ReubenBond in https://github.com/dotnet/orleans/pull/7779ExecutionContext when interacting with reminders by @ReubenBond in https://github.com/dotnet/orleans/pull/7789GrainType and GrainInterfaceType by @ReubenBond in https://github.com/dotnet/orleans/pull/7821IConsistentRingProvider implementations should notify immediately on subscribe by @ReubenBond in https://github.com/dotnet/orleans/pull/7847LocalReminderService, and tests by @ReubenBond in https://github.com/dotnet/orleans/pull/7855Full Changelog: https://github.com/dotnet/orleans/compare/v4.0.0-preview1...v4.0.0-preview2
Update release notes for 3.3.0 to reflect the fact that addition of RecordExists is a potentially breaking change by @sergeybykov in https://github.co…
The full change log lists around 500 changes, and many involve small quality of life improvements, internal refactorings for performance, reliability, versatility, and maintainability. What follows are the larger changes which we would like to highlight in these release notes since they are more likely to impact application developers.
Grain identities now take the form type/key where both type and key are strings. This greatly simplifies how grain identity works and improves support for generic grain types.
Previous versions of Orleans used a compound type for GrainIds in order to support grain keys of either: Guid, long, string, Guid + string, or long + string. This involves some complexity when it comes to dealing with grain keys. Grain identities consist of two components: a type and a key. The type component previously consisted of a numeric type code, a category, and 3 bytes of generic type information.
Streams are also now identified using a string instead of a Guid, which grants more flexibility, especially when working with declarative subscriptions (most commonly accessed via the [ImplicitStreamSubscription(...)] attribute)
This move to stringly-typed ids is expected to be easier for developers to work with, particularly since the GrainId and StreamId types are now public (they were internal) and GrainId is able to identify any grain.
4.x changes how serialization works. The default serializer in previous releases of Orleans is not tolerant to changes in a type's schema. Adding, removing, or renaming a field or type could cause serialization to break without obvious recourse. In 4.x, we introduce a new version-tolerant serializer which allows adding/removing/renaming fields and some type change operations (widening or narrowing a numeric type, for example). We still recommended that developers use JSON serialization for persistence. The new serializer is also designed for high performance and as a result, it is substantially faster than the serializer which it replaces.
Aside from serialization, the remote procedure call internals have been overhauled for performance and flexibility. Previous versions of Orleans use a type called InvokeMethodRequest which identifies the interface and method being invoked using generated integer values and contain an array of objects representing the arguments. The InvokeMethodRequest object is passed to a generated IGrainMethodInvoker implementation which essentially contains some nested switch statements to find the correct method to invoke, then casts the arguments in the object array to the correct types in the invocation. This design has several drawbacks:
int, DateTimeOffset, and user-defined structsInstead, the replacement (which lives in Microsoft.Orleans.Serialization) involves generating an implementation of IInvokable for every method. This interface gives infrastructure components like grain filters enough information to see interface and method information as well as to inspect and manipulate arguments and return values. It is also more efficient to serialize and invoke and relies on the C# compiler to perform method overloading. Generic parameters from generic grain interfaces and generic methods become generic parameters of the implementation, avoiding or offloading most of the complexities involved with generics.
[GenerateSerializer] attribute, with any serializable property or field marked with the corresponding [Id(x)] attribute. This is intentionally less magical than in previous versions of Orleans, which did its best to infer what types needed to have serializers generated for them. What this extra ceremony buys you is valuable, though: version tolerance.GrainId and StreamId are so different, persistence, streams, and reminders are not forward-compatible yet.Here is an example of a type which Orleans would generate a serializer for previously, versus how that same type should be written for Orleans 4.0:
Orleans 3.x and below:
[Serializable]
public class UserProfile
{
public string DisplayName { get; set; }
public string PreferredLanguage { get; set; }
public DateTimeOffset AccountCreated { get; set; }
}
Orleans 4.x and above:
[GenerateSerializer]
public class UserProfile
{
[Id(0)]
public string DisplayName { get; set; }
[Id(1)]
public string PreferredLanguage { get; set; }
[Id(2)]
public DateTimeOffset AccountCreated { get; set; }
}
We have included some analyzers to make this process easier for developers. The first code fix prompts you to add the [GenerateSerializer] attribute for any type which has the [Serializable] attribute:
The second analyzer will add [Id(x)] attributes for you:
ServiceUrl when region is provided. by @icanhasjonas in https://github.com/dotnet/orleans/pull/6327UseProvisionedThroughput by @icanhasjonas in https://github.com/dotnet/orleans/pull/6328Catalog and ActivationDirectory by @ReubenBond in https://github.com/dotnet/orleans/pull/7231CoarseStopwatch using Environment.TickCount64 and use on hot paths by @ReubenBond in https://github.com/dotnet/orleans/pull/7246ConcurrentObjectPool instead of DefaultObjectPool by @ReubenBond in https://github.com/dotnet/orleans/pull/7247ValueTask methods by @ReubenBond in https://github.com/dotnet/orleans/pull/7250MemoryStreamBufferWriter by @ReubenBond in https://github.com/dotnet/orleans/pull/7270PersistentStreamPullingAgent instances by @ReubenBond in https://github.com/dotnet/orleans/pull/7263Response.ToString() by @ReubenBond in https://github.com/dotnet/orleans/pull/7296IGrainStorage in DI unless there is a provider named "Default" by @ReubenBond in https://github.com/dotnet/orleans/pull/7409Full Changelog: https://github.com/dotnet/orleans/compare/v3.0.0...v4.0.0-preview1
One column per quarter.