Upgrade Orleans 7.x to 10.x

Starting and target assumptions

This guide assumes:

• The application first updates to the latest Orleans 7.2 patch.
• The application can retarget from .NET 7 to .NET 8 before adopting Orleans 8.
• Each major-version checkpoint can be deployed and validated independently.
• The application already uses the Orleans 7 package, hosting, identity, and serialization model.

The supported checkpoint sequence is:

1. Latest Orleans 7.2 on the application’s current runtime.
2. Latest Orleans 8.2 on .NET 8.
3. Latest Orleans 9.2 on .NET 8.
4. Current Orleans 10.x on .NET 8 or .NET 10.

Don’t combine the .NET retarget, Orleans package update, provider migration, and application contract changes in one production deployment.

Prepare the Orleans 7 application

Before moving to Orleans 8:

• Align all Microsoft.Orleans.* packages on the same latest 7.2 patch.
• Remove obsolete APIs and resolve analyzer warnings.
• Confirm silos use Microsoft.Orleans.Server, clients use Microsoft.Orleans.Client, and shared contract projects use Microsoft.Orleans.Sdk.
• Confirm hosting uses the .NET generic host with UseOrleans or UseOrleansClient.
• Inventory serializer member IDs, aliases, provider names, stream partition counts, and database schemas.
• Capture representative persisted state and a tested recovery point.

Call filters should already be registered using AddIncomingGrainCallFilter or AddOutgoingGrainCallFilter on the Orleans builders. The old AddGrainCallFilter API has been unsupported since before Orleans 7 and isn’t an Orleans 10 change.

Move to Orleans 8.2

Retarget the application to .NET 8 and move all Orleans packages to the latest 8.2 patch.

Configuration renames

Update these compile-time breaks:

options.CpuThreshold = 95;
options.LeaseAcquisitionPeriod = TimeSpan.FromSeconds(30);

LoadSheddingLimit became CpuThreshold in Orleans 8.1. Orleans 8.2 corrected the spelling of LeaseAquisitionPeriod.

Timer behavior

Replace the obsolete RegisterTimer API with RegisterGrainTimer. The old API interleaved callbacks, while the new API defaults Interleave to false. Preserve old behavior explicitly when required:

public override Task OnActivateAsync(CancellationToken cancellationToken)
{
    _timer = this.RegisterGrainTimer(
        callback: DoWorkAsync,
        options: new GrainTimerCreationOptions
        {
            DueTime = TimeSpan.FromSeconds(1),
            Period = TimeSpan.FromSeconds(10),
            Interleave = true
        });

    return Task.CompletedTask;
}

private static Task DoWorkAsync(CancellationToken cancellationToken) =>
    Task.CompletedTask;

Test activation collection and set KeepAlive only when timer ticks must prevent collection.

Move to Orleans 9.2

Complete the Orleans 9.2 checkpoint described in Upgrade Orleans 8.x to 10.x:

• Decide whether to accept ResourceOptimizedPlacement, the new default, or register RandomPlacement.
• Remove adaptive grain-directory cache configuration.
• Test the aligned IGrainState<T> read and clear semantics.
• Adopt native CancellationToken grain method parameters only after the runtime checkpoint is stable.

Move to Orleans 10

Complete Upgrade Orleans 9.x to 10.x. The Orleans 10-specific changes are concentrated in:

• Obsolete UnorderedAttribute and OrleansConstructorAttribute annotations.
• The CancelRequestOnTimeout default changing to false.
• SQL Server ADO.NET providers moving to Microsoft.Data.SqlClient.
• Cancellation support expanding to observers and system targets.

The generic-host model, builder-based call-filter registration, and version-tolerant serialization model remain in place.

Serialization, state, and providers

Orleans 7 introduced the identity and serializer model used by later releases, so a 7-to-10 upgrade doesn’t require the identity conversion required by Orleans 3.

Still, preserve the application contract:

• Never renumber or reuse IdAttribute values.
• Keep AliasAttribute values stable across type or assembly moves.
• Don’t reorder record primary-constructor parameters.
• Keep storage serializers and provider names stable during each runtime upgrade.
• Test reminders, stream subscriptions, queued payloads, and representative grain state at every checkpoint.
• Apply ADO.NET migration scripts in order and validate each provider before advancing.

Deployment and rollback

The documented mixed-version guarantee covers patch and minor differences inside one major family, not Orleans 7, 8, 9, and 10 in one cluster. Use a parallel cluster for every major transition unless the exact pair has passed your own mixed-version test suite.

Keep the previous cluster, deployment artifacts, provider recovery point, and compatible client build until the new checkpoint has completed its soak period. For details, see Upgrade deployment and rollback.

Checklist

• Update to the latest Orleans 7.2 patch and resolve warnings.
• Back up durable state and inventory provider schemas and serializer contracts.
• Retarget to .NET 8 independently.
• Upgrade to Orleans 8.2 and fix option and timer migrations.
• Upgrade to Orleans 9.2 and validate placement, cancellation, directory caching, and state semantics.
• Complete the Orleans 9-to-10 checklist.
• Keep package versions aligned at every checkpoint.
• Test old-state reads, new-state writes, reminders, and streams at every checkpoint.
• Rehearse a parallel-cluster deployment and rollback for every major transition.