从 5.3.1 升级到 6.0.1 - ABP Framework 极速开发

ABP Framework 6.0.0 发布之后，并没有第一时间升级，主要是新版本发布之后其稳定性需要接受考验，目前 6.0.1 也已经发布，已知Bug得到修复，那么是时候将示例解决方案升级到最新版了。

本文记录从 5.3.1 升级到 6.0.1 的详细过程及注意事项。

除了框架源码，LeptonX Lite Theme 已经发布正式版，此前使用的版本是 1.0.0-beta.3 ，这次我们一块升级到正式版 1.0.0 。

第一步：更新 ABP Framework 源码

基于前面良好的解决方案结构划分，框架升级其实只是需要替换 ABP-Framework-All-In-One 目录下的 abp 目录为最新版框架源码即可。

下载最新版 ABP Framework 源码 6.0.1 ，将原 abp 目录打包备份之后删除，然后将 abp-6.0.1 并解压重命名为 abp ，这样我们就将框架源码更新到最新。

abp_resource_6.0.1.png

第二步：检查已安装 .NET 版本

ABP Framework 6.0.1 和 5.3.1 所需要的版本要求相同，需要 .NET 6 或以上版本。

值得一提的是 ABP Framework 从 6.0.0 开始，会保持与与 .NET 大版本号一致，例如：.NET 7 已经发布，ABP Framework 下一个版本 7.0.preview 也会很快发布。

查看已安装的 .NET 版本，在终端执行命令 dotnet --list-sdks。

6.0.400 [/usr/local/share/dotnet/sdk]
7.0.100 [/usr/local/share/dotnet/sdk]

从显示的信息可以看出，系统中已经安装了 .NET 6.0 ，这一步就不用刻意去升级了！

如果有小版本升级，注意检查解决方案中的 global.json 文件，保持SDK版本统一。

{
  "sdk": {
    "version": "6.0.400"
  }
}

第三步：编译解决方案

执行 dotnet build 编译整个解决方案，编译成功。

ABP Framework 从 5.3.1 到 6.0.1 核心模块并没有破坏性更新，所以项目编译很顺利。

Microsoft.Extensions.FileProviders.Embedded 程序集版本不变，依然是 6.0.5 。

第四步：更新数据库结构

Microsoft.EntityFrameworkCore.Tools 程序集版本不变 6.0.5 。

不需要更新程序集和EF工具，直接执行命令生成数据迁移脚本：

cd 'src/AbpClub.EntityFrameworkCore'
dotnet ef migrations add UpdateSix

在 Migrations 目录下找到 xxxxx_UpdateSix 类：

public partial class UpdateSix : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<bool>(
            name: "IsActive",
            table: "CmsUsers",
            type: "bit",
            nullable: false,
            defaultValue: false);
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropColumn(
            name: "IsActive",
            table: "CmsUsers");
    }
}

实体结构变化不大，只有 CmsUsers 实体中增加 IsActive 属性。

接下来，执行 dotnet ef database update 将数据迁移脚本更新到数据库。

注意：修改数据库 CmsUsers 表 admin 帐户记录 IsActive 修改为 1，激活该帐户。

第五步：升级前端包

在 AbpClub.Web 项目中找到包配置文件 packages.json，将@abp为前缀的所有NPM包升级到最新版本号。这里有个规律每次 ABP Framework 版本升级都会更新为相同的NPM版本号。

@abp/aspnetcore.mvc.ui.theme.leptonxlite 用的是单独的版本号，在 ABP Framework 6.0 发布时，该包也发布了正式版，版本号为 1.0.0 。

更新后的包配置文件：

{
  "version": "1.0.0",
  "name": "abpclub",
  "private": true,
  "dependencies": {
    "@abp/aspnetcore.mvc.ui.theme.leptonxlite": "~1.0.0",
    "@abp/cms-kit": "6.0.1",
    "@abp/docs": "6.0.1",
    "@abp/jstree": "6.0.1",
    "@abp/tui-editor": "6.0.1",
    "@abp/uppy": "6.0.1",
    "@abp/virtual-file-explorer": "6.0.1",
    "slugify": "1.6.5",
    "tui-code-snippet": "2.3.3"
  }
}

slugify 和 tui-code-snippet 没有新版本，无需升级。

终端工具导航到 Web 项目所在目录，然后执行 abp install-libs 更新包引用。

除了 Web 项目，别忘记将 IdentityServer 项目按照同样的方式进行升级。

{
  "version": "1.0.0",
  "name": "my-app-identityserver",
  "private": true,
  "dependencies": {
    "@abp/aspnetcore.mvc.ui.theme.leptonxlite": "~1.0.0"
  }
}

第六步：升级 LeptonX Lite Theme 程序集

Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonXLite Nuget包引用升级到 1.0.0版本，两个项目用到该程序集： AbpClub.IdentityServer.csproj 和 AbpClub.Web.csproj

<PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonXLite" Version="1.0.0" />

第七步：功能测试

分别启动 IdentityServer HttpApi.Host 以及 Web 项目，测试应用中的功能是否都正常。经测试，除 CMS-Kit 应用模块内容页面与布局页存不兼容的Bug外，其他各项功能正常运行，升级 6.0.1 已经成功！

接下来，我们来修复页面Bug。

Bug修复：CMS-Kit与LeptonX Lite兼容问题

问题复现：访问CMS菜单下除评论外的其他6个页面都会抛出同样的异常。

博客：https://localhost:44397/Cms/Blogs
博客帖子：https://localhost:44397/Cms/BlogPosts
菜单：https://localhost:44397/Cms/Menus/Items
页面：https://localhost:44397/Cms/Pages
标签：https://localhost:44397/Cms/Tags

application_layout_exception

异常信息为：

InvalidOperationException: The following sections have been defined but have not been rendered by the page at '/Themes/LeptonXLite/Layouts/Application.cshtml': 'content_toolbar'. To ignore an unrendered section call IgnoreSection("sectionName").

从异常信息可以看出，在内容页中定义了 content_toolbar 节点（Section），但是在 /Themes/LeptonXLite/Layouts/Application.cshtml 布局页中并没有渲染该节点，导致报错。

默认情况下，Razor 视图引擎会强制渲染内容页中定义的所有节点。

所以正常解决方式是：在布局页中不需要显示某个内容页中的节点时，可以调用IgnoreSection("content_toolbar") 方法，在布局页中，忽略呈现名为 content_toolbar 节的内容。

在 /Themes/LeptonXLite/Layouts/Application.cshtml 页面中添加如下代码：

@{
  IgnoreSection("content_toolbar");
  }

不过目前官方并没有开放 LeptonX Lite Theme 源码，所以我们不能直接修改布局页，只能修改内容页来适配。（注意：修改内容页来适配布局页会导致其他主题下内容的缺失，例如：将 Theme 切换为 Basic 则该节点内容不会显示。）

修复方式：找到页面对应的 .cshtml 文件，注释掉 content_toolbar 节点。

示例：博客页面中abp/modules/cms-kit/src/Volo.CmsKit.Admin.Web/Pages/CmsKit/Blogs/Index.cshtml注释 content_toolbar 节点，其他页面修改是一样的。

@* @section content_toolbar {
    @await Component.InvokeAsync(typeof(AbpPageToolbarViewComponent), new { pageName = typeof(IndexModel).FullName })
} *@

从这个Bug修复方式来看，尽管 LeptonX Lite Theme 已经发布正式版，但是将 LeptonX Lite Theme 应用到项目中还不是 “合适” 的时候，出现UI问题，因为没有源码不方便修改。

小结

回顾一下升级涉及到的内容有三大块：源码、数据库和前端包。

源码，直接使用新版源码替换abp源码目录即可。
数据库，只增加了1个字段，使用数据迁移轻松完成。
前端包，直接升级所有NPM包到最新版本。

尽管从 5.3.1 到 6.0.1 似乎跨了一个版本，但是整个升级过程非常顺畅。

在 ABP Framework 6.0.0 有两块新增内容：一个是 LeptonX Lite Theme 替换 Basic Theme，我们已经在项目中集成到1.0.0版；另一个是 OAuth 2.0 默认实现切换为 OpenIddict 应用模块，接下来会用一个单独的章节总结 IdentityServer 迁移到 OpenIddict 的步骤和经验。

上一篇： Centos 8.2 排错

下一篇：框架升级指南：从 6.0.1 升级到 7.0.0

ABP Framework 极速开发