快學會這個技能-.NET API攔截技法

大家好，我是沙漠盡頭的狼。

本文先拋出以下問題，請在文中尋找答案，可在評論區回答：

什麼是API攔截？
一個方法被很多地方呼叫，怎麼在不修改這個方法原始碼情況下，記錄這個方法呼叫的前後時間？
同2，不修改原始碼的情況下，怎麼對方法的參數進行校正（篡改）？
同3，不修改原始碼的情況下，怎麼對方法的回傳值進行偽造？ ...

1. 前言

前言翻譯自一個國外的文章，他寫的更容易讓人理解 - Hacking .NET – rewriting code you don’t control：

您是否曾經遇到過不屬於您但想要更改其行為的類別庫方法？通常，該方法是非公開的，並且沒有很好的方法來覆蓋其行為。你可以看到它是如何工作的（因為你很棒，並且使用像Resharper、dnSpy之類反編譯工具，對吧？），你只是無法改變它。你真的需要改變它，因為XXX原因。

有幾個選項可供您使用：

透過反編譯或下載原始碼（如果首先可用）取得原始碼。這通常很冒險，因為它經常伴隨著複雜的建置過程，許多依賴項，現在你負責維護庫的整個分支，即使你只想做一個很小的改變。
使用 ILDasm 反編譯應用，直接修補 IL 程式碼，然後使用 ILAs 將其組裝回來。在許多方面，這更好，因為您可以建立一個戰略性的手術切口，而不是全面的「從頭開始」的方法。缺點是您必須完全在IL中實現您的方法，這是一個不平凡的冒險。

如果您正在處理已簽章的庫，上述兩種方法也不起作用。

現在讓我們看一下另一種解決方法-記憶體修補。這與遊戲作弊引擎幾十年來使用的技術相同，這些引擎附加到正在執行的處理序，查詢記憶體位置並改變其行為。聽起來很複雜？實際上，在 .NET 中做到這一點比聽起來容易得多。我們將使用一個名為Harmony的庫，該庫在NuGet上可透過「Lib.Harmony」套件獲得。這是一個用於 .NET 的記憶體修補引擎，主要針對使用 Unity 建置的遊戲，當然不止Unity。

站長將在本文向您展示如何更改您認為不可能的事情 - 從攔截(Hook)自己的庫開始，到攔截(Hook) WPF庫和.NET基礎庫結束。

2. 攔截(Hook)自己的庫

2.1. 準備工作

建立一個主控台程式 HelloHook，新增類別 Student：

namespace HelloHook;

public class Student
{
    public string GetDetails(string name)
    {
        return $"大家好，我是沙漠盡頭的狼網站站長：{name}";
    }
}

Student類別中定義了一個GetDetails方法，返回格式化的自我介紹資訊，這個方法後面攔截試驗使用。

Program.cs中加入Student呼叫：

using HelloHook;

var student = new Student();
Console.WriteLine(student.GetDetails("沙漠盡頭的狼"));

執行程式輸出如下：

大家好，我是沙漠盡頭的狼網站站長：沙漠盡頭的狼

基本工作準備完成，這就是一個簡單的主控台程式，後文的內容就根據這兩個專案展開細說。

2.2. 攔截`GetDetails`方法

引入攔截套件-Lib.Harmony

我們使用Lib.Harmony套件，API的攔截就靠它了，在HelloHook專案中加入如下NuGet套件：

<PackageReference Include="Lib.Harmony" Version="2.2.2" />

攔截處理

新增攔截類別HookStudent：

using HarmonyLib;

namespace HelloHook;

[HarmonyPatch(typeof(Student))]
[HarmonyPatch(nameof(Student.GetDetails))]
public class HookStudent
{
    public static bool Prefix()
    {
        Console.WriteLine($"Prefix");
        return true;
    }

    public static void Postfix()
    {
        Console.WriteLine($"Postfix");
    }

    public static void Finalizer()
    {
        Console.WriteLine($"Finalizer");
    }
}

看程式碼中的註解，HookStudent類別上新增了兩個HarmonyPatch特性：

第一個是關聯被攔截的類別Student類型；
第二個是關聯被攔截的類別方法GetDetails；

即當程式中呼叫Student類別的GetDetails方法時，HookStudent內定義的方法就會分別執行，三個方法執行順序是Prefix->Postfix->Finalizer，當然約定的方法不止這三個，其實我們常用的應該是Prefix和Postfix，約定方法的意義見後方說明，沒說就看Harmony wiki...

2.3. 註冊攔截

對Program.cs進行修改，新增Harmony對整個組件集的攔截：

using HarmonyLib;
using HelloHook;
using System.Reflection;

var student = new Student();
Console.WriteLine(student.GetDetails("沙漠盡頭的狼"));  

var harmony = new Harmony("https://dotnet9.com");
harmony.PatchAll(Assembly.GetExecutingAssembly());

Console.WriteLine(student.GetDetails("沙漠盡頭的狼"));

Console.ReadLine();

執行程式輸出如下：

大家好，我是沙漠盡頭的狼網站站長：沙漠盡頭的狼
Prefix
Postfix
Finalizer
大家好，我是沙漠盡頭的狼網站站長：沙漠盡頭的狼

上面程式碼就完成了一個自訂類別的攔截處理，使用PatchAll能自動發現補丁類別HookStudent，從而自動攔截Student類別的GetDetails方法呼叫，發現第二次呼叫student.GetDetails("沙漠盡頭的狼")時，Harmony的三個生命週期方法都被呼叫了。

我們可以在攔截類別的約定方法（Prefix和Postfix等）裡做一些日誌記錄(Console.WriteLine\ILogger.LogInfo等)，類似於B/S中的AOP攔截，操作日誌在這裡記錄正合適。

這就完了？說啥呢，這才開始。

2.4. 說好的參數篡改呢？還有API結果偽造呢？

修改Program.cs，多印幾行資料方便區分：

using HarmonyLib;
using HelloHook;
using System.Reflection;

var student = new Student();
Console.WriteLine(student.GetDetails("沙漠盡頭的狼"));

var harmony = new Harmony("https://dotnet9.com");
harmony.PatchAll(Assembly.GetExecutingAssembly());

Console.WriteLine(student.GetDetails("沙漠之狐"));
Console.WriteLine(student.GetDetails("Dotnet"));

Console.ReadLine();

在註冊Harmony之前，列印一次，註冊後列印兩次，注意看參數的不同。

修改HookStudent，我們只使用Prefix方法，其他Postfix等方法類似，可看Harmony wiki瞭解更多的使用方法，修改如下：

using HarmonyLib;

namespace HelloHook;

[HarmonyPatch(typeof(Student))]
[HarmonyPatch(nameof(Student.GetDetails))]
public class HookStudent
{
    public static bool Prefix(ref string name, ref string __result)
    {
        if ("沙漠之狐".Equals(name))
        {
            __result = $"這是我的曾用網名";
            return false;
        }

        if (!"沙漠盡頭的狼".Equals(name))
        {
            name = "非站長名";
        }

        return true;
    }
}

先執行看輸出：

大家好，我是沙漠盡頭的狼網站站長：沙漠盡頭的狼
這是我的曾用網名
大家好，我是沙漠盡頭的狼網站站長：非站長名

第1行「大家好，我是沙漠盡頭的狼網站站長：沙漠盡頭的狼」，這是沒有註冊攔截之前的正常格式化輸出；
第2行「這是我的曾用網名」，這裡實現的是結果的偽造；
第3行「大家好，我是沙漠盡頭的狼網站站長：非站長名」，這裡實現的是參數的篡改。

結果偽造

注意看Prefix方法傳入的參數ref string __result：其中ref表示引用傳遞，允許對結果進行修改；string與原方法的回傳值類型必須一致；__result為回傳值的約定命名，前面是兩個"_"，即命名必須為__result。

if ("沙漠之狐".Equals(name))
{
    __result = $"這是我的曾用網名";
    return false;
}

注意回傳值是false，表示不呼叫原生方法，這裡就將被攔截的方法回傳值偽造成功了。

參數篡改

看傳入的參數ref string name：ref表示參數是引用傳遞，允許對參數進行修改；string name必須與原方法參數定義一樣。

if (!"沙漠盡頭的狼".Equals(name))
{
    name = "非站長名";
}

Prefix方法預設返回的true，表示需要呼叫原生方法，這裡會將篡改的參數傳入原生方法，原生方法執行結果會將篡改的參數組合返回為「大家好，我是沙漠盡頭的狼網站站長：非站長名」。

注意：

原生參數name和回傳值__result是可選的，如果不進行篡改，去掉ref也是可以的。

上面的範例原始碼點這。

3. 攔截(Hook)WPF的API

我們建立一個簡單的WPF程式HookWpf，攔截MessageBox.Show方法：

public static MessageBoxResult Show(string messageBoxText, string caption)

首先在App中使用自動攔截註冊：

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {

        base.OnStartup(e);

        var harmony = new Harmony("https://dotnet9.com");
        harmony.PatchAll(Assembly.GetExecutingAssembly());
    }
}

定義攔截類別HookMessageBox：

using HarmonyLib;
using System.Windows;

namespace HookWpf;

[HarmonyPatch(typeof(MessageBox))]
[HarmonyPatch(nameof(MessageBox.Show))]
[HarmonyPatch(new [] { typeof(string), typeof(string) })]
public class HookMessageBox
{
    public static bool Prefix(ref string messageBoxText, string caption)
    {
        if (messageBoxText.Contains("垃圾"))
        {
            messageBoxText = "這是一個不錯的網站喲";
        }

        return true;
    }
}

類別HookMessageBox上關聯攔截的MessageBox.Show多載方法，在Prefix裡對提示框內容進行合法性驗證，不合法進行修正。

最後就是在表單MainWindow.xaml裡新增兩個彈出提示框的按鈕：

<Window x:Class="HookWpf.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <StackPanel>
        <Button Content="彈出預設提示框" Width="120" Height="30" Click="ShowDialog_OnClick"></Button>
        <Button Content="這是一個垃圾網站" Width="120" Height="30" Click="ShowBadMessageDialog_OnClick"></Button>
    </StackPanel>
</Window>

後台處理按鈕點擊事件，彈出提示框：

using System.Windows;

namespace HookWpf;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }

    private void ShowDialog_OnClick(object sender, RoutedEventArgs e)
    {
        MessageBox.Show("https://dotnet9.com 是一個熱衷於技術分享的程式設計師網站", "Dotnet9");
    }

    private void ShowBadMessageDialog_OnClick(object sender, RoutedEventArgs e)
    {
        MessageBox.Show("這是一個垃圾網站", "https://dotnet9.com");
    }
}

執行結果如下：

上面效果即完成了提示框內容的驗證，如果內容含有「垃圾」關鍵字，就換成好聽的話（這是一個不錯的網站喲）。

本範例原始碼在這。

4. 攔截(Hook).NET預設的API

建立主控台程式HookDotnetAPI，引入Lib.Harmonynuget套件，Program.cs修改如下：

using HarmonyLib;

var dotnet9Domain = "https://dotnet9.com";
Console.WriteLine($"9的位置：{dotnet9Domain.IndexOf('9',0)}");

var harmony = new Harmony("com.dotnet9");
harmony.PatchAll();

Console.WriteLine($"9的位置：{dotnet9Domain.IndexOf('9', 0)}");

[HarmonyPatch(typeof(String))]
[HarmonyPatch(nameof(string.IndexOf))]
[HarmonyPatch(new Type[] { typeof(char), typeof(int) })]
public static class HookClass
{
    public static bool Prefix(ref int __result)
    {
        __result = 100;
        return false;
    }
}

使用方法和前面類似，string.IndexOf方法被攔截後，總是返回100，不論查詢的字元位置在哪，當然這個測試程式碼沒有任何意義，這裡只是示範而已，執行結果如下：

9的位置：14
9的位置：100

5. 總結及分享

5.1. 總結

Harmony的原理是利用反射取得對應類別中的方法，然後加上特性標籤進行邏輯控制，達到不破壞原有程式碼進行更新的效果。

Harmony用於在執行階段修補取代和裝飾 .NET/.NET Core 方法的庫。但是該技術可以與任何.NET版本一起使用。它對同一方法的多個變更是累積而不是覆蓋。

再次分析可能產生的場景需要攔截，加深您對本文的記憶：

.NET的一些方法，我們直接在程式碼層面可能無法直接修改；
第三庫未提供原始碼，但我們想改它的部分方法；
第三庫提供了原始碼，雖然可以修改它的原始碼，但萬一第三庫後面疊代升級，我們又不得不更新時，那自己做的修改跟著升級可能麻煩了；

攔截注意：如您所見，這提供了大量新的可能性。請記住，權力越大，責任越大。由於您以原始開發人員不打算的方式覆蓋行為，因此無法保證您的補丁程式碼在他們發布新版本的程式碼時會起作用。即上面第3點，不排除第三庫升級API結構也變了，我們也要跟著修改攔截邏輯哦

從《Harmony wiki patching》中翻譯出以下使用注意事項：

最新2.0版支援 .NET Core ；
Harmony支援手動（Patch，參考Harmony wiki上的使用）和自動（PatchAll，本文示範使用的這種方式，Lib.Harmony使用的是C#的特性機制）；
它為每個原始方法建立DynamicMethod方法，並向其織入程式碼，該程式碼在開始（Prefix）和結束時（Postfix）呼叫自訂方法。它也允許您編寫篩選器（Transpiler）來處理原始的IL程式碼，從而可以對原始方法進行更詳細的操作;
Getter/Setter、虛/ 非虛方法、靜態方法；
補丁方法必須是靜態方法；
Prefix需要傳回void或者bool型別(void即不攔截)；
Postfix需要傳回void型別，或者傳回的型別要與第一個參數一致(直通模式)；
如果原方法不是靜態方法，則可以使用名為__instance(兩個底線)的參數來存取物件實例；
可以使用名為__result(兩個底線)的參數來存取方法的回傳值，如果是Prefix，則得到回傳值的預設值；
可以使用名為__state(兩個底線)的參數在Prefix補丁中儲存任意型別的值，然後在Postfix中使用它，你有責任在Prefix中初始化它的值；
可以使用與原方法中同名的參數來存取對應的參數，如果你要寫入非參考型別，記得使用ref關鍵字；
補丁使用的參數必須嚴格對應型別(或者使用object型別)和名字；
我們的補丁只需要定義我們需要用到的參數，不用把所有參數都寫上；
要允許補丁重用，可以使用名為__originalMethod(兩個底線)的參數注入原始方法。

最後忘了補一條，.NET 7中使用Harmony還有點點問題，站長在測試WPF API和.NET基礎庫攔截Demo時一直不生效，折騰了2、3個晚上，以為是自己的使用問題，最後看到Harmony issue .NET 7 Runtime Skipping Patches #504，將程式降級為.NET 6即可。

5.2 分享

讀者朋友們，相信不少人使用過Harmony或者其他的 .NET Hook庫，可在評論中留言分享，可提出自己的疑問，或自己的使用心得：

我使用過這個庫進行API的Hook，它是XXX；
我自己實現過類似功能，分享文章連結是XXX；
想問，我能攔截這個API嗎？場景是XXXX

[我的分享] + [你的分享] ∈ [.NET圈子的一份小力量]

6. 參考

寫作本文時以下文章都做了參考，建議大家都看看，特別是 Harmony wiki中寫了Harmony的詳細使用方法：

7. 補充

2023年9月23號手動註冊攔截

非public類別及方法如何攔截攔截|篡改|偽造.NET類別庫中不限於public的類別和方法