Hyz.Trace.Weaving.Fody 1.2.3

Hyz.Trace.Weaving.Fody

Hyz.Trace 的 Fody IL 编织器 — 编译时扫描 [Trace] 特性，采用方法外壳包装（Thunk/Wrapper）模式自动织入 TraceScope 包装代码，实现方法级 Span 的零侵入捕获，理论编织成功率 100%。

安装

dotnet add package Hyz.Trace.Weaving.Fody

本包不包含 Hyz.Trace 核心库，需配合以下任一包使用：

• Hyz.Trace.Client（客户端元包，推荐）
• Hyz.Trace（仅核心库）

工作原理

方法外壳包装（Thunk/Wrapper）模式：与传统的内联 IL 修改方式不同，本编织器完全不修改原方法体，而是：

1. 编译时 Fody 加载本 weaver DLL
2. 扫描程序集中所有标注 [Trace] 特性的方法或类
3. 重命名原方法：将原方法重命名为 <MethodName>__TraceOriginal，改为 private，原方法体 IL 保持 100% 不变
4. 生成包装方法：创建一个与原方法签名完全一致的新方法（public/原访问级别）
5. 织入追踪代码：包装方法内部通过 TraceScope.Run() / TraceScope.RunAsync() 调用原方法，自动处理：
   • Span 创建与命名（默认 {TypeName}.{MethodName}）
   • 输入参数捕获
   • 返回值捕获
   • 异常自动捕获与 SetError()
   • 正常完成时 SetOk()
   • using 模式确保 Dispose() 始终执行
6. 对于 ref/out 参数，采用直接 IL 路径避免闭包开销
7. 内部调用自动重定向到包装方法，确保追踪连续性

核心优势：原方法体完全不被修改，从根本上避免了内联编织遇到复杂控制流（多 return、try-catch-finally、using、lock、迭代器、泛型方法、Dictionary 初始化器等）时的 IL 验证失败和 InvalidProgramException。

支持的方法类型

使用示例

using Hyz.Trace;

// 方法级追踪：自动生成 Span，名称为 "UserService.GetUser"
public class UserService
{
    [Trace]
    public User? GetUser(int id)
    {
        // 业务代码...
        return userRepository.Find(id);
    }
}

// 类级追踪：所有 public 实例方法自动生成 Span
[Trace]
public class OrderService
{
    // 会被自动编织
    public Order CreateOrder(CreateOrderRequest request) { /* ... */ }
    
    // 会被自动编织
    public void CancelOrder(int orderId) { /* ... */ }
    
    // 不会被编织：private 方法
    private void InternalHelper() { /* ... */ }
    
    // 不会被自动编织：static 方法（类级 [Trace] 不包含静态）
    // 如需追踪，需显式加 [Trace]
    [Trace]
    public static Order? FindById(int id) { /* ... */ }
}

// 自定义 Span 名称
public class PaymentService
{
    [Trace(Name = "process-payment")]
    public PaymentResult Process(PaymentRequest request) { /* ... */ }
}

// 复杂方法也能正常编织：含 try-catch-finally、多 return、using、泛型、lambda 闭包等
[Trace]
public static HttpResult<T> WebRequest<T>(string url, Dictionary<string, string>? headers = null)
{
    // 任意复杂控制流都不会导致编织失败
    // 原方法体完全保持不变
}

编译日志

编织过程会在 Visual Studio 生成输出中打印详细日志（前缀 [Hyz.Trace.Weaving]）：

• Normal 详细级别：

  • OK {Kind} {MethodName}：编织成功（显示方法类型：SyncVoid/SyncFunc/AsyncTask/AsyncTaskT）
  • SKIP {Source} {MethodName} : {原因}：跳过编织
  • 汇总统计：总计扫描/成功/跳过/失败数量

• Detailed 详细级别：

  • FAIL {MethodName} : {错误信息}：编织失败（带完整异常堆栈）
  • 失败状态始终在 Normal 级别显示为警告

日志示例

[Hyz.Trace.Weaving] =========================================================
[Hyz.Trace.Weaving] 开始扫描程序集: Hyz.Trace.Demo.NetFramework.Console
[Hyz.Trace.Weaving] =========================================================
[Hyz.Trace.Weaving] --- Hyz.Trace.Demo.NetFramework.TraceConsole.Services.OrderService ---
[Hyz.Trace.Weaving]   OK SyncFunc CreateOrder
[Hyz.Trace.Weaving]   OK SyncFunc GetOrder
[Hyz.Trace.Weaving] --- Hyz.Trace.Demo.NetFramework.TraceConsole.Services.SafetyStressService ---
[Hyz.Trace.Weaving]   OK SyncFunc PrivateGeneric
[Hyz.Trace.Weaving]   OK SyncFunc PublicWithUsingAndThrow
[Hyz.Trace.Weaving]   OK SyncFunc MultiBranchServiceCallHandle
[Hyz.Trace.Weaving]   ...
[Hyz.Trace.Weaving] =========================================================
[Hyz.Trace.Weaving] 编织完成: 总计 86, 成功 49, 跳过 37, 失败 0
[Hyz.Trace.Weaving] =========================================================

安全保障机制

1. 原方法体零修改：从根本上避免 IL 损坏
2. 原子提交：新类型/方法先添加到模块树，再生成 IL，失败时自动回滚
3. 运行时保护：TraceScope 公共方法均有 try-catch，追踪异常绝不影响业务代码
4. IL 栈验证：编织完成后验证方法体 IL 栈深度正确性

与元包的关系

Hyz.Trace.Client 元包默认不包含本包，以避免与独立引用时的双重编织冲突。如需 IL 编织能力，请显式安装本包。

依赖

• Fody 6.9.3（自动作为传递依赖引入）
• Hyz.Trace 核心库（需使用者自行引用）

目标框架

netstandard2.0 — 兼容所有支持 .NET Standard 2.0 的运行时（.NET Framework 4.6.2+、.NET Core 2.0+、.NET 5+）。