ABP Version 10.0 Migration Guide

This document is a guide for upgrading ABP v9.x solutions to ABP v10.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.

Open-Source (Framework)

Upgrade to .NET 10.0

We've upgraded ABP to .NET 10.0, so you need to move your solutions to .NET 10.0 if you want to use ABP 10.0. You can check Microsoft’s Migrate from ASP.NET Core 9.0 to 10.0 documentation to see how to update an existing ASP.NET Core 9.0 project to ASP.NET Core 10.0.

MySQL Support for .NET 10.0

If you are using MySQL as your database provider, please be aware of the following compatibility issues before upgrading to ABP 10.0!

The MySQL Entity Framework Core providers currently have limited support for .NET 10.0:

• Pomelo.EntityFrameworkCore.MySql: Does not yet support .NET 10.0. The team is actively working on adding support.
• MySql.EntityFrameworkCore: Currently in Release Candidate (RC) status with known bugs that may affect production applications.

Recommendation: If you are using MySQL, we recommend waiting to upgrade to ABP 10.0 until the MySQL providers release stable versions with full .NET 10.0 support.

Track Progress:

• Pomelo Provider - EF Core 10 Support
• MySql.EntityFrameworkCore NuGet Package

We will update to support the latest stable MySQL providers as soon as they become available.

Add New EF Core Migrations

Some entities in certain modules have been modified. If you are using Entity Framework Core, please create a new EF Core migration in your project after upgrading to ABP 10.0.

If the migration file is empty, you can remove it by using the dotnet ef migrations remove command.

Razor Runtime Compilation Obsolete

We removed the Razor Runtime Compilation support since it is obsolete and replaced by Hot Reload in .NET 10.0.

If you want to keep using it, you can add Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation package to your project and configure it manually.

If the referenced project also contains Razor Pages that require this feature, add the package to that project as well.

using Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation;
using Volo.Abp.DependencyInjection;
using Volo.Abp.AspNetCore.VirtualFileSystem;

public override void ConfigureServices(ServiceConfigurationContext context)
{
    if (context.Services.GetHostingEnvironment().IsDevelopment())
    {
        var mvcCoreBuilder = context.Services.AddMvc();
        mvcCoreBuilder.AddRazorRuntimeCompilation().Services
#pragma warning disable ASPDEPR003
            .Configure<MvcRazorRuntimeCompilationOptions>(options =>
#pragma warning restore ASPDEPR003
            {
                options.FileProviders.Add(new RazorViewEngineVirtualFileProvider(mvcCoreBuilder.Services
                    .GetSingletonInstance<IObjectAccessor<IServiceProvider>>()));
            });
    }
}

For more information, you can check the Razor Runtime Compilation Obsolete page.

IActionContextAccessor Obsolete

We removed the IActionContextAccessor from dependency injection and are not using the IActionContextAccessor in ABP's core framework and modules.

See IActionContextAccessor Obsolete for more information.

Add BLOB Storing Memory Provider module.

In this version, we have added the BLOB Storing Memory Provider module for unit testing purposes.

See the BLOB Storing Memory Provider document for more information.

Always use MapStaticAssets

Previously, the MapStaticAssets had performance problems if there were too many static files. NET 10.0 has fixed this problem. We will always use MapStaticAssets to serve the static files.

See Static file serving performance issues for more information.

C# 14 overload resolution with span parameters

NET Core will redirect the array.Contains extension method to MemoryExtensions.Contains. This will cause MongoDB.Driver to be unable to translate IQueryable<T>. If you are using array.Contains in your code, you should use the following code to avoid this problem:

M((array, num) => array.Contains(num)); // fails, binds to MemoryExtensions.Contains
M((array, num) => ((IEnumerable<int>)array).Contains(num)); // ok, binds to Enumerable.Contains
M((array, num) => array.AsEnumerable().Contains(num)); // ok, binds to Enumerable.Contains
M((array, num) => Enumerable.Contains(array, num)); // ok, binds to Enumerable.Contains

Please note that only the array type has this problem. Other types are not affected (e.g. List<T>, HashSet<T>, etc). MongoDB.Driver provider will be fixed in future versions, and we will immediately apply the changes if needed.

See the C# 14 overload resolution with span parameters for more information.

OpenIddict Upgrade to 7.X

We have upgraded OpenIddict to v7.x. For detailed information about the changes introduced in this release, refer to the OpenIddict 6.x to 7.x Migration Guide.

As a developer, you typically only need to create a new Entity Framework Core migration and apply it to your database, since OpenIddict v7.x introduces a modification in the OpenIddictToken entity.

Migrating from AutoMapper to Mapperly

The AutoMapper library is no longer free for commercial use. For more details, you can refer to this announcement post.

In this version, all ABP modules use Mapperly instead of AutoMapper. ABP Framework provides both AutoMapper and Mapperly integrations. If your project currently uses AutoMapper and you don't have a commercial license, you can follow the Migrating from AutoMapper to Mapperly document to migrate to Mapperly.

Failure Retry Policy for InboxProcessor

We added a failure retry policy to AbpEventBusBoxesOptions (see InboxProcessorFailurePolicy and InboxProcessorRetryBackoffFactor). Because this change adds and removes fields in the IncomingEventRecord entity, you must create a new database migration if you use Inbox/Outbox with Entity Framework Core.

• InboxProcessorFailurePolicy: The policy to handle the failure of the inbox processor. Default value is Retry. Possible values are:
  • Retry: The current exception and subsequent events will continue to be processed in order in the next cycle.
  • RetryLater: Skip the event that caused the exception and continue with the following events. The failed event will be retried after a delay that doubles with each retry, starting from the configured InboxProcessorRetryBackoffFactor (e.g., 10, 20, 40, 80 seconds). The default maximum retry count is 10 (configurable). Discard the event if it still fails after reaching the maximum retry count.
  • Discard: The event that caused the exception will be discarded and will not be retried.
• InboxProcessorRetryBackoffFactor: The initial retry delay factor (double) used when InboxProcessorFailurePolicy is RetryLater. The retry delay is calculated as: delay = InboxProcessorRetryBackoffFactor × 2^retryCount. Default value is 10.

See the Add failure retry policy to InboxProcessor PR for more information.

Disable Cache Error Hiding in Development Environment

Starting from ABP 10.0, the HideErrors option of AbpDistributedCacheOptions is disabled by default in the development environment.

By default, ABP hides and logs cache server errors to keep the application running even when the cache is unavailable.
However, in the development environment, errors are no longer hidden so that developers can immediately detect and fix any cache server issues (such as connection, configuration, or runtime errors).