当前位置：首页 > article >正文

.NET外挂系列：1. harmony 基本原理和骨架分析

article 2025/9/15 21:29:51

一：背景

1. 讲故事

为什么要开这么一个系列，是因为他可以对 .NET SDK 中的方法进行外挂，这种技术对解决程序的一些疑难杂症特别有用，在.NET高级调试 领域下大显神威，在我的训练营里也是花了一些篇幅来说这个，今天我准备用10篇左右来详细聊一聊，供学员和同行们欣赏，详细的文档参考：https://harmony.pardeike.net/articles/intro.html

二：harmony 解读

1. 概念

Harmony 是一个用于在运行时修补、替换和装饰 .NET 方法的库，兼容主流平台，比如 PC、Mac、Linux的32位和64位系统。它的注入模型图如下：

这张图很好理解，就是对你想要 hook 的方法，harmony 会对应生成一个动态方法，然后将需要hook的原方法的il代码全部copy走，同时根据你的配置情况，在il代码之前和il代码之后 配置一个 AOP 逻辑，当然有需要的话，还可以对原方法的 il 代码借助 Transpilers 组件进行修改，总之非常强大。

2. harmony 有哪些注入点

用 harmony 做外挂，肯定要知道注入的一些点位，常见的有：

前缀补丁（Prefix）和后缀补丁（Postfix）

前缀补丁和后缀补丁非常好理解，就是我们理解的 AOP 功能，前者在原始方法执行前执行，后者是在原始方法执行后执行。

转译器补丁（Transpiler）

如果基本的 AOP 功能不能满足，这时候就必须更精细化的控制，对，就是直接修改 copy 之后的 il 代码，这个就比较🐂👃了，

终结器补丁（Finalizer）

如果构建出来的AOP补丁逻辑会抛异常的话，你又不想让这些异常污染正常的业务代码逻辑，这时候就可以用 终结器补丁 了，相当于对外屏蔽了人家不关心的东西，哈哈，否则容易造成恐慌。

反向补丁（Reverse Patch）

如果说 AOP 是纵向扩展，那反向补丁就是横向扩展，它的原理就是在 DynamicMethod 方法之前生成一个动态代码(Proxy)，后续再跟大家详细聊。

三：案例场景介绍

1. 案例背景

说了这么说，还是说一些比较实际的案例可能大家更感兴趣，我的一个 .NET 程序平时都是好好的，不知道为啥线程突然就暴涨到了1000+，现在很惶恐，不知道是什么逻辑导致的，我用 windbg 观察后发现是都是普通的 Thread 类，输出如下：


0:013> !t
ThreadCount:      1004
UnstartedThread:  0
BackgroundThread: 2
PendingThread:    0
DeadThread:       1
Hosted Runtime:   noLock  DBG   ID     OSID ThreadOBJ           State GC Mode     GC Alloc Context                  Domain           Count Apt Exception0    1     5358 0000024A2661D790    2a020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 11    2      66c 0000024A26687150    2b220 Preemptive  0000024A2AC04F88:0000024A2AC062B8 0000024a26613dc0 -00001 MTA (Finalizer) 
XXXX    4        0 0000028ABF061250  1039820 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 Ukn (Threadpool Worker) 14    5     4f2c 0000028ABF0656C0  302b220 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA (Threadpool Worker) 16    7     4ed8 0000028ABF069F40  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 17    8     44d8 0000028ABF08B110  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 18    9     4738 0000028ABD4BC640  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 19   10     201c 0000028ABD4BEAC0  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 20   11     49b0 0000028ABD4C0F80  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 21   12     43c8 0000028ABF08E1F0  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 22   13     5020 0000028ABF077170  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 23   14     3c48 0000028ABF07C820  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 24   15     4384 0000028ABF060BB0  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA ...1016 1003     5db4 0000028ABF7F9CD0  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA 1017 1004     5db8 0000028ABF7FC190  202b020 Preemptive  0000000000000000:0000000000000000 0000024a26613dc0 -00001 MTA

人对一些未知的东西一般都很焦虑惶恐，那怎么反向找到是什么代码导致的呢？大家可以仔细想一想，既然有人开了 Thread, 那必然要调用相应的 Start 方法，所以思路就很简单了，外挂 Thread.Start 方法就好，先用 ilspy 观察源码。

从图中看当前的 Start 有四个重载，那到底注入哪一个呢？可以全tm注入了，但由于是第一篇就不要搞的那么复杂，挑一个 无参构造函数，参考代码如下：


namespace Example_19_6
{internal class Program{static void Main(string[] args){// 创建 Harmony 实例var harmony = new Harmony("com.example.threadhook");// 应用补丁harmony.PatchAll();Task.Factory.StartNew(() => { Test(); });Console.ReadLine();}static void Test(){// 测试线程var thread = new Thread(() => Console.WriteLine("线程正在运行"));thread.Start();}}[HarmonyPatch(typeof(Thread), "Start", new Type[] { })]public class ThreadStartHook{// 前缀补丁 - 在原始方法执行前运行public static void Prefix(Thread __instance){Console.WriteLine("----------------------------");Console.WriteLine($"即将启动线程: {__instance.ManagedThreadId}");Console.WriteLine(Environment.StackTrace);Console.WriteLine("----------------------------");}}
}

卦中的代码稍微解释一下：

ThreadStartHook
这个是注入的主体类，[HarmonyPatch(typeof(Thread), "Start", new Type[] { })] 表示对无参的 Thread.Start 进行外挂。
Prefix
这个是本次问题的核心代码，它在 Thread.Start 函数调用之前执行，其中 __instance 是当前 Thread 的 this 指针，为了能够捕获是谁调用的，我们用 Environment.StackTrace 显示当前的调用栈即可，如果输出了那就真相大白，这里我是输出到控制台，大家可以输出到文件。
PatchAll
有了 patch(ThreadStartHook) 类之后，当调用 harmony.PatchAll() 时，harmony就会在当前程序集中搜索所有的标记为 HarmonyPatch 特性的类，然后构建相应的容纳万物的 DynamicMethod。

代码逻辑相信大概都清楚了，接下来将程序跑起来，观察 Console 输出。

从卦中看，尼玛，原来是代码 Example_19_6.Program.Test() 导致的，这时候就可以根据这个方法在源码中观察一下，为什么会这样？

2. 底层原理浅析

到这里我相信有很多人都有一个疑惑，对 thread.Start(); 方法的注入点在哪里？要想找到这个答案，可以简单粗暴看汇编即可。


0:013> !name2ee System_Private_CoreLib!System.Threading.Thread.Start 
Module:      00007ff7fe8c4000
Assembly:    System.Private.CoreLib.dll
Token:       0000000006003691
MethodDesc:  00007ff7feaa1458
Name:        System.Threading.Thread.Start(System.Object)
Not JITTED yet. Use !bpmd -md 00007FF7FEAA1458 to break on run.
-----------------------
Token:       0000000006003693
MethodDesc:  00007ff7feaa1488
Name:        System.Threading.Thread.Start(System.Object, Boolean, Boolean)
Not JITTED yet. Use !bpmd -md 00007FF7FEAA1488 to break on run.
-----------------------
Token:       0000000006003694
MethodDesc:  00007ff7feaa14a0
Name:        System.Threading.Thread.Start()
JITTED Code Address: 00007ff85bd0e440
-----------------------
Token:       0000000006003697
MethodDesc:  00007ff7feaa14e8
Name:        System.Threading.Thread.Start(Boolean, Boolean)
JITTED Code Address: 00007ff85bd0e4700:013> !U 00007ff85bd0e440
preJIT generated code
System.Threading.Thread.Start()
ilAddr is 00007FF85C11E870 pImport is 000001BAD0805BF0
Begin 00007FF85BD0E440, size 12/_/src/libraries/System.Private.CoreLib/src/System/Threading/Thread.cs @ 226:
>>> 00007ff8`5bd0e440 e9cb22fba2      jmp     00007ff7`fecc0710
00007ff8`5bd0e445 8f00            pop     qword ptr [rax]
00007ff8`5bd0e447 ba01000000      mov     edx,1
00007ff8`5bd0e44c 4533c0          xor     r8d,r8d
00007ff8`5bd0e44f 48ff20          jmp     qword ptr [rax]0:013> !U 00007ff7`fecc0710
Normal JIT generated code
DynamicClass.System.Threading.Thread.Start_Patch1(System.Threading.Thread)
Can only work with dynamic not implemented

当你看到卦中的 jmp 00007ff7fecc0710 代码之后，我相信你一切都明白了，这是典型的钩子代码，这要是被杀毒软件知道了，绝对是定斩不赦！画个简图如下：

四：总结

作为一个.NET高级调试师，灵活运用.NET外挂是一个基本功，有了它我就可以轻松的给 .NET SDK 加上日志，从此以后像鹰眼一样，洞察苍穹。