abp/docs/en/release-info/migration-guides/abp-10-6.md

//[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. This version includes explicitly marked migration-impacting changes for specific customization scenarios, while most applications can upgrade with no additional action beyond the notes below.

Package Version Changes: Before upgrading, review the Package Version Changes 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 or IBackgroundJobWorker 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 or IBackgroundJobWorker, 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:

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 document and #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 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 and #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:

Configure<AbpAntiForgeryOptions>(options =>
{
    options.NormalizeUserIdClaimIssuer = false;
});

See #25655 and #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 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 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 for details.

Dependency Updates

Who is affected

• Applications that pin ABP transitive dependencies directly.
• Applications using Microsoft.Data.SqlClient, MongoDB.Driver, 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.
• MongoDB.Driver was upgraded to 3.10.0.
• 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 MongoDB integrations if your solution directly references MongoDB.Driver packages.
• Re-test Swagger/OpenAPI integration if you customized Swashbuckle configuration.

Pro

This version contains the following changes on the PRO side:

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.

AI Management Indexing Resilience

Who is affected

• Applications using the AI Management module with document indexing enabled.
• Applications that replace or customize IDocumentChunkRepository.

What changed

• Indexing is more resilient under memory pressure by coordinating work in bounded batches.
• IDocumentChunkRepository includes a new paged datasource query overload used by bounded batch indexing.

What to do

• Re-test document indexing on large datasets or memory-constrained environments after upgrading.
• If your application implements IDocumentChunkRepository directly, add the new overload and return chunks for the datasource ordered by ChunkIndex, starting at startChunkIndex, limited to maxResultCount.