Orleans migration guides

Use the guide that matches the Orleans major version currently deployed in production.

Starting version	Recommended path	Guide
Orleans 9.x	Update to the latest 9.x patch, then upgrade to Orleans 10.x	Upgrade Orleans 9.x to 10.x
Orleans 8.x	Update to Orleans 8.2, validate Orleans 9.2, then upgrade to Orleans 10.x	Upgrade Orleans 8.x to 10.x
Orleans 7.x	Update to the latest 7.2 patch, then validate each supported major-version checkpoint	Upgrade Orleans 7.x to 10.x
Orleans 3.x or earlier	Migrate to Orleans 7 in a separate cluster before continuing sequentially	Archived Orleans 3.x to 7.x notes

Important

Orleans documents mixed-version deployment safety only within one major-version family. Don’t put Orleans 9 and Orleans 10 silos in the same production cluster without completing your own compatibility qualification. The guides use a parallel-cluster deployment as the safe default for crossing major versions.

What every upgrade must preserve

Before changing packages, record the following compatibility contract:

• The Orleans, .NET, provider, and database versions currently deployed.
• The grain interface and serialized type assemblies used by every silo and client.
• Stable serializer member IDs and type aliases for data in grain storage, streams, reminders, and queued messages.
• The clustering, persistence, reminder, stream, and grain-directory providers and their schema versions.
• Explicit values for behavior-sensitive options, including request cancellation, placement, grain directory caching, and timer interleaving.
• A backup or recovery point for durable state and provider metadata.

See Upgrade deployment and rollback before choosing a deployment strategy.

POCO grains and IGrainBase

POCO grains remain supported. A grain that doesn’t inherit from Grain implements IGrainBase and receives its IGrainContext through dependency injection. This also enables grain extension methods such as timers, reminders, streaming, deactivation, and migration.

Package version policy

Keep all Microsoft.Orleans.* packages on the same 10.x patch. For solutions that use NuGet Central Package Management, declare the versions in Directory.Packages.props and omit versions from project-level PackageReference items. Don’t copy old provider dependency versions from migration examples; select a current version that is supported by your target runtime and provider.

For related guidance, see:

• Orleans serialization
• Deploy new versions of grains
• ADO.NET provider configuration
• Deployment troubleshooting