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 it carefully and apply the necessary changes to your application.

Open-Source (Framework)

Upgraded 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.

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 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.

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.

We are not using IActionContextAccessor in ABP core framework and modules.

See IActionContextAccessor Obsolete for more information.

Add BLOB Storing Memory Provider module.

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

See the BLOB Storing Memory Provider document for more information.

Always use MapStaticAssets

Provious, the MapStaticAssets has performance problems if there are too many static files. and we will use StaticFileMiddleware to serve the static files in development mode. 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 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 following code to avoid this problem.

Only array has this problem, other types are not affected. eg List, HashSet, etc.

MongoDB.Driver will be fixed in the future.

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

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

OpenIddict 7.X

We upgraded OpenIddict to 7.X. See the OpenIddict 6.x to 7.x Migration Guide for more information.

OpenIddict 7.X changed the OpenIddictToken entity, you must create a new database migration if you use Entity Framework Core.

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).

PRO