1.概要

在软件开发过程中，调试和诊断应用程序的运行状态是至关重要的步骤。这篇文章将分享Trace对象的使用场景和使用方法，包括在跨平台下的兼容（Windows、Linux）和AOT编译下的使用（完整代码在文章底部链接，如果有帮助希望像雄鹰一下狠狠的点一下star）。

1.1 Trace 对象的作用

Trace 是 C# 提供的一个调试和诊断工具，它允许开发者在应用程序运行时输出信息，从而帮助识别和解决问题。Trace 对象的主要功能包括：

• 监控应用程序状态：Trace 可以在程序的任何地方插入，以输出当前的变量值、执行路径及状态信息，有助于了解程序的执行情况和逻辑流程。
• 问题定位：通过在关键代码位置使用 Trace 输出信息，开发者可以快速定位问题所在，减少故障排查时间。
• 性能分析：通过输出特定时间点的信息，开发者可以分析程序的性能瓶颈和延迟问题。
• 运行时诊断：Trace 可以与条件断点结合使用，帮助在特定条件下抓取诊断信息，避免过量输出。

1.2 既然有Log 为什么还要Trace？它们的功能非常重叠！

1.2.1 起源与定位不同

• Trace（及Debug） ： 是 .NET 框架原生提供的调试与跟踪基础设施（位于System.Diagnostics命名空间），诞生于 .NET 早期，设计初衷是实时诊断程序执行流程，主要用于开发和测试阶段的代码调试、流程跟踪（如方法调用顺序、参数传递等）。 它更贴近 "程序内部运行轨迹的记录"，强调对代码执行过程的实时观察。
• 日志（Logging）： 通常指更通用的事件记录机制（如ILogger、log4net、Serilog 等），核心目标是持久化记录程序关键事件（如错误、警告、业务操作等），用于生产环境的问题排查、业务分析、监控告警等。 它更侧重 "事件的持久化存储与后期分析"。

1.2.2 使用阶段与环境不同

• Trace：

• 与程序执行流程深度绑定，可跟踪代码的细粒度行为（如方法进入 / 退出、循环次数、变量变化等）。

• 配合 TraceListener可输出到控制台、文件、调试器等，但默认配置下更适合开发 / 测试环境（可通过编译符号控制是否生效，如TRACE符号）。

• 生产环境中通常仅保留关键跟踪（如性能指标），避免过多输出影响性能。

• 日志：

• 主要面向生产环境，需要记录的信息更宏观（如用户登录、订单创建、系统异常等）。

• 具备完善的级别控制（Info/Warn/Error/Fatal）、格式化、持久化（文件、数据库、日志服务）、滚动策略等功能，适合长期存储和检索。

1.2.3 功能特性不同

• Trace的特性：

• 轻量级，无额外依赖（基于 .NET 原生 API）。

• 支持 跟踪开关（TraceSwitch）控制输出粒度，可动态开启 / 关闭不同级别的跟踪。

• 可与性能计数器、诊断工具（如 Visual Studio 调试器）集成，适合实时性能分析。

• 示例：

  // 跟踪方法调用
  Trace.WriteLine("进入 UserService.GetUser 方法");
  // 跟踪关键参数
  Trace.WriteLineIf(userId 0, "警告：用户ID为负数", "参数检查");
  

• 日志的特性：

• 功能更丰富，支持结构化日志（JSON 格式）、上下文信息（如用户 ID、请求 ID）、异步写入、日志聚合等。

• 可通过配置动态调整输出目标（如开发环境输出到控制台，生产环境输出到 ELK 栈）。

• 示例（使用 ILogger）：

  // 记录业务事件
  logger.LogInformation("用户 {UserId} 登录成功", userId);
  // 记录异常
  logger.LogError(ex, "订单 {OrderId} 处理失败", orderId);
  

1.2.4 互补而非替代

• Trace适合开发阶段的代码级跟踪，关注 "程序如何运行"；
• 日志适合 生产环境的事件记录，关注 "程序发生了什么"。

2.详细内容

这里继续分享，代码的实现和为什么要使用Trace的原因：

• （1）可以记录组件内部异常或执行流程（可文本记录、控制台输出、方便），细粒度的跟踪程序运行情况，便于调试。

• （2）在组件这种级别的项目中，追求的通常是轻量化和少依赖甚至无依赖第三方组件。

• （3）可兼容不同的平台（Windows、Linux）。

• （4）Dbgview.exe工具可与Trace联动，简单描述一下，能通过Dbgview看到 基础文本信息、消息类别（Category）、进程与线程信息、时间戳等内容（ 根据自己需要添加相关信息到写入方法中 ）。工具也非常轻便只有800kb+，所以在大部分情况下都能便捷使用（Linux上目前没看到对应可用版本，但是可以将这些调试信息写入文件）。

代码实现：

public staticclassTracer
{
//...

static GeneralTracer
{
Trace.Listeners.Clear;

//将调试记录转发到Dbgview.exe工具中查看，由于目前没发现官方有Linux版本的Dbgview.exe所以只实现了windows的。
//如果在Linux操作系统下可通过文本记录的方式查看。
if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
Trace.Listeners.Add(new WindowsOutputDebugListener);
}

//调试记录转发到控制台中查看，例如：IDE的控制台
Trace.Listeners.Add(new TextWriterTraceListener(Console.Out) { Name = "ConsoleListener" });

//调试记录转发到本地文本文件中记录，由于原生的TextWriteTraceListener写入文件容易出现进程占用，所以手写了一个带队列的写入文件实现。
InitializeFileListener;

if (Debugger.IsAttached)
Trace.Listeners.Add(new DefaultTraceListener);

Trace.AutoFlush = true;
_isTracingEnabled = true;
}

private static void InitializeFileListener
{
var today = DateTime.Now.ToString("yyyy-MM-dd");
if (today == _currentLogDate && _fileListener != null)
return;

var logDir = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Logs");
Directory.CreateDirectory(logDir);

var logFileName = Path.Combine(logDir, $"generalupdate-trace {today}.log");
_fileListener = new TextTraceListener(logFileName);

Trace.Listeners.Add(_fileListener);
_currentLogDate = today;
}

//...

public static void Info(string message) => WriteTraceMessage(TraceLevel.Info, message);

public static void Error(string message) => WriteTraceMessage(TraceLevel.Error, message);

private static void WriteTraceMessage(TraceLevel level, string message)
{
if(!IsTracingEnabled)
return;

InitializeFileListener;
var timestamp = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss.fff");
var levelName = GetLevelName(level);
var fullMessage = string.Empty;

try
{
//这里尝试使用#if !NATIVEAOT或者RuntimeInfomation的做法在代码内判断当前是否AOT编译，这两种方式通常无效，这里为了简单在AOT下通过try的 //方式兼容简化输出。

//在AOT下该方法不可使用，因为StackFrame 的工作机制依赖于程序运行时的动态调试信息和调用栈结构，而 AOT 编译的核心是通过静态优化生成高效、 //精简的机器码，必然会剥离动态信息并改变原始调用栈结构。这种本质冲突导致 StackFrame 在 AOT 环境下通常无法正常使用。
var stackFrame = new StackFrame(2, true);
var method = stackFrame.GetMethod;
var className = method.DeclaringType?.Name ?? "UnknownType";
var methodName = method.Name;
var lineNumber = stackFrame.GetFileLineNumber;
var lineInfo = lineNumber > 0 ? $"Line {lineNumber}" : "Line N/A (Line numbers may not be displayed in Release mode)";
fullMessage = $"[{timestamp}] [{levelName}] {className}.{methodName} ({lineInfo}): {message}";
}
catch
{
//为了兼容AOT,在此简化了输出
fullMessage = $"[{timestamp}] [{levelName}] : {message}";
}

Trace.WriteLine(fullMessage);
}

//...
}

运行效果：

这里非常简单的手动引发了一个异常效果如下（左上角Dbgview.exe、左下角IDE、右侧文本记录）。

3.引用

• 在线文档：Trace 类 (System.Diagnostics) | Microsoft Learn

• 示例完整源码，仓库地址：GeneralUpdate/src/c#
  /GeneralUpdate.Common/Shared/Trace at master ·
  GeneralLibrary/GeneralUpdate

• Dbgview工具地址：DebugView - Sysinternals | Microsoft Learn