跳到主要内容
版本：3.0.0

如何从 2.2.0 升级到 3.0.0

这页对应的是 Aegis 2.2.0 -> 3.0.0 / 3.x 的升级指南。
它不只是讲 .NET 6 -> .NET 8，还包括组件包、命名空间、启动方式和组件装配方式的整体迁移。

升级前先看​

这次升级的影响主要集中在四类内容：

  • 项目目标框架从 net6.0 迁到 net8.0
  • Aegis 组件包整体进入 3.0.0 / 3.x
  • 一部分包名、命名空间和代码拼写发生变化
  • 组件装配和启动方式要统一到 AegisApplication + Component.deps.json

如果旧项目里还用了认证、SignalR、Broker、自定义 Startup、Docker 内网构建，这次升级里通常还会额外碰到行为差异。

升级前准备​

1. 先安装 .NET 8 SDK​

迁移前先确认本机和 CI 环境都已经具备 .NET 8 SDK。

2. 保证当前项目可回退​

先做这两件事：

  • 确保项目已经纳入 Git 管理
  • 升级前工作区保持干净，便于逐步回归和快速回滚

3. 统一采用“先替换、再编译、再回归”的节奏​

这次迁移里有一批内容非常适合全局替换，建议优先处理：

  • TargetFramework
  • 包名变更
  • 命名空间变更
  • 明确的拼写修正

必改项​

下面这些内容，基本可以视为 2.2.0 -> 3.0.0 的必改项。

1. 项目目标框架升级到 net8.0​

全局替换时，重点看这两种写法：

原值目标值
<TargetFramework>net6.0</TargetFramework><TargetFramework>net8.0</TargetFramework>
<TargetFrameworks>net6.0</TargetFrameworks><TargetFrameworks>net8.0</TargetFrameworks>

2. Aegis 相关 NuGet 包整体升级到 3.x​

升级时应统一把解决方案中的 Aegis 包提升到 >= 3.0.0-preview1 的当前目标版本，不要混用 2.2.0 和 3.x。

优先原则：

  • 先统一 Aegis 包版本
  • 再处理包名更名
  • 最后编译并解决剩余 API 差异

3. 包名更名​

3.x 中有几项是直接换包名的，常见的全局替换如下：

原值目标值
Aegis.SignalRAegis.Net.SignalR
Aegis.EncryptionAegis.Security.Encryption
Aegis.Generic.IdGeneratorAegis.IdGenerator

4. 常见代码替换​

下面这些是升级里最常见的源码层修正：

原值目标值
return FaliedResult(return FailedResult(
CustomeUserCustomUser
using Aegis.Encryption;using Aegis.Security.Encryption;
using Aegis.Core.Authorization.Models;using Aegis.Core.Authentication.Models;
base(fsql, null, null)base(fsql)

5. 启动方式切换到 AegisApplication​

如果旧项目还保留旧版 Program 启动方式，当前主线应统一收口到：

AegisApplication.Run(args);

6. 引入并核对 Component.deps.json​

3.x 的组件装配是迁移主线之一。迁移后要显式核对：

  • 组件是否放在 Services
  • 是否还需要同时放在 Middlewares
  • 认证、Swagger、SignalR、Prometheus 这类组件是否漏了中间件侧配置

一个最小示意：

{
  "Components": {
    "Services": [
      "BusinessServices",
      "Authorization",
      "Swagger"
    ],
    "Middlewares": [
      "Authorization",
      "Swagger"
    ]
  }
}

建议改项​

这些内容不一定每个项目都碰到，但一旦命中，就建议在升级期一起处理。

1. 外部 NuGet 版本同步升级​

如果项目里仍在用旧版本外部依赖，建议一并收口。当前升级材料里重点点名了两项：

包名建议版本
Newtonsoft.Json13.0.4
FreeSql.Provider.SqlServer3.5.303

2. ICustomStartup 补齐新成员​

如果项目实现了 ICustomStartup，迁移到 3.x 时要注意接口成员变化，当前需要实现新的 ConfigureInitializer。

3. IBrokerFilter 改用新命名空间​

如果项目接了 Broker 过滤器，升级时注意引用：

using Aegis.Net.Broker.Filters;

4. CurrentUser 命名空间迁移​

当前用户信息相关类不再按旧版授权命名空间理解，迁移时要按新的认证命名空间修正引用。

按场景补的调整项​

使用了 SignalR​

如果项目用了 SignalR，迁移后要显式确认跨域策略是否仍然完整。常见场景下需要继续在中间件阶段启用 CORS，例如：

public void Configure(IApplicationBuilder app)
{
    app.UseCors("CorsPolicy");
}

使用了认证鉴权​

如果项目运行时报错：

当前未注入用户管理服务,请注入用户管理服务(IUserManager)后再使用Authorize

通常不是用户管理逻辑本身坏了，而是组件装配没有启用认证。先检查 Component.deps.json 是否已经加入 Authentication。

Linux 内网环境 / Docker 构建​

在 Linux 内网环境下，.NET 8 默认启用 NuGet 包签名验证，网络慢或验证超时时会让 restore 明显变慢。
如果你们是内网 Docker 构建，可以在 Dockerfile 的 build 阶段加上：

ENV DOTNET_NUGET_SIGNATURE_VERIFICATION=false

推荐升级顺序​

建议按下面顺序推进，而不是想到哪改到哪：

  1. 安装 .NET 8 SDK，确认本地和 CI 环境一致。
  2. 统一升级 Aegis 包版本到 3.x。
  3. 全局替换包名、命名空间和已知代码差异。
  4. 把 TargetFramework 统一切到 net8.0。
  5. 引入或重构 Component.deps.json。
  6. 把 Program 收口到 AegisApplication.Run(args)。
  7. 编译并修正剩余错误。
  8. 针对实际用到的组件逐项回归。

升级后优先回归什么​

建议至少回归下面这些内容：

工程启动​

  • 项目是否能正常 restore
  • 项目是否能正常编译
  • 项目是否能正常启动
  • AegisApplication 是否按预期加载组件

组件装配​

  • Component.deps.json 是否被复制到输出目录
  • Services 组件是否都已生效
  • Middlewares 组件是否都已生效

业务主链路​

  • 认证接口能否正常登录和获取用户
  • Controller 到 Service 的 DI 是否正常
  • Repository / FreeSql 是否正常工作
  • 事件总线、Broker、SignalR 等实际使用到的组件是否都能跑通

部署与构建​

  • Docker 构建是否仍然正常
  • Linux 内网环境的 restore 是否明显超时
  • 发布产物在目标服务器上是否能正常启动

常见升级问题​

编译通过了，但运行时报认证相关异常​

优先检查 Component.deps.json 是否启用了 Authentication，不要只盯着业务代码本身。

升级后 Broker 相关代码找不到过滤器接口​

通常是命名空间没改，优先检查：

using Aegis.Net.Broker.Filters;

SignalR 升级后前端连不上​

除了包名变更，还要继续检查：

  • 是否用了新包名 Aegis.Net.SignalR
  • 是否保留了跨域策略
  • 是否把需要的中间件配置补齐

Docker / Linux 构建特别慢​

优先怀疑 .NET 8 下的 NuGet 签名验证，在内网环境中可先验证是否需要加：

ENV DOTNET_NUGET_SIGNATURE_VERIFICATION=false

继续往下看哪些文档​

迁移落地时，建议继续跳到这些页：

当前页的维护口径​

后续继续补升级页时，默认保持这条语义：

  • 这是一套 Aegis 2.2.0 -> 3.0.0 / 3.x 的迁移文档
  • .NET 版本变化 是其中一部分，但不是全部
  • 页面重点应放在迁移成本控制、替换路径和回归验证，而不是功能介绍