ABP Version 11.0 Migration Guide

This document is a guide for upgrading ABP v10.x solutions to ABP v11.0. There are some changes in this version that may affect your applications. Please read them carefully and apply the necessary changes to your application.

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:

Batch Permission Update

Who is affected

• Applications that implement IPermissionManager themselves, instead of deriving from PermissionManager.
• Applications that derive from PermissionManager and override SetAsync(string, string, string, bool).

What changed

• IPermissionManager has a new SetAsync(IEnumerable<KeyValuePair<string, bool>>, string, string) member. It reads the current state of every requested permission once and writes only the permissions whose state changes, instead of querying the current state once per permission.
• PermissionAppService.UpdateAsync calls the new overload once instead of calling the single-permission SetAsync in a loop. A derived PermissionManager that only overrides the single-permission overload still compiles, but the permission management UI no longer goes through it.

What to do

Implement the new member if you implement IPermissionManager yourself, and move the logic of an overridden single-permission SetAsync to the new overload.

See #26126 for details.

Feature Value Update Skipped When Unchanged

Who is affected

• Applications that use MongoDB and handle EntityUpdatedEventData<FeatureValue>.

What changed

FeatureManagementStore.SetAsync does not update the feature value when the stored value already equals the requested one, so it no longer raises an entity updated event for it. The Entity Framework Core providers already behaved this way.

What to do

No action is required unless a handler of yours relies on receiving an event for a value that did not change.

See #26126 for details.

MySQL and Oracle Providers Do Not Work on EF Core 11 Yet

Who is affected

• Applications that use Volo.Abp.EntityFrameworkCore.MySQL, Volo.Abp.EntityFrameworkCore.Oracle or Volo.Abp.EntityFrameworkCore.Oracle.Devart.

What changed

• ABP v11.0 targets .NET 11 and EF Core 11. The database providers these packages use (MySql.EntityFrameworkCore, Oracle.EntityFrameworkCore and Devart.Data.Oracle.EFCore) have no EF Core 11 release yet, and the current versions fail with MissingMethodException or TypeLoadException when the DbContext is created.

What to do

Keep these applications on ABP v10.x until the provider ships an EF Core 11 version.

Polly Is No Longer Referenced

Who is affected

• Applications that use Polly in their own code without referencing the Polly package themselves, and get it through one of the ABP packages below.

What changed

• ABP retries its own HTTP requests and file operations with Volo.Abp.Threading.RetryHelper, so these packages no longer reference Polly:

• The number of attempts, the delays between them and the failures that are retried are unchanged in all of them.
• No ABP API takes or returns a Polly type, so nothing else changes for an application that does not use Polly itself.

What to do

Reference the package in the projects that use it. abp update rewrites Volo.* references only, so it does not add this one. ABP referenced Polly 8.6.3 up to v10.7, so that version keeps the behavior you had:

<PackageReference Include="Polly" Version="8.6.3" />

RetryHelper is an alternative if you use Polly only to retry a failing call:

using var response = await RetryHelper.ExecuteAsync(
    async cancellationToken => await httpClient.GetAsync(url, cancellationToken),
    new RetryOptions<HttpResponseMessage>
    {
        MaxRetryCount = 3,
        ShouldRetryOnResult = response => !response.IsSuccessStatusCode
    });

response.EnsureSuccessStatusCode();

Docs Module Renders PDF Files with HtmlRenderer.PdfSharp

Who is affected

• Applications that use the PDF export of the Docs module and customize, replace or derive from ITextHtmlToPdfRenderer, for example to provide fonts through GetFontProviderAsync.
• Applications that set their own HtmlStyle in DocsProjectPdfGeneratorOptions, or export Chinese, Japanese or Korean documents.
• Applications that use iText in their own code without referencing it themselves, and get it through Volo.Docs.Domain.

What changed

• Volo.Docs.Domain no longer references the iText packages (itext7, itext7.pdfhtml and itext.bouncy-castle-adapter), which are licensed under AGPL. ITextHtmlToPdfRenderer and HtmlIdTagWorkerFactory are removed.
• PdfSharpHtmlToPdfRenderer is the new default IHtmlToPdfRenderer. It uses HtmlRenderer.PdfSharp (BSD-3-Clause) and PDFsharp (MIT). It supports CSS 2 level styles, uses the fonts installed on the server and does not fall back to another font for a single missing character. GIF and WebP images are converted to PNG with SkiaSharp, and SVG images are rendered as links.
• The default HtmlStyle no longer sets width: 100% on table cells, wraps long lines in code blocks, and adds the Liberation and DejaVu fonts as fallbacks for Linux servers.

What to do

• Move your ITextHtmlToPdfRenderer customizations to PdfSharpHtmlToPdfRenderer, or implement IHtmlToPdfRenderer yourself to keep using another engine. PdfSharpHtmlToPdfRenderer uses HtmlRenderer types in its virtual methods, and Volo.Docs.Domain does not expose them to your project, so add a HtmlRenderer.PdfSharp package reference to the project that derives from it.
• Install fonts on Linux servers and containers, for example the fonts-dejavu-core or fonts-liberation package. Otherwise the text is rendered with HtmlRenderer's built-in fallback font.
• Add the SkiaSharp.NativeAssets.Linux.NoDependencies package to your host project on Linux, so GIF and WebP images can be converted. The SkiaSharp.NativeAssets.Linux package loads fontconfig and can crash the process on servers where fontconfig is installed.
• If your application sets its own PDFsharp font resolver (GlobalFontSettings.FontResolver), replace IHtmlToPdfRenderer. HtmlRenderer.PdfSharp sets its own global font resolver, and PDFsharp does not allow changing it once it is used.
• For Chinese, Japanese or Korean documents, install a TrueType (.ttf) font that contains both Latin and these characters and put it first in the font-family of HtmlStyle, as explained in the Docs module document. Font collections (.ttc) are not loaded.
• If you replace HtmlStyle, do not rely on flexbox or grid layouts, and generate a PDF to check your tables and code blocks.
• Reference the iText packages in the projects that use them.

Docs Module Uses the New Elasticsearch Client

Who is affected

• Applications that enable the full-text search of the Docs module with an Elasticsearch 7.x server.
• Applications that implement IElasticClientProvider, derive from DefaultElasticClientProvider or ElasticDocumentFullSearch, or call DocsElasticSearchOptions.Authenticate.
• Applications that use NEST in their own code without referencing it themselves, and get it through Volo.Docs.Domain.

What changed

• Volo.Docs.Domain uses Elastic.Clients.Elasticsearch 8.x instead of NEST 7.17.5, which is deprecated. The new client works with Elasticsearch 8.x and 9.x servers.
• IElasticClientProvider.GetClient() returns ElasticsearchClient instead of IElasticClient.
• DocsElasticSearchOptions.Authenticate takes and returns ElasticsearchClientSettings instead of ConnectionSettings. UseBasicAuthentication and UseApiKeyAuthentication are unchanged.
• ElasticDocumentFullSearch.HandleError takes ElasticsearchResponse instead of IElasticsearchResponse.
• The index name, the index mapping and the stored documents are unchanged, so an index created by a previous version keeps working.

What to do

• Upgrade Elasticsearch 7.x servers to 8.x or later.
• Update your implementations and derived classes to the new types. See Migration guide: From NEST v7 to .NET Client v8 for the query API changes.
• Reference the NEST package in the projects that use it.

Localization Dictionaries Are Built Per Culture

Who is affected

• Applications that derive from JsonVirtualFileLocalizationResourceContributor and change the culture or skip files in CreateDictionaryFromFile or CreateDictionaryFromFileContent.
• Applications that rely on an invalid localization JSON file to throw on the first localization call.

What changed

JsonVirtualFileLocalizationResourceContributor reads the culture of each file first and builds the dictionary of a culture only when that culture is requested. Before, it parsed all culture files of a resource on first use. So an invalid file may now throw only when its culture is requested.

What to do

In a derived contributor that changes the culture or skips files, override GetCultureNameOrNull and return null. It then parses all files as before.

See #26378 for details.

Pro

This version contains the following changes on the PRO side:

Polly Is No Longer Referenced

Who is affected

• Applications that use Polly in their own code without referencing the Polly package themselves, and get it through Volo.Abp.LanguageManagement.Domain or Volo.Abp.TextTemplateManagement.Domain.

What changed

• Both packages retry with Volo.Abp.Threading.RetryHelper instead of Polly and no longer reference it. The number of attempts, the delays between them and the failures that are retried are unchanged.

What to do

Reference the Polly package in the projects that use it, as described in the open-source section above.