Harmony项目中的反向补丁技术详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00003/article/details/148490678

Harmony项目中的反向补丁技术详解

Harmony A library for patching, replacing and decorating .NET and Mono methods during runtime 项目地址: https://gitcode.com/gh_mirrors/ha/Harmony

什么是反向补丁

在Harmony项目中，反向补丁(Reverse Patch)是一项强大的功能，它允许开发者创建一个"存根方法"，这个方法可以"变成"原始方法或其部分实现。这种技术为开发者提供了直接调用原始方法的能力，而无需使用反射或其他间接调用方式。

反向补丁的核心优势

直接调用私有方法：无需通过反射机制，可以直接访问和调用目标类的私有成员
原生性能：避免了反射或委托带来的性能开销
选择性提取：可以通过IL转换器(transpiler)只提取原始方法中的特定部分
获取原始实现：可以获取未被修改的原始方法实现
实现冻结：反向补丁会冻结方法实现，不受后续补丁影响

反向补丁的基本用法

要创建一个反向补丁，需要使用[HarmonyReversePatch]特性标记一个补丁方法。这个方法需要与原始方法具有相同的签名(包括静态/非静态修饰符)。

private class OriginalClass
{
    private void SecretMethod(int value, string name)
    {
        // 原始实现
    }
}

[HarmonyPatch]
public class PatchClass
{
    [HarmonyReversePatch]
    [HarmonyPatch(typeof(OriginalClass), "SecretMethod")]
    public static void MyWrapper(object instance, int value, string name) =>
        throw new NotImplementedException("这是一个存根方法");
}

使用时需要注意：当使用实例方法作为存根时，IL代码会期望this指向原始类类型，如果存根方法所在的类不是原始类，会导致问题。

反向补丁的两种类型

Harmony提供了两种反向补丁类型：

Original类型：获取DLL中定义的原始未修改方法，不受任何补丁或转换器影响
```
[HarmonyReversePatch(HarmonyReversePatchType.Original)]
```
Snapshot类型：获取应用了所有现有转换器后的方法版本(前缀、后缀和终结器补丁不会被应用)
```
[HarmonyReversePatch(HarmonyReversePatchType.Snapshot)]
```

如果不指定类型，默认使用Original类型。

高级应用：修改原始方法内容

反向补丁的真正强大之处在于可以结合转换器(transpiler)来修改原始IL代码，从而提取或修改原始方法的部分功能。

实际案例解析

假设原始类中有一个复杂方法，其中包含一段计算校验和的代码。我们可以使用反向补丁技术只提取这部分功能：

private class OriginalClass
{
    private string ComplexMethod(string input, int factor)
    {
        var parts = input.Split('-').Reverse().ToArray();
        var checksum = CalculateChecksum(parts); // 我们想提取这部分
        return checksum + "Result";
    }
    
    private int CalculateChecksum(string[] parts) { ... }
}

[HarmonyPatch]
public class PatchClass
{
    [HarmonyReversePatch]
    [HarmonyPatch(typeof(OriginalClass), "ComplexMethod")]
    public static int ExtractChecksum(string input)
    {
        // 这个转换器将修改原始IL，只保留校验和计算部分
        IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions)
        {
            // 这里进行IL代码操作，提取需要的部分
            // 具体实现需要了解IL和堆栈操作
            // ...
        }

        _ = Transpiler(null); // 使编译器满意
        return 0;
    }
}