Upgrade Orleans 8.x to 10.x

Starting and target assumptions

This guide assumes:

The application can first move to Orleans 8.2 on .NET 8.
The upgrade can be validated at Orleans 9.2 before packages move to Orleans 10.x.
Provider schemas and durable state can be backed up and tested at each checkpoint.
All Orleans packages move together at each checkpoint.

Don’t skip directly from an early Orleans 8 release to Orleans 10 in production. Build and test the application on the latest 8.2 patch, then Orleans 9.2, then the selected Orleans 10.x patch.

Orleans 8.x changes to complete first

Applications starting before Orleans 8.2 must account for these changes:

Area	Change	Action
Load shedding	LoadSheddingLimit was replaced by CpuThreshold in Orleans 8.1	Rename the option and review the added MemoryThreshold.
Streaming	LeaseAquisitionPeriod and DefaultMinLeaseAquisitionPeriod were corrected in Orleans 8.2	Use LeaseAcquisitionPeriod and DefaultMinLeaseAcquisitionPeriod.
Timers	RegisterGrainTimer replaced the obsolete RegisterTimer API in Orleans 8.2	Migrate callbacks and choose Interleave and KeepAlive deliberately.
Serialization	MessagePack integration became available in Orleans 8.2	Don’t change the active serializer during the runtime upgrade unless separately qualified.

When translating an old timer and preserving its interleaving behavior:

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;

For the full timer behavior matrix, see Timers and reminders.

Validate the Orleans 9.2 checkpoint

Orleans 9.2 introduces behavior that must be understood before moving to Orleans 10.

Native CancellationToken parameters

Grain interface methods can use CancellationToken directly. Existing GrainCancellationToken code can be migrated independently; don’t combine that API conversion with business-logic changes.

Task RunAsync(CancellationToken cancellationToken);

Only one cancellation token is allowed in a grain method. Test cancellation that occurs before dispatch, during execution, after completion, and while the target is unavailable.

Resource-optimized placement is the default

Orleans 9.2 changed the default placement strategy from RandomPlacement to ResourceOptimizedPlacement. This can change activation distribution and locality. Either accept and load-test the new default or register RandomPlacement explicitly:

public static void KeepRandomPlacement(ISiloBuilder siloBuilder)
{
    siloBuilder.Services.AddSingleton<PlacementStrategy, RandomPlacement>();
}

Grain directory caching

The adaptive grain-directory cache implementation was removed in Orleans 9.2. The CachingStrategyType value Adaptive remains as an obsolete alias for LRU. Remove explicit adaptive-cache configuration and tune LRU cache size and expiration based on production measurements.

Grain storage behavior

Orleans 9.2 aligned storage providers so that State, RecordExists, and ETag follow consistent rules after reads and clears. Test activation initialization and ClearStateAsync behavior for every provider, especially code that inferred record existence from a null state object.

Apply the Orleans 10 changes

After the Orleans 9.2 checkpoint is stable, complete every step in Upgrade Orleans 9.x to 10.x, including:

Removing obsolete UnorderedAttribute and valid OrleansConstructorAttribute uses.
Setting timeout-cancellation behavior explicitly.
Moving SQL Server ADO.NET providers to Microsoft.Data.SqlClient.
Keeping hosting, call filters, serializer contracts, and provider schemas stable.

Serialization and state compatibility

Orleans 8, 9, and 10 use the version-tolerant serializer introduced in Orleans 7, but application changes can still make stored data incompatible.

Keep all IdAttribute and AliasAttribute values stable.
Don’t reorder record primary-constructor parameters.
Don’t change storage serializers while changing runtime majors.
Test old-state reads and rollback reads after every checkpoint.
Preserve stream partition counts and provider names.
Apply provider schema migrations in order and keep a pre-migration recovery point.

Deployment and rollback

Use separate clusters for the 8-to-9 and 9-to-10 production transitions unless each mixed-major pair has been explicitly qualified. Grain interface versioning helps application versions coexist, but it doesn’t extend the documented runtime guarantee beyond one Orleans major family.

Follow Upgrade deployment and rollback at each checkpoint. Don’t allow writes in the new cluster until the rollback build has been tested against the resulting state and provider schema.