docs: add Orleans 10 migration guides

docs/site/src/content/docs/migration/3-to-7-archive.md

@@ -0,0 +1,57 @@
+---
+title: Archived Orleans 3.x to 7.x migration notes
+description: Historical guidance for crossing the incompatible Orleans 3-to-7 identity, hosting, and serialization boundary.
+ms.date: 08/02/2026
+ms.topic: how-to
+---
+
+# Archived Orleans 3.x to 7.x migration notes
+
+> [!WARNING]
+> Orleans 3.x and Orleans 7.x are out of support. Use these notes only to reach a supported intermediate codebase, then continue through [Orleans 7.x to 10.x](7-to-10.md).
+
+## Starting and target assumptions
+
+These notes apply to an Orleans 3.x application that must first become an Orleans 7 application. This transition isn't wire compatible. Orleans 3 and Orleans 7 silos can't form a mixed cluster, so deploy Orleans 7 in a separate cluster and plan an application-specific state transition.
+
+## Required architectural changes
+
+- Reference `Microsoft.Orleans.Server` from silo projects, `Microsoft.Orleans.Client` from client projects, and `Microsoft.Orleans.Sdk` from shared contract projects.
+- Remove the legacy MSBuild code-generator and `Microsoft.Orleans.OrleansRuntime` packages.
+- Remove Application Parts configuration. The Orleans source generator discovers application types.
+- Use the .NET generic host with `UseOrleans` and `UseOrleansClient`.
+- Update `OnActivateAsync` and `OnDeactivateAsync` overrides to the Orleans 7 cancellation-token and deactivation-reason signatures.
+- Add `[GenerateSerializer]` and stable `[Id]` values to application types.
+- Replace legacy grain, interface, and stream identity assumptions with the Orleans 7 string-based identity model.
+- Replace Simple Message Streams with broadcast channels or a persistent stream provider.
+- Replace legacy telemetry consumers with .NET metrics and `ActivitySource`-based tracing.
+
+The old `IServiceCollection.AddGrainCallFilter` API was removed before Orleans 7. Register incoming and outgoing filters on `ISiloBuilder` or `IClientBuilder`.
+
+## State and deployment boundary
+
+Grain and stream identities and the wire serializer changed incompatibly in Orleans 7. Don't point a new cluster at production state until you have verified:
+
+- How old grain identities map to new string identities.
+- How each persisted payload is converted or read.
+- How reminders and stream subscriptions are recreated or migrated.
+- How traffic is cut over without two clusters processing the same logical entities.
+
+Prefer an offline export/transform/import process or an application-level bridge with idempotent writes. Keep the Orleans 3 data recovery point until the Orleans 7 cluster has completed validation.
+
+## Continue to Orleans 10
+
+After the Orleans 7 application is stable:
+
+1. Update it to the latest Orleans 7.2 patch.
+1. Follow [Upgrade Orleans 7.x to 10.x](7-to-10.md).
+1. Use a separate deployment checkpoint for Orleans 8.2, Orleans 9.2, and Orleans 10.x.
+
+## Checklist
+
+- [ ] Build an Orleans 7 codebase using current package and hosting patterns.
+- [ ] Define grain, stream, reminder, and state identity mappings.
+- [ ] Convert and validate representative persisted payloads.
+- [ ] Deploy Orleans 7 in a separate cluster.
+- [ ] Verify rollback to the Orleans 3 recovery point.
+- [ ] Stabilize on Orleans 7.2 before continuing sequentially to Orleans 10.

docs/site/src/content/docs/migration/7-to-10.md

@@ -0,0 +1,113 @@
+---
+title: Upgrade Orleans 7.x to 10.x
+description: Upgrade an Orleans 7 application sequentially through Orleans 8.2 and 9.2 to Orleans 10.
+ms.date: 08/02/2026
+ms.topic: how-to
+---
+
+# 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.
+1. Latest Orleans 8.2 on .NET 8.
+1. Latest Orleans 9.2 on .NET 8.
+1. 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 `IServiceCollection.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:
+
+```csharp
+options.CpuThreshold = 95;
+options.LeaseAcquisitionPeriod = TimeSpan.FromSeconds(30);
+```
+
+`LoadSheddingOptions.LoadSheddingLimit` became `CpuThreshold` in Orleans 8.1. Orleans 8.2 corrected the spelling of `LeaseBasedQueueBalancerOptions.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:
+
+:::code language="csharp" source="snippets/Orleans10MigrationExamples.cs" id="grain_timer":::
+
+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](8-to-10.md):
+
+- 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](9-to-10.md). The Orleans 10-specific changes are concentrated in:
+
+- Obsolete `[Unordered]` and `[OrleansConstructor]` 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 `[Id]` values.
+- Keep `[Alias]` 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](deployment-and-rollback.md).
+
+## 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.

docs/site/src/content/docs/migration/8-to-10.md

@@ -0,0 +1,101 @@
+---
+title: Upgrade Orleans 8.x to 10.x
+description: Upgrade an Orleans 8 application through Orleans 9.2 to Orleans 10 with validated compatibility checkpoints.
+ms.date: 08/02/2026
+ms.topic: how-to
+---
+
+# 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:
+
+:::code language="csharp" source="snippets/Orleans10MigrationExamples.cs" id="grain_timer":::
+
+For the full timer behavior matrix, see [Timers and reminders](../grains/timers-and-reminders.md#migrate-from-registertimer-to-registergraintimer).
+
+## 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 `System.Threading.CancellationToken` directly. Existing `GrainCancellationToken` code can be migrated independently; don't combine that API conversion with business-logic changes.
+
+:::code language="csharp" source="snippets/Orleans10MigrationExamples.cs" id="grain_cancellation":::
+
+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:
+
+:::code language="csharp" source="snippets/Orleans10MigrationExamples.cs" id="random_placement":::
+
+### Grain directory caching
+
+The adaptive grain-directory cache implementation was removed in Orleans 9.2. `GrainDirectoryOptions.CachingStrategyType.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 `IGrainState<T>.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](9-to-10.md), including:
+
+- Removing obsolete `[Unordered]` and valid `[OrleansConstructor]` 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 `[Id]` and `[Alias]` 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](deployment-and-rollback.md) 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.
+
+## Checklist
+
+- [ ] Update the application to the latest Orleans 8.2 patch on .NET 8.
+- [ ] Replace renamed load-shedding and lease-balancer options.
+- [ ] Migrate `RegisterTimer` to `RegisterGrainTimer` and select timer options.
+- [ ] Build and test on the latest Orleans 9.2 patch.
+- [ ] Decide whether to keep resource-optimized placement or register random placement.
+- [ ] Remove adaptive grain-directory cache configuration.
+- [ ] Test native cancellation and provider state semantics.
+- [ ] Complete the Orleans 9-to-10 checklist.
+- [ ] Validate serialization, streams, reminders, and provider schemas at every checkpoint.
+- [ ] Rehearse deployment and rollback for each major-version transition.