企业官网建设流程全解析

如何正确使用EntityFrameworkCore.Triggered异步触发器：避开sync-over-async死锁陷阱的完整指南

【免费下载链接】EntityFrameworkCore.TriggeredTriggers for EFCore. Respond to changes in your DbContext before and after they are committed to the database.项目地址: https://gitcode.com/gh_mirrors/en/EntityFrameworkCore.Triggered

EntityFrameworkCore.Triggered 是一个为 EF Core 添加"触发器"能力的开源库，它让你可以在 DbContext 的改动写入数据库前后执行自定义逻辑。它的**异步触发器（async trigger）**支持await查询数据库、发送邮件等耗时操作，但使用不当会掉进 sync-over-async 死锁陷阱。本文手把手教你正确编写异步触发器、注册触发器，并彻底避开死锁。

一、EntityFrameworkCore.Triggered 异步触发器能做什么？

想象一下：每当一个新的Student被保存时，你希望自动帮他报名所有必修课程。手写if判断散落在各处代码里既繁琐又容易遗漏。异步触发器把这类"保存前后自动执行"的逻辑集中到独立的触发器类中：

• BeforeSave 异步触发器：实体写入数据库前执行，可以修改实体、向 DbContext 添加新实体（改动会一并入库）；
• AfterSave 异步触发器：实体成功入库后执行，适合发邮件、写审计日志等副作用操作；
• AfterSaveFailed 异步触发器：保存失败（如数据库约束冲突）时执行，方便记录异常。

官方示例里就有一个典型的 BeforeSave 异步触发器：学生新增时自动报名必修课，见 samples/2 - PrimarySchool/Triggers/StudentSignupToMandatoryCourses.cs（学生报名逻辑）以及 samples/3 - StudentManagerAspNetCore/Triggers/Students/SignupToMandatoryCourses.cs（完整 Web 版示例）。

二、异步触发器接口速览：IAfterSaveAsyncTrigger 与 IBeforeSaveAsyncTrigger

异步触发器接口都定义在EntityFrameworkCore.Triggered.Abstractions包中，命名空间为EntityFrameworkCore.Triggered，核心接口如下：

接口源码非常简洁，以 src/EntityFrameworkCore.Triggered.Abstractions/IAfterSaveAsyncTrigger.cs 为例：

public interface IAfterSaveAsyncTrigger<TEntity> where TEntity : class { Task AfterSaveAsync(ITriggerContext<TEntity> context, CancellationToken cancellationToken); }

一个真实的异步触发器长这样（自动报名必修课，触发器内通过await查询数据库）：

public class SignupToMandatoryCourses : IBeforeSaveAsyncTrigger<Student> { readonly ApplicationDbContext _applicationContext; public SignupToMandatoryCourses(ApplicationDbContext applicationContext) { _applicationContext = applicationContext; } public async Task BeforeSaveAsync(ITriggerContext<Student> context, CancellationToken cancellationToken) { // 关键点1：触发器内部使用异步数据库查询 var mandatoryCourses = await _applicationContext.Courses .Where(x => x.IsMandatory) .ToListAsync(cancellationToken); foreach (var course in mandatoryCourses) { if (_applicationContext.StudentCourses.Find(context.Entity.Id, course.Id) == null) { _applicationContext.StudentCourses.Add( new StudentCourse { Student = context.Entity, Course = course }); } } } }

💡ITriggerContext<TEntity>提供Entity（当前实体）和ChangeType（Added / Modified / Deleted）属性，帮你判断实体处于什么变更状态。

三、最快配置方法：三步注册异步触发器

注册分三步走：

第 1 步：安装 NuGet 包EntityFrameworkCore.Triggered（含核心实现）；

第 2 步：在配置DbContext时调用UseTriggers()并注册触发器：

services.AddDbContext<ApplicationDbContext>(options => { options.UseTriggers(triggerOptions => { triggerOptions.AddTrigger<SignupToMandatoryCourses>(); }); });

第 3 步：像平常一样调用SaveChangesAsync，触发器会自动生效。

如果你希望自动扫描整个程序集里的所有触发器，EntityFrameworkCore.Triggered.Extensions包提供了更省心的方式（见 src/EntityFrameworkCore.Triggered.Extensions/ServiceCollectionExtensions.cs）：

options.UseTriggers(t => t.AddAssemblyTriggers());

四、sync-over-async 死锁陷阱：为什么会卡死你的线程

这是全文最重要的一节 ⚠️。

问题本质：如果你调用的是同步版SaveChanges()，但注册了异步触发器，库只能"阻塞当前线程"等待异步触发器执行完成（即 sync-over-async）。在 Web 等线程池受限的场景下，被阻塞的线程一直不释放，而异步操作完成后又需要一个线程池线程来继续——线程池被耗尽，程序就死锁了。

从拦截器源码 src/EntityFrameworkCore.Triggered/Internal/TriggerSessionSaveChangesInterceptor.cs 可以看到：同步入口SavingChanges和异步入口SavingChangesAsync是两条完全独立的路径，异步入口会真正await触发器：

_triggerSession.RaiseBeforeSaveTriggers(); await _triggerSession.RaiseBeforeSaveAsyncTriggers(cancellationToken).ConfigureAwait(false);

而触发器编排核心 src/EntityFrameworkCore.Triggered/TriggerSession.cs 中的RaiseAsyncTriggers方法，才是异步触发器被await执行的真正场所（支持取消令牌、按优先级顺序执行）。

4 条规则，一次避开死锁

正确的保存调用示例：

context.Students.Add(newStudent); await context.SaveChangesAsync(ct); // ✅ 异步保存，异步触发器被 await 执行 // context.SaveChanges(); // ❌ 会阻塞线程等待异步触发器，可能死锁

五、进阶技巧：让异步触发器更好用

• 取消令牌要透传：触发器方法都带有CancellationToken参数，请把它传给所有内部await调用，让取消请求及时生效；
• 控制执行顺序：实现ITriggerPriority接口可自定义优先级（数值小先执行），同类型的多个触发器按注册顺序执行；
• 级联触发（Cascading）：BeforeSave 触发器修改实体图后，可以再次触发其他触发器。默认开启EntityAndType级联策略并限制最大递归次数防止死循环，可通过UseTriggers的CascadeBehavior(...).MaxRecusion(20)调整（见 src/EntityFrameworkCore.Triggered/Infrastructure/CascadeBehavior.cs）；
• 生命周期触发器：IBeforeSaveStartingAsyncTrigger、IAfterSaveCompletedAsyncTrigger等接口在整个保存生命周期只执行一次，适合做批量统计（接口位于 src/EntityFrameworkCore.Triggered.Abstractions/Lifecycles/ 目录）；
• 保存失败处理：用IAfterSaveFailedAsyncTrigger<T>捕获DbUpdateException，在触发器内可尝试修正数据后再次保存；
• Roslyn 分析器帮你迁移：v4 起同步/异步触发器彻底分离。仓库自带分析器（见 EntityFrameworkCore.Triggered.Analyzers/EntityFrameworkCore.Triggered.Analyzers/TriggerMigrationAnalyzer.cs），会扫描你代码中"同步接口 + Task 方法"的旧签名（诊断码 EFCT001），并提供 CodeFix 一键改写为IBeforeSaveAsyncTrigger<T>/IAfterSaveAsyncTrigger<T>等新接口。

六、总结：3 个要点带走

1. 异步触发器接口（IBeforeSaveAsyncTrigger<T>/IAfterSaveAsyncTrigger<T>）让触发器可以await数据库查询和外部服务，逻辑集中、不侵入业务代码；
2. 注册只需一行UseTriggers(...)，配合AddAssemblyTriggers()可全自动发现触发器；
3. 永远用SaveChangesAsync搭配异步触发器——这是避开 sync-over-async 死锁的黄金法则。

更多完整用法可参考仓库中的示例项目：samples/2 - PrimarySchool/Program.cs 演示了控制台应用中最小化的触发器注册流程。

【免费下载链接】EntityFrameworkCore.TriggeredTriggers for EFCore. Respond to changes in your DbContext before and after they are committed to the database.项目地址: https://gitcode.com/gh_mirrors/en/EntityFrameworkCore.Triggered