当应用规模扩大后，同一条 SQL 语句可能由多个业务模块、多个方法同时生成。数据库慢查询日志中出现的高频查询，如果没有上下文信息，排查起来非常耗时。EF Core 的查询标记正是为解决这个定位问题而设计：它会在最终生成的 SQL 命令文本最前面插入一段注释，注释内容由开发者通过 TagWith 指定。这个动作不改变查询逻辑，也不影响执行结果，只增加极小的表达式树处理成本。因此，在需要调试、审计或做日志检索时，它几乎是零侵入的排查工具。
本文围绕基本用法、日志配置、自动定位和实战避坑四个部分展开，帮助你把查询标记真正用起来。
查询标记的基本用法与 SQL 输出效果
TagWith 是 IQueryable<T> 的扩展方法，位于 Microsoft.EntityFrameworkCore 命名空间下。它的用法非常简单，通常放在 ToList、FirstOrDefault 等终止操作之前，调用方式形如 .TagWith("标记内容")。传入的字符串会作为 SQL 注释附加到最终生成的命令文本最前面。下面这段代码给待发货订单查询加了一个固定标记。
using var context = new AppDbContext();
var orders = context.Orders
.Where(o => o.Status == "Pending")
.TagWith("OrderModule:GetPendingOrders")
.ToList();
启用 EF Core 日志后，控制台会输出类似的 SQL 语句。可以看到，注释位于 SELECT 之前，以两个短横线开头，这正是数据库 SQL 注释的标准写法。即使查询被数据库网关、连接池或 SQL Profiler 捕获，这个注释也会一直保留。
-- OrderModule:GetPendingOrders SELECT [o].[Id], [o].[CustomerId], [o].[OrderDate], [o].[Status] FROM [Orders] AS [o] WHERE [o].[Status] = N'Pending'
需要注意的是，TagWith 只对查询命令生效。像 SaveChanges 生成的 INSERT、UPDATE、DELETE，以及 ExecuteDelete、ExecuteUpdate 这类批量命令，并不会携带查询标记。如果需要追踪这些写操作，通常要依靠拦截器或审计日志另行处理。此外，标记内容不会影响 SQL 的执行计划，数据库引擎解析到注释后会直接忽略。
如果希望从多个维度标识一条查询，可以多次调用 TagWith。EF Core 会把这些标记按照调用顺序拼接在同一行注释中，之间用空格分隔。常见做法是把模块名和方法名拆开，例如：
var query = context.Orders
.TagWith("Module: Sales")
.TagWith("Method: GetHighValueOrders")
.Where(o => o.Total > 1000)
.ToList();
最终生成的注释会是 -- Module: Sales Method: GetHighValueOrders。这种拆分方式便于在日志系统中按前缀过滤，也方便统计不同模块的 SQL 出现频率。
配置日志并查看查询标记
要让查询标记发挥作用，必须能够让 EF Core 输出生成的 SQL。最简单的方式是在 DbContext 的 OnConfiguring 方法中调用 LogTo，把数据库命令输出到控制台或调试窗口。下面的示例使用 SQL Server 提供程序，并记录 Information 级别日志。
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
optionsBuilder
.UseSqlServer("Server=.;Database=Shop;Trusted_Connection=True;")
.LogTo(Console.WriteLine, LogLevel.Information);
}
如果项目使用 ASP.NET Core，更适合通过 appsettings.json 配置日志分类。数据库命令对应的分类名称是 Microsoft.EntityFrameworkCore.Database.Command，可以单独调高该分类的日志级别，而不影响其他组件的日志噪声。配置后，所有执行的 SQL 命令都会进入日志管道，查询标记会原样出现在 SQL 文本开头。
默认情况下，EF Core 不输出参数值，只显示参数占位符。这是为了避免敏感数据进入日志。查询标记不受此限制，即使不开启 EnableSensitiveDataLogging，标记内容也会完整打印出来。因此必须把标记视为日志可见内容，绝不能放入密码、身份证号、手机号或用户输入等敏感信息。这一点在后面的避坑部分还会进一步讨论。
使用 TagWithCallSite 自动定位查询来源
手工添加查询标记虽然直观，但开发人员经常忘记为新查询打标记，或者复制代码后标记名称与实际位置越来越不一致。EF Core 6 引入的 TagWithCallSite 方法可以自动填充调用位置信息。它不需要传入任何字符串，调用后会在 SQL 注释中附带源文件路径和行号。
var customers = context.Customers
.Where(c => c.City == "Berlin")
.TagWithCallSite()
.ToList();
生成的 SQL 注释会类似下面这样。只要修改文件路径或移动查询位置，再次执行时注释中的行号会自动更新，不需要手动维护。
-- File: /src/Data/Repositories/CustomerRepository.cs:42 SELECT [c].[Id], [c].[Name], [c].[City] FROM [Customers] AS [c] WHERE [c].[City] = N'Berlin'
TagWithCallSite 可以与 TagWith 同时使用。EF Core 会累积所有标记，例如先调用 TagWith("CustomerQuery")，再调用 TagWithCallSite()，生成的注释会同时包含业务标记和文件位置。这种组合特别适合仓储层复杂查询分散在多个文件的项目，既能按业务含义检索，又能精确回溯到代码位置。
不过，TagWithCallSite 会把源码目录结构写入日志或 SQL Profiler。如果日志可能被外部人员查看，或者生产环境对源码路径有保密要求，建议只在开发、测试或本地排查时使用，生产环境改用固定的业务标记。否则运维同事可能无法理解路径含义，反而增加日志阅读成本。
实战避坑与标记规范
查询标记最大的价值在于可检索性，因此标记内容应当保持稳定。不要把时间戳、随机数、订单号或用户输入拼进标记。例如 .TagWith($"OrderQuery-{Guid.NewGuid()}") 这类写法虽然技术上可行，但每次生成的标记都不同，无法用于日志聚合分析。更合理的格式是使用模块名加动作名，例如 OrderModule:GetPendingOrders。需要区分不同租户或业务线时，可以在固定前缀后加一个稳定的租户标识，而不是完整用户数据。
从性能角度看，查询标记只是往表达式树中增加一个节点，并额外产生一行 SQL 注释，成本基本可以忽略。但这并不意味着每条查询都需要打标记。对于简单的、只在一个地方出现的单表查询，标记意义不大；而对于连接多个表、条件复杂、会被多个入口调用的查询，标记能显著提高问题定位效率。通常建议在仓储层、复杂报表查询、跨模块共享查询中集中使用。
如果项目已经实现了 IDbCommandInterceptor，还可以在拦截器中读取 CommandText，识别注释里的业务标记并做进一步处理，例如统计各标记的执行次数和平均耗时。因为注释就包含在命令文本开头，解析逻辑并不复杂。这种用法可以把查询标记从单纯的调试辅助，提升为轻量级 SQL 执行监控手段。
最后强调一点：查询标记永远不要包含敏感数据。即使关闭了敏感数据日志，标记也会完整输出到控制台、文件、SQL Profiler 或第三方 APM 工具。任何可能被日志收集的内容都应该假设它会被长期保存并被不同角色查看。把标记定义为无业务敏感信息的稳定标识，是使用该功能必须遵守的底线。
