FlexLabs.Upsert 排错清单：InvalidMatchColumnsException 与 UnsupportedExpressionException 全解

FlexLabs.Upsert 排错清单：InvalidMatchColumnsException 与 UnsupportedExpressionException 全解

【免费下载链接】FlexLabs.UpsertFlexLabs.Upsert is a library that brings UPSERT functionality to common database providers for Entity Framework in their respective native SQL syntax项目地址: https://gitcode.com/gh_mirrors/fl/FlexLabs.Upsert

使用 Entity Framework Core 做数据同步时，FlexLabs.Upsert 是最受欢迎的 UPSERT 库之一——它把"插入或更新"一步到位，让各数据库（SQL Server、MySQL、PostgreSQL、Oracle、SQLite 等）使用各自的 native SQL 语法。不过很多新手第一次调用Upsert().On().WhenMatched().Run()时，就会被两个异常拦下：InvalidMatchColumnsException（匹配列不合法）和UnsupportedExpressionException（表达式不受支持）。这份排错清单帮你 3 分钟定位问题根源，快速修复。

两个异常，一张速查表

两者都在命令构建阶段（而非真正执行 SQL 之前）被抛出，属于"防御性报错"——它们把问题拦在了最前端，避免了生成错误 SQL。

InvalidMatchColumnsException：为什么不能用自增主键匹配？

触发场景

当你没有调用On()，或On()里包含了自增列时，就会命中这条报错。库的默认行为是拿实体的主键作为匹配列，如果主键是 Identity 自增列（如Id），问题就来了：插入一条全新记录时，数据库还没生成自增值，MERGE/INSERT … ON CONFLICT无从匹配。

检查逻辑位于 UpsertCommandBuilder.cs：

if (!_allowIdentityMatch && matchProperties.Any(p => p.ValueGenerated != ValueGenerated.Never)) throw new InvalidMatchColumnsException();

异常定义在 InvalidMatchColumnsException.cs，报错原文为：

Using autogenerated / identity keys as the upsert match expression is not supported. Please pick a non generated unique key.

修复方法一：换一个"非生成"的唯一键匹配（推荐）

业务上真正需要匹配的通常也不是自增 Id，而是业务唯一键，例如UserID + Date：

dbContext.DailyVisits .Upsert(visit) .On(v => new { v.UserID, v.Date }) // 用业务唯一键，而不是自增 Id .WhenMatched(v => new DailyVisit { Visits = v.Visits + 1 }) .RunAsync();

前提是UserID + Date上建有唯一索引，否则 upsert 会退化成重复插入。

修复方法二：显式允许 Identity 匹配

如果你确实需要按自增键匹配（例如导入已有记录、Id 已经指定），调用 AllowIdentityMatch() 即可放行：

dbContext.Orders .Upsert(order) .On(o => o.OrderId) // 自增键 .AllowIdentityMatch() // 明确告知：我知道自己在做什么 .Run();

💡 经验法则：优先方案一。upsert 的匹配列应当是"外部世界可确定"的业务键，而不是依赖数据库生成的值。

UnsupportedExpressionException：更新表达式里的"雷区"

这个异常定义在 UnsupportedExpressionException.cs，它有一个HelpLink属性，指向官方对支持表达式清单的说明。抛出的原文是：

This type of expression is not currently supported: … Simplify the expression, or try a different one.

注意：错误信息里会完整打印出有问题的表达式，先把它读出来，再对照下面 4 种常见雷区。

雷区 1：WhenMatched 里写了复杂表达式

WhenMatched中允许的值大致是：成员访问、常量、简单的+/-/比较运算、new初始化器等。如果你写出了嵌套 LINQ 调用、方法调用链、复杂三元组合，解析器会在 ExpressionParser.cs 处拒绝。

✅ 能翻译的例子：

.WhenMatched(v => new DailyVisit { Visits = v.Visits + 1 }) // 数据库列 + 常量

❌ 容易炸的例子：

.WhenMatched(v => new DailyVisit { Visits = v.History.Select(h => h.Count).Sum() + 1 // 聚合 + 成员导航，翻译不了 })

雷区 2：修改 JSON 列的成员

对 owned 关系映射成 JSON 的列（如 Postgres 的 jsonb），修改其中某个属性（如v.Profile.Name = "x"）会抛出：

Modifying JSON members is not supported. Unsupported Expression: …

见 UnsupportedExpressionException.cs。

雷区 3：读取 JSON 列的成员

在更新表达式中读取JSON 子成员（如Visits = v.Profile.VisitCount + 1）同样不被支持：

Reading JSON members is not supported.

检查点在 UpdateExpressionVisitor.cs。

✅ 应对办法：把 JSON 列整体替换（例如赋一个新的完整对象），或者在应用层先查再算。

雷区 4：MySQL 上不用 UpdateIf 条件更新

UpdateIf让你只在满足条件时才更新已有行（如"仅当新值更大时覆盖"），但在 MySQL 上，由于INSERT … ON DUPLICATE KEY UPDATE语法限制，条件更新直接不可用，会抛出：

Using conditional updates is not supported in MySQL due to database syntax limitations.

见 UnsupportedExpressionException.cs。其他数据库（SQL Server、PostgreSQL 等）则正常支持，测试用例可参考 RelationalCommandRunnerTestsBase.cs。

✅ 应对办法：MySQL 下改用WhenMatched中内置Math.Max之类的表达式（可翻译的部分）在值层面兜底，或先查询再决定。

终极开关：WithFallbackExpressionCompiler

如果内置解析器不认识的表达式其实很简单，可以启用后备表达式编译器，用 .NET 端求值换取更广的支持面（代价是更新表达式不再完全下推、性能略低）：

dbContext.Rates .Upsert(rate) .On(r => r.Currency) .WhenMatched(r => new Rate { Value = r.Value * 1.01m }) .WithFallbackExpressionCompiler() // 支持更多表达式类型 .Run();

方法说明在 UpsertCommandBuilder.cs。

高频报错排查清单 🧰

按下面顺序过一遍，覆盖 90% 的现场问题：

1. 报错是 InvalidMatchColumnsException？
   • 检查On()的列是否含自增/ValueGenerated列 → 换成业务唯一键；
   • 确需按自增键匹配 → 加.AllowIdentityMatch()。
2. 报错是 UnsupportedExpressionException？
   • 先看异常消息里打印的表达式原文；
   • 涉及 JSON 列成员（读/写）→ 改为整列赋值；
   • MySQL +UpdateIf→ 该功能在 MySQL 不可用，换方案；
   • 表达式复杂但逻辑简单 → 试.WithFallbackExpressionCompiler()。
3. 其他伴生报错（InvalidOperationException），常见文案与出处见 Resources.resx：
   • Match columns have to be properties of the TEntity class——On()里写的不是实体属性（如写了导航对象或计算列）；
   • Unknown property {0}—— 属性名拼错或该属性未映射到列；
   • Exclude columns should not be excluded twice—— 同一列在多个Exclude()中重复排除；
   • {0} and {1} are mutually exclusive类报错 ——Exclude与WhenMatched、WhenMatched与NoUpdate不可混用。
4. 实体类型未映射：若实体没加进DbContext模型，Upsert()会先抛EntityType must be mapped in DbContext（UpsertExtensions.cs），先把实体注册进模型。
5. 数据库供应商不支持：执行时找不到对应 Runner 会抛DatabaseProviderNotSupportedYet——本库内置 SQL Server / MySQL / PostgreSQL / Oracle / SQLite 五种方言的 Runner（见 Runners 目录），其他供应商需自行注入IUpsertCommandRunner。

常见疑问 FAQ

Q：异常是在"执行 SQL 时"抛的吗？不是。两者都在客户端构建/解析阶段抛出，SQL 尚未下发，数据库零副作用。

Q：On()不写会怎样？默认用实体主键匹配。主键是自增列时就会触发 InvalidMatchColumnsException——这其实是在保护你。

Q：这两个异常能 catch 后降级吗？不建议吞掉。它们说明"意图与语法不匹配"，降级执行往往掩盖数据正确性问题；正确做法是按清单修配置。

小结

• InvalidMatchColumnsException= 匹配列用了自增键 → 换业务唯一键，或AllowIdentityMatch()；
• UnsupportedExpressionException= 表达式翻译不了 → 先读异常消息原文，简化表达式、整列赋值 JSON、MySQL 避开UpdateIf，或开WithFallbackExpressionCompiler()；
• 所有报错文案集中在 Resources.resx，可对照源码逐条定位。

按这份清单走一遍，FlexLabs.Upsert 的两大异常基本不会再让你卡住超过 10 分钟。🚀

【免费下载链接】FlexLabs.UpsertFlexLabs.Upsert is a library that brings UPSERT functionality to common database providers for Entity Framework in their respective native SQL syntax项目地址: https://gitcode.com/gh_mirrors/fl/FlexLabs.Upsert