Hyz.Trace.Weaving.Fody 1.4.1

Hyz.Trace.Weaving.Fody

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

特性优先级：类级 [Trace] 编织类内所有方法（含 public/protected/internal/private/static）；方法级 [Trace] 仅编织打标的单个方法。两者可混用，方法级标注总是生效。

安装

dotnet add package Hyz.Trace.Weaving.Fody

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

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

安装后确保项目存在 FodyWeavers.xml（通常由 NuGet 包自动引入），其中启用本编织器：

<Weavers>
  <Hyz.Trace.Weaving.Fody />
</Weavers>

[Trace] 特性详解

[Trace] 特性定义于 Hyz.Trace 命名空间，可标注于 类、方法、属性（AttributeTargets.Method | Class | Property，Inherited = true）。

特性属性

标注位置与行为

混用规则：类级 [Trace] + 方法级 [Trace] 可共存。方法级标注的方法一定会被编织（即使类未标注）；类级标注会编织类内所有方法，方法级标注的方法同样会被编织，不会重复。

工作原理

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

1. 编译时 Fody 加载本 weaver DLL
2. 扫描程序集中所有标注 [Trace] 特性的方法或类
3. 重命名原方法：将原方法重命名为 <MethodName>__TraceOriginal，改为 private，原方法体 IL 保持 100% 不变
4. 生成包装方法：创建一个与原方法签名完全一致的新方法（保留原访问级别与 static / virtual / override 修饰；显式接口 Overrides 迁到包装方法，原方法改为 private non-virtual）
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;

public class UserService
{
    // 自动生成 Span，名称为 "UserService.GetUser"
    [Trace]
    public User? GetUser(int id)
    {
        return userRepository.Find(id);
    }
}

类级追踪（覆盖所有方法）

using Hyz.Trace;

[Trace]
public class OrderService
{
    public Order CreateOrder(CreateOrderRequest request) { /* 会被编织 */ }
    public void CancelOrder(int orderId) { /* 会被编织 */ }

    // 类级 [Trace] 同样编织 private / protected / static 方法
    private void InternalHelper() { /* 会被编织 */ }
    protected virtual void Validate(Order order) { /* 会被编织 */ }
    public static Order? FindById(int id) { /* 会被编织 */ }

    // 构造函数不会被编织（不支持）
    public OrderService() { }
}

自定义 Span 名称与参数控制

public class PaymentService
{
    [Trace(Name = "process-payment")]
    public PaymentResult Process(PaymentRequest request) { /* ... */ }

    // 关闭入参/返回值记录（避免敏感数据或大对象进入 Span）
    [Trace(IncludeParameters = false, IncludeReturnValue = false)]
    public string GetToken() { /* ... */ }
}

属性级追踪

public class ConfigProvider
{
    // Span 名为 "ConfigProvider.Cache.get" / ".set"
    [Trace]
    public string? Cache { get; set; }
}

复杂方法也能正常编织

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

编译日志

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

• Normal 详细级别：

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

• 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 栈深度正确性

与 SourceGenerator 对比

选型建议：优先使用 Fody（功能完整、零侵入、全平台）。SourceGenerator 作为补充，仅用于无法安装 Fody 或必须使用源生成器的场景。

与元包的关系

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+）。