From 0c37e591f2b73d6b74ae33d6db36ff09aa5ef958 Mon Sep 17 00:00:00 2001
From: Engincan VESKE <enginveske@gmail.com>
Date: Tue, 7 Jul 2026 17:03:09 +0300
Subject: [PATCH] Add ABP 10.6 migration guide

Document the upgrade path from ABP 10.5 to 10.6, including background job infrastructure changes, upload/proxy generation updates, Angular 22 adoption, antiforgery and authentication behavior fixes, and dependency version bumps. Also add the new guide to the migration guide index.
---
 .../release-info/migration-guides/abp-10-6.md | 272 ++++++++++++++++++
 .../en/release-info/migration-guides/index.md |   1 +
 2 files changed, 273 insertions(+)
 create mode 100644 docs/en/release-info/migration-guides/abp-10-6.md

diff --git a/docs/en/release-info/migration-guides/abp-10-6.md b/docs/en/release-info/migration-guides/abp-10-6.md
new file mode 100644
index 0000000000..d4be6cbde1
--- /dev/null
+++ b/docs/en/release-info/migration-guides/abp-10-6.md
@@ -0,0 +1,272 @@
+```json
+//[doc-seo]
+{
+    "Description": "Upgrade your ABP solutions from v10.5 to v10.6 with this migration guide covering important behavior and integration changes."
+}
+```
+
+# ABP Version 10.6 Migration Guide
+
+This document is a guide for upgrading ABP v10.5 solutions to ABP v10.6. One item in this release is labeled as a breaking change. The new background job features are opt-in and default runtime behavior is unchanged, but the background jobs infrastructure extends public contracts and database models for optional scenarios.
+
+> **Package Version Changes:** Before upgrading, review the [Package Version Changes](../../package-version-changes.md) document to see version changes on dependent NuGet and NPM packages and align your project with ABP's internal package versions.
+
+## Open-Source (Framework)
+
+This version contains the following changes on the open-source side:
+
+### Background Jobs Infrastructure Extensions
+
+**Who is affected**
+
+- Applications using the default background job worker and wanting dedicated workers, parallel execution, or successful job retention.
+- Applications with a custom `IBackgroundJobStore` implementation.
+- Applications using the Background Jobs module with EF Core and enabling successful job retention.
+
+**What changed**
+
+- ABP adds opt-in support for:
+  - storing successfully completed jobs (`StoreSuccessfulJobs`)
+  - dedicated workers per job argument type (`AddDedicatedWorker(...)`)
+  - parallel job execution (`MaxParallelJobExecutionCount`)
+- `IBackgroundJobStore`, `IBackgroundJobWorker`, and related infrastructure gained new members.
+- EF Core stores add a `CompletionTime` column to background job records for retention scenarios.
+- All new runtime features are disabled by default.
+
+**What to do**
+
+No action is required if you do not enable the new options and do not maintain a custom background job store.
+
+If you maintain a custom `IBackgroundJobStore`, implement the new interface members so your solution compiles.
+
+If you enable `StoreSuccessfulJobs`, add/review the EF Core migration for the `CompletionTime` column and configure retention options explicitly:
+
+```csharp
+Configure<AbpBackgroundJobWorkerOptions>(options =>
+{
+    options.StoreSuccessfulJobs = true;
+    options.SuccessfulJobRetentionTime = TimeSpan.FromDays(7);
+});
+```
+
+If you enable dedicated workers or parallel execution, configure the options consistently across all application instances and use a real distributed lock provider in clustered deployments.
+
+> See the [Background Jobs](../../framework/infrastructure/background-jobs/index.md) document and [#25742](https://github.com/abpframework/abp/pull/25742) for details.
+
+### API Definition and Proxy Generation for Uploads and Content Types
+
+**Who is affected**
+
+- Applications using generated Angular, jQuery, or C# proxies for upload endpoints.
+- Applications returning non-JSON response types from application services.
+- Applications that customized generated upload proxy signatures.
+
+**What changed**
+
+- API definition now exposes response `ContentTypes` and `IsRemoteStream`.
+- Generated Angular and jQuery proxies forward upload DTOs containing `IRemoteStreamContent` as multipart `FormData`.
+- Generated Angular upload method signatures may collapse the upload argument to `FormData`.
+- `RestService` now unwraps ABP error envelopes more consistently for text and blob response modes.
+
+**What to do**
+
+- Keep upload DTO types in `FormBodyBindingIgnoredTypes` as before.
+- Regenerate client proxies after upgrading.
+- Update custom client code that assumed upload proxies accepted the original DTO type instead of `FormData`.
+- Re-test file upload flows in Angular, MVC/jQuery, and C# client integrations.
+
+> See [#25639](https://github.com/abpframework/abp/pull/25639) for details.
+
+### Angular 22 Upgrade
+
+**Who is affected**
+
+- Applications using the ABP Angular UI.
+- Applications with custom Angular code, third-party Angular libraries, or CI pipelines pinned to Angular 21.
+
+**What changed**
+
+- ABP Angular packages and templates now target **Angular 22.0.x**.
+- Locale loading was improved with a fallback mechanism for missing or partial locale resources.
+
+**What to do**
+
+- Upgrade your Angular application dependencies together with ABP NPM packages.
+- Follow the official Angular update guidance for your current Angular version.
+- Re-run UI tests and rebuild custom Angular libraries after the upgrade.
+- Regenerate Angular proxies after upgrading backend packages.
+
+> See [#25690](https://github.com/abpframework/abp/pull/25690) and [#25734](https://github.com/abpframework/abp/pull/25734) for details.
+
+### Antiforgery User Id Claim Issuer Normalization
+
+**Who is affected**
+
+- Applications that serve a token-authenticated SPA and cookie-authenticated MVC/Razor Pages on the same origin.
+- Applications using Razor Pages modules such as Setting Management with antiforgery-protected POST handlers.
+
+**What changed**
+
+- ABP normalizes the user id claim issuer while generating and validating antiforgery tokens.
+- Razor Pages now use ABP's antiforgery validation path instead of only the built-in ASP.NET Core filter.
+- The behavior is enabled by default through `AbpAntiForgeryOptions.NormalizeUserIdClaimIssuer`.
+
+**What to do**
+
+- Re-test SPA + MVC mixed authentication flows, especially pages that POST immediately on load.
+- If you implemented custom antiforgery logic that depends on the raw claim issuer, review it after upgrading.
+- Disable the behavior only if you intentionally rely on the previous issuer-specific antiforgery identity:
+
+```csharp
+Configure<AbpAntiForgeryOptions>(options =>
+{
+    options.NormalizeUserIdClaimIssuer = false;
+});
+```
+
+> See [#25655](https://github.com/abpframework/abp/pull/25655) and [#25669](https://github.com/abpframework/abp/pull/25669) for details.
+
+### OpenIddict Interactive Cookie `client_id` Fix
+
+**Who is affected**
+
+- Applications using OpenIddict authorization-code flows together with interactive cookie authentication.
+- Applications relying on audit logs or current-client resolution from cookie-authenticated requests.
+
+**What changed**
+
+- ABP removes `client_id` from the interactive authentication cookie when the cookie principal is refreshed.
+- Access tokens are unaffected.
+- Cookies that were already corrupted self-heal on the next refresh.
+
+**What to do**
+
+No action is required. Re-test authorization, account, and audit-log scenarios if you previously observed intermittent incorrect `ClientId` values in cookie-authenticated requests.
+
+> See [#25711](https://github.com/abpframework/abp/pull/25711) for details.
+
+### Access Token Forwarding for Authenticated Client Requests
+
+**Who is affected**
+
+- Applications using `HttpContextAbpAccessTokenProvider`.
+- Machine-to-machine integrations that authenticate with `client_credentials` and then call other protected APIs from the same request pipeline.
+
+**What changed**
+
+- The provider now forwards the incoming access token whenever the request is authenticated, not only when there is an interactive user.
+- `client_credentials` requests no longer fall back to configured identity clients in that scenario.
+
+**What to do**
+
+- Re-test service-to-service calls that rely on the current HTTP context access token.
+- Verify downstream API authorization when the caller authenticates as a client rather than a user.
+
+> See [#25740](https://github.com/abpframework/abp/pull/25740) for details.
+
+### Thread Current Principal Accessor Behavior
+
+**Who is affected**
+
+- Background jobs, hosted services, and other non-web code that reads `ICurrentPrincipalAccessor.Principal`.
+- Code that explicitly checks for `null` principals in non-web contexts.
+
+**What changed**
+
+- `ThreadCurrentPrincipalAccessor` now returns an anonymous `ClaimsPrincipal` instead of `null` when `Thread.CurrentPrincipal` is not set.
+
+**What to do**
+
+- Re-test background jobs and hosted services that branch on `Principal == null`.
+- Prefer checking authentication/identity state through claims or ABP's current user/client abstractions instead of relying on a `null` principal.
+
+> See [#25752](https://github.com/abpframework/abp/pull/25752) for details.
+
+### Dependency Updates
+
+**Who is affected**
+
+- Applications that pin ABP transitive dependencies directly.
+- Applications using `Microsoft.Data.SqlClient`, Swashbuckle, or Angular with fixed versions.
+
+**What changed**
+
+- `Microsoft.*` and `System.*` packages were upgraded to **10.0.9**.
+- `Microsoft.Data.SqlClient` was upgraded to **7.0.2**.
+- `Swashbuckle.AspNetCore` was upgraded to **10.2.3**.
+- ABP Angular packages were upgraded to **Angular 22.0.x**.
+
+**What to do**
+
+- Review your direct package references and align them with ABP's package versions where needed.
+- Rebuild and run database/integration tests if you directly use `Microsoft.Data.SqlClient`.
+- Re-test Swagger/OpenAPI integration if you customized Swashbuckle configuration.
+
+## Pro
+
+There are no explicitly marked breaking changes on the PRO side in this release scope. However, check the following if they apply to your application.
+
+### OpenIddict Generate Access Token UI
+
+**Who is affected**
+
+- Applications using OpenIddict application management UIs in ABP Commercial.
+
+**What changed**
+
+- Administrators can generate access tokens for OpenIddict applications from MVC, Blazor, MudBlazor, and Angular UIs.
+- The backend forwards `client_credentials` requests to `/connect/token`.
+
+**What to do**
+
+- Re-test OpenIddict application administration pages after upgrading.
+- Review who can access the new token-generation action in your authorization setup.
+
+### Low-Code Runtime History
+
+**Who is affected**
+
+- Applications using the LowCode module and Admin Console designer.
+- Teams relying on writable low-code layers and designer undo/redo workflows.
+
+**What changed**
+
+- The designer adds runtime model history with undo/redo, save points, compare, revert, and selective apply flows.
+- History starts after deployment; older saves are not reconstructed.
+- MongoDB history persistence is not implemented yet in this release scope.
+
+**What to do**
+
+- Re-test low-code designer save, undo/redo, compare, and revert flows after upgrading.
+- Plan operational expectations for history retention and deployment timing.
+
+### Low-Code Layer Contracts and Designer Policy Enforcement
+
+**Who is affected**
+
+- Applications using inherited low-code layers, page groups, and multi-layer customization.
+
+**What changed**
+
+- Layer override/edit policies are enforced in backend validation and Admin Console designer controls.
+- Disabled or orphaned overrides can be cleaned up and reported through model health snapshots.
+- Broken parent/group/page reference chains are hidden from runtime APIs while remaining visible in designer diagnostics.
+
+**What to do**
+
+- Re-test inherited entity/page/page-group customization flows.
+- Review model health warnings after upgrading and clean up orphaned or disallowed overrides if needed.
+
+### AI Management Indexing Resilience
+
+**Who is affected**
+
+- Applications using the AI Management module with document indexing enabled.
+
+**What changed**
+
+- Indexing is more resilient under memory pressure.
+
+**What to do**
+
+- Re-test document indexing on large datasets or memory-constrained environments after upgrading.
diff --git a/docs/en/release-info/migration-guides/index.md b/docs/en/release-info/migration-guides/index.md
index 418ec7d586..ec169d8242 100644
--- a/docs/en/release-info/migration-guides/index.md
+++ b/docs/en/release-info/migration-guides/index.md
@@ -9,6 +9,7 @@
 
 The following documents explain how to migrate your existing ABP applications. We write migration documents only if you need to take an action while upgrading your solution. Otherwise, you can easily upgrade your solution using the [abp update command](../upgrading.md).
 
+- [10.5 to 10.6](abp-10-6.md)
 - [10.4 to 10.5](abp-10-5.md)
 - [10.3 to 10.4](abp-10-4.md)
 - [10.x to 10.3](abp-10-3.md)