抠丁客 抠丁客
项目
编辑 (2025/12/24)

ABP 版本 10.0 迁移指南

本文档是将 ABP v9.x 解决方案升级到 ABP v10.0 的指南。此版本中有一些可能影响您的应用程序的更改。请仔细阅读并应用到您的应用程序中。

开源版（框架）

升级到 .NET 10.0

我们已经将 ABP 升级到 .NET 10.0，因此如果您想使用 ABP 10.0，您需要将您的解决方案迁移到 .NET 10.0。您可以查看微软的 从 ASP.NET Core 9.0 迁移到 10.0 文档，了解如何将现有的 ASP.NET Core 9.0 项目更新到 ASP.NET Core 10.0。

MySQL 对 .NET 10.0 的支持

如果您使用 MySQL 作为您的数据库提供商，请在升级到 ABP 10.0 之前注意以下兼容性问题！

MySQL Entity Framework Core 提供商目前对 .NET 10.0 的支持有限：

  • Pomelo.EntityFrameworkCore.MySql：尚未支持 .NET 10.0。该团队正在积极致力于添加支持。
  • MySql.EntityFrameworkCore：目前处于发布候选版本状态，存在已知可能影响生产应用程序的错误。

建议：如果您使用 MySQL，我们建议等待 MySQL 提供商发布完全支持 .NET 10.0 的稳定版本后，再升级到 ABP 10.0。

跟踪进展：

我们将在最新的稳定版 MySQL 提供商可用后立即更新以支持它们。

添加新的 EF Core 迁移

某些模块中的一些实体已被修改。如果您正在使用 Entity Framework Core，请在升级到 ABP 10.0 后，在您的项目中创建一个新的 EF Core 迁移。

如果迁移文件为空，您可以使用 dotnet ef migrations remove 命令将其删除。

Razor 运行时编译已过时

我们移除了对 Razor 运行时编译的支持，因为它已过时，并在 .NET 10.0 中被 热重载 取代。

如果您想继续使用它，可以手动向您的项目添加 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 包并进行配置。

如果引用的项目也包含需要此功能的 Razor 页面，请同时将包添加到该项目中。

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>>()));
            });
    }
}

更多信息，请查看 Razor 运行时编译已过时 页面。

IActionContextAccessor 已过时

我们已经从依赖注入中移除了 IActionContextAccessor，并且在 ABP 的核心框架和模块中不再使用 IActionContextAccessor。

更多信息，请参见 IActionContextAccessor 已过时。

添加 BLOB 存储内存提供程序 模块

在此版本中，我们添加了 BLOB 存储内存提供程序 模块，用于单元测试目的。

更多信息，请参阅 BLOB 存储内存提供程序 文档。

始终使用 MapStaticAssets

以前，如果静态文件过多，MapStaticAssets 会有性能问题。.NET 10.0 已修复此问题。我们将始终使用 MapStaticAssets 来提供静态文件。

更多信息，请参见 静态文件服务性能问题。

C# 14 中带 Span 参数的重载解析

.NET Core 会将 array.Contains 扩展方法重定向到 MemoryExtensions.Contains。这将导致 MongoDB.Driver 无法转换 IQueryable<T>。如果您在代码中使用 array.Contains，应使用以下代码来避免此问题：

M((array, num) => array.Contains(num)); // 失败，绑定到 MemoryExtensions.Contains
M((array, num) => ((IEnumerable<int>)array).Contains(num)); // 正常，绑定到 Enumerable.Contains
M((array, num) => array.AsEnumerable().Contains(num)); // 正常，绑定到 Enumerable.Contains
M((array, num) => Enumerable.Contains(array, num)); // 正常，绑定到 Enumerable.Contains

请注意，只有 array 类型有这个问题。其他类型不受影响（例如 List<T>、HashSet<T> 等）。MongoDB.Driver 提供商将在未来版本中修复此问题，如果需要，我们将立即应用更改。

更多信息，请参见 C# 14 中带 Span 参数的重载解析。

OpenIddict 升级到 7.X

我们已经将 OpenIddict 升级到 v7.x。有关此版本引入的更改的详细信息，请参阅 OpenIddict 6.x 到 7.x 迁移指南。

作为开发者，您通常只需要 创建一个新的 Entity Framework Core 迁移 并将其 应用到您的数据库，因为 OpenIddict v7.x 引入了对 OpenIddictToken 实体的修改。

从 AutoMapper 迁移到 Mapperly

AutoMapper 库不再免费用于商业用途。更多详情，请参考这篇 公告文章。

在此版本中，所有 ABP 模块都使用 Mapperly 替代 AutoMapper。ABP 框架同时提供了 AutoMapper 和 Mapperly 的集成。如果您的项目当前使用 AutoMapper 并且没有商业许可，您可以按照 从 AutoMapper 迁移到 Mapperly 文档迁移到 Mapperly。

InboxProcessor 的失败重试策略

我们向 AbpEventBusBoxesOptions 添加了失败重试策略（请参阅 InboxProcessorFailurePolicy 和 InboxProcessorRetryBackoffFactor）。由于此更改在 IncomingEventRecord 实体中添加和删除了字段，因此如果您将 Inbox/Outbox 与 Entity Framework Core 一起使用，则必须创建一个新的数据库迁移。

  • InboxProcessorFailurePolicy：处理收件箱处理器失败的策略。默认值为 Retry。可能的值有：
    • Retry：当前异常及后续事件将在下一个周期中继续按顺序处理。
    • RetryLater：跳过引发异常的事件，并继续处理后续事件。失败的事件将延迟重试，每次重试的延迟时间按配置的 InboxProcessorRetryBackoffFactor 倍数递增（例如，10、20、40、80 秒）。默认最大重试次数为 10（可配置）。如果在达到最大重试次数后仍然失败，则丢弃该事件。
    • Discard：引发异常的事件将被丢弃，并且不会重试。
  • InboxProcessorRetryBackoffFactor：当 InboxProcessorFailurePolicy 为 RetryLater 时使用的初始重试延迟因子（双精度）。重试延迟的计算公式为：delay = InboxProcessorRetryBackoffFactor × 2^retryCount。默认值为 10。

更多信息，请参见 为 InboxProcessor 添加失败重试策略 的 PR。

在开发环境中禁用缓存错误隐藏

从 ABP 10.0 开始，AbpDistributedCacheOptions 的 HideErrors 选项默认在开发环境中被禁用。

默认情况下，ABP 会隐藏并记录缓存服务器错误，以便即使在缓存不可用时也能保持应用程序运行。 但是，在开发环境中，错误不再被隐藏，以便开发者能够立即检测并修复任何缓存服务器问题（例如连接、配置或运行时错误）。

在本文档中