AspectCore 3.0.0 变更日志(Changelog)

July 26, 2026 · View on GitHub

覆盖范围:v2.4.0 → v3.0.0。本篇是结构化的变更清单,按 特性 / 性能 / 修复 / 破坏性变更 / 工程 分节列出。 发布背景与研发过程的叙事版本见同目录的 v3.0.0.md,两篇互补。

⚠️ 升级须知:3.0.0 是大版本升级,目标框架显著收窄——移除了 .NET Framework(net461)与 netstandard2.0/2.1 支持。仍运行在这些框架上的消费者无法直接升级。升级前请先阅读下方 💥 Breaking Changes 一节。

版本坐标

版本提交日期说明
v2.4.0dfd5cf62023-05-25netstandard2.0 时代的最后一个稳定版(本次变更的基线)
v2.6.3635a6a52026-07-15中间版本
v3.0.0-beta.188a11d82026-07-21首个 3.0 预览
v3.0.0-rc.1ed932362026-07-25候选发布

自 v2.4.0 至 HEAD 共 137 个提交。

🚀 新特性

Source Generator 编译期代理引擎(全新引擎)

在既有的 DynamicProxy 运行时引擎之外新增一套基于 Roslyn 的编译期代理引擎,在编译时为被拦截方法生成强类型代理代码,是 NativeAOT 支持的基础。

  • bff678b — 以 AST 架构重构 proxy emit(#341)
  • 05c19b8 — Source Generator GA 改进:多程序集、泛型、AOT、inline activation(#348)

NativeAOT AOP 支持(编译期调度委托)

Source Generator 在编译期生成调度委托,运行时直接调用,使 AOP 拦截能够在 NativeAOT 发布下工作。

  • 38f71bc — NativeAOT AOP 支持(#392)
  • d43c4b3 — 强化 NativeAOT 下的 Source Generator 覆盖(#402)

Castle DynamicProxy 迁移工具包 + 竞品 benchmark

  • 3cc2087 — 面向 Castle DynamicProxy 用户的迁移工具包,附竞品 benchmark(#397)

C# 语言特性代理支持

补齐 C# 9 ~ C# 13 语言特性在代理生成中的适配:

  • 2733202 — C# 语言特性 Emit 适配(基础,#375)
  • 11ad20b — C# 12 主构造函数 + C# 13 params collections(#376)
  • 3f8669d — ref struct 拒绝(rejection)+ scoped 参数(#377)
  • a748efc — C# 13 partial properties(#378)
  • 4bf323d — init-only / required members(#381)
  • 5770dbb — async enumerable(IAsyncEnumerable,#382)
  • fe319f9 — interpolated string handler + Index / Range(#383)
  • ea68a9c — C# 9 record 类型(#384)
  • bbece5a — ref / ref readonly 返回(#385)

⚡ 性能优化

多 TFM 综合性能优化(Phase 1-3)

  • 47c5a83 — 分三个阶段的综合优化(#400):
    • Phase 1:消除热路径分配(适用于全部目标框架)
    • Phase 2:net8.0+ 条件优化 —— ObjectPool<SourceGeneratedAspectContext>、FrozenDictionary、UnsafeAccessor
    • Phase 3:PoolingAsyncValueTaskMethodBuilder + 泛型方法缓存
    • net6.0 走 fallback 路径,不使用上述新 API
  • 69eb544 — 缓存 pipeline delegate,Source Generator 代理改用 Array.Empty(#399)

对外性能数字

场景v2.x(DynamicProxy)v3.0(Source Generator)
同步方法拦截220 ns / 360 B112 ns / 112 B
ValueTask<T>1,975 ns / 929 B1,514 ns / 232 B
NativeAOT 冷启动不可用18 ms

经三轮优化后,Source Generator 引擎相较 DynamicProxy 约快 49%、内存分配约少 69%。

📊 数据来源:以上数字来自项目自述与 BenchmarkDotNet 产物,并非本文档独立复现的测量结果;实际收益随运行时、目标框架与工作负载而异。

🐛 Bug 修复

依赖注入(DI)

  • b7769fa — 修复内置 DI 容器的多个问题(#331 / #271 / #254,经由 #401 合并)
  • 6df4161 — 修复 keyed service 在核心 DI 管道中的解析(#389)
  • d7750bf — 修复 IServiceResolver 的 keyed service 解析(#387)
  • dbccd10 — 修复 ServiceValidator 的 keyed service 解析(#326)
  • f1b6d9b — 服务 scope 校验与 Microsoft DI 对齐兼容(#336)

拦截

  • 8b991e0 — 修复调用 internal 类的非代理方法时抛出 MethodAccessException(#274)
  • 9467eb1 — 修复工厂(factory)注册服务的拦截(#235)
  • f34af55 — 修复 ServiceInterceptor 的 AllowMultiple 因 .Distinct() 未生效的问题

💥 Breaking Changes(升级前必读)

1. 目标框架收窄(影响最大)

3.0.0 移除了旧运行时的目标框架:

目标框架(TFM)
v2.4.0net7.0;net6.0;netstandard2.1;netstandard2.0;net461
3.0.0net10.0;net9.0;net8.0;net6.0

被移除的目标框架:net461(.NET Framework 4.6.1)、netstandard2.0、netstandard2.1。

  • 受影响者:仍运行在 .NET Framework 或仅依赖 netstandard2.0/2.1 的项目无法升级到 3.0.0,需要停留在 2.x 分支,或先迁移到 .NET 6+ 运行时。
  • 原因:NativeAOT 支持要求 .NET 7+;默认接口方法(DIM,Default Interface Members)要求 .NET Core 3.0+。这两项能力无法在被移除的框架上实现。

2. 新增 NuGet 包

  • AspectCore.SourceGenerator — 编译期代理引擎
  • AspectCore.Extensions.CastleCompat — Castle DynamicProxy 兼容 / 迁移支持

3. 默认引擎不变

默认代理引擎仍为 DynamicProxy,以降低现有用户的迁移成本;Source Generator 引擎为 opt-in(按需启用)。因此从 2.x 升级到 3.0(且已在受支持的目标框架上)时,拦截行为保持一致,不会被动切换到新引擎。

4. 迁移步骤

目标框架收窄与引擎选型的详细迁移步骤,详见升级指南。

🏗️ 工程与 CI

  • 7587d88 — CI 从 AppVeyor 迁移到 GitHub Actions(#349)
  • 16d097a — 测试覆盖率提升至 core 98% / extensions 90%,新增 2462 个测试(#353);当前测试总数 2800+
  • b0133a3 — CI 增加 coverage、lint、CodeQL、.NET analyzers 门禁(#369)

相关链接