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

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

1. 什么是API攔截？

2. 一個方法被很多地方調(diào)用，怎么在不修改這個方法源碼情況下，記錄這個方法調(diào)用的前后時間？

3. 同2，不修改源碼的情況下，怎么對方法的參數(shù)進行校正（篡改）？

4. 同3，不修改源碼的情況下，怎么對方法的返回值進行偽造？
   ...

1. 前言

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

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

有幾個選項可供您使用：

1. 通過反編譯或下載源代碼（如果首先可用）獲取源代碼。這通常很冒險，因為它經(jīng)常伴隨著復雜的構(gòu)建過程，許多依賴項，現(xiàn)在你負責維護庫的整個分支，即使你只想做一個很小的改變。

2. 使用?ILDasm?反編譯應用，直接修補?IL?代碼，然后使用?ILAs?將其組裝回來。在許多方面，這更好，因為您可以創(chuàng)建一個戰(zhàn)略性的手術(shù)切口，而不是全面的“從頭開始”的方法。缺點是您必須完全在IL中實現(xiàn)您的方法，這是一個不平凡的冒險。

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

現(xiàn)在讓我們看一下另一種解決方法-內(nèi)存修補。這與游戲作弊引擎幾十年來使用的技術(shù)相同，這些引擎附加到正在運行的進程，查找內(nèi)存位置并改變其行為。聽起來很復雜？ 實際上，在 .NET 中做到這一點比聽起來容易得多。我們將使用一個名為Harmony的庫，該庫在NuGet上可通過“Lib.Harmony”包獲得。這是一個用于?.NET?的內(nèi)存修補引擎，主要針對使用 Unity 構(gòu)建的游戲，當然不止Unity。

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

2. 攔截(Hook)自己的庫

2.1. 準備工作

1. 創(chuàng)建一個控制臺程序?HelloHook，添加類?Student：

namespace HelloHook;public class Student{public string GetDetails(string name){return $"大家好，我是Dotnet9網(wǎng)站站長：{name}";}}

Student類中定義了一個GetDetails方法，返回格式化的個人介紹信息，這個方法后面攔截試驗使用。

1. Program.cs中添加Student調(diào)用：

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

運行程序輸出如下：

大家好，我是Dotnet9網(wǎng)站站長：沙漠盡頭的狼

基本工作準備完成，這就是一個簡單的控制臺程序，后文的內(nèi)容就根據(jù)這兩個工程展開細說。

2.2. 攔截GetDetails方法

1. 引入攔截包-Lib.Harmony

我們使用Lib.Harmony包，API的攔截就靠它了，在HelloHook工程中添加如下Nuget包：

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

1. 攔截處理

添加攔截類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特性：

• 第一個是關(guān)聯(lián)被攔截的類Student類型；

• 第二個是關(guān)聯(lián)被攔截的類方法GetDetails；

即當程序中調(diào)用Student類的GetDetails方法時，HookStudent內(nèi)定義的方法就會分別執(zhí)行，三個方法執(zhí)行順序是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();

運行程序輸出如下：

大家好，我是Dotnet9網(wǎng)站站長：沙漠盡頭的狼PrefixPostfixFinalizer大家好，我是Dotnet9網(wǎng)站站長：沙漠盡頭的狼

上面代碼就完成了一個自定義類的攔截處理，使用PatchAll能自動發(fā)現(xiàn)補丁類HookStudent，從而自動攔截Student類的GetDetails方法調(diào)用，發(fā)現(xiàn)第二次調(diào)用student.GetDetails("沙漠盡頭的狼")時，Harmony的三個生命周期方法都被調(diào)用了。

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

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

2.4. 說好的參數(shù)篡改呢？還有API結(jié)果偽造呢？

修改Program.cs，多打印幾行數(shù)據(jù)方便區(qū)分：

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之前，打印一次，注冊后打印兩次，注意看參數(shù)的不同。

修改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 = $"這是我的曾用網(wǎng)名";return false;}if (!"沙漠盡頭的狼".Equals(name)){name = "非站長名";}return true;}}

先運行看輸出：

大家好，我是Dotnet9網(wǎng)站站長：沙漠盡頭的狼這是我的曾用網(wǎng)名大家好，我是Dotnet9網(wǎng)站站長：非站長名

• 第1行“大家好，我是Dotnet9網(wǎng)站站長：沙漠盡頭的狼”，這是沒有注冊攔截之前的正常格式化輸出；

• 第2行“這是我的曾用網(wǎng)名”，這里實現(xiàn)的是結(jié)果的偽造；

• 第3行“大家好，我是Dotnet9網(wǎng)站站長：非站長名”，這里實現(xiàn)的是參數(shù)的篡改。

結(jié)果偽造

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

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

注意返回值是false，表示不調(diào)用原生方法，這里就將被攔截的方法返回值偽造成功了。

參數(shù)篡改

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

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

Prefix方法默認返回的true，表示需要調(diào)用原生方法，這里會將篡改的參數(shù)傳入原生方法，原生方法執(zhí)行結(jié)果會將篡改的參數(shù)組合返回為“大家好，我是Dotnet9網(wǎng)站站長：非站長名”。

注意：

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

上面的示例源碼點這。

3. 攔截(Hook)WPF的API

我們創(chuàng)建一個簡單的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 = "這是一個不錯的網(wǎng)站喲";}return true;}}

類HookMessageBox上關(guān)聯(lián)攔截的MessageBox.Show重載方法，在Prefix里對提示框內(nèi)容進行合法性驗證，不合法進行修正。

最后就是在窗體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="這是一個垃圾網(wǎng)站" 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 是一個熱衷于技術(shù)分享的程序員網(wǎng)站", "Dotnet9");}private void ShowBadMessageDialog_OnClick(object sender, RoutedEventArgs e){MessageBox.Show("這是一個垃圾網(wǎng)站", "https://dotnet9.com");}}

運行結(jié)果如下：

上面效果即完成了提示框內(nèi)容的驗證，如果內(nèi)容含有“垃圾”關(guān)鍵字，就換成好聽的話（這是一個不錯的網(wǎng)站喲）。

本示例源碼在這。

4. 攔截(Hook).NET默認的API

創(chuàng)建控制臺程序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，不論查找的字符位置在哪，當然這個測試代碼沒有任何意義，這里只是演示而已，運行結(jié)果如下：

9的位置：149的位置：100

5. 總結(jié)及分享

5.1. 總結(jié)

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

Harmony用于在運行時修補替換和裝飾 .NET/.NET Core 方法的庫。 但是該技術(shù)可以與任何.NET版本一起使用。它對同一方法的多次更改是累積而不是覆蓋。

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

1. .NET的一些方法，我們直接在代碼層面可能無法直接修改；

2. 第三庫未提供源碼，但我們想改它的部分方法；

3. 第三庫提供了源碼，雖然可以修改它的源碼，但萬一第三庫后面迭代升級，我們又不得不更新時，那自己做的修改跟著升級可能麻煩了；

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

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

1. 最新2.0版支持 .NET Core ；

2. Harmony支持手動（Patch，參考Harmony wiki上的使用）和自動（PatchAll，本文演示使用的這種方式，Lib.Harmony使用的是C#的特性機制）；

3. 它為每個原始方法創(chuàng)建DynamicMethod方法，并向其織入代碼，該代碼在開始（Prefix）和結(jié)束時（Postfix）調(diào)用自定義方法。它還允許您編寫過濾器（Transpiler）來處理原始的IL代碼，從而可以對原始方法進行更詳細的操作;

4. Getter/Setter、虛/ 非虛 方法、 靜態(tài) 方法；

5. 補丁方法必須是靜態(tài)方法；

6. Prefix需要返回void或者bool類型(void即不攔截)；

7. Postfix需要返回void類型，或者返回的類型要與第一個參數(shù)一致(直通模式)；

8. 如果原方法不是靜態(tài)方法，則可以使用名為__instance(兩個下劃線)的參數(shù)來訪問對象實例；

9. 可以使用名為__result(兩個下劃線)的參數(shù)來訪問方法的返回值，如果是Prefix，則得到返回值的默認值；

10. 可以使用名為__state(兩個下劃線)的參數(shù)在Prefix補丁中存儲任意類型的值，然后在Postfix中使用它，你有責任在Prefix中初始化它的值；

11. 可以使用與原方法中同名的參數(shù)來訪問對應的參數(shù)，如果你要寫入非引用類型，記得使用ref關(guān)鍵字；

12. 補丁使用的參數(shù)必須嚴格對應類型(或者使用object類型)和名字；

13. 我們的補丁只需要定義我們需要用到的參數(shù)，不用把所有參數(shù)都寫上；

14. 要允許補丁重用，可以使用名為__originalMethod(兩個下劃線)的參數(shù)注入原始方法。

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

5.2 分享

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

1. 我使用過這個庫進行API的Hook，它是XXX；

2. 我自己實現(xiàn)過類似功能，分享文章鏈接是XXX；

3. 想問，我能攔截這個API嗎？場景是XXXX

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

6. 參考

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

• Harmony

• Harmony wiki

• Harmony API文檔

• Hacking .NET – rewriting code you don’t control

• Rimworld Mod制作教程6 使用Harmony對C#代碼Patch

• 動態(tài)IL織入框架Harmony簡單入手

• 一個開放源代碼，實現(xiàn)動態(tài)IL注入(Hook或補丁工具)框架:Lib.Harmony

• .NET 7 Runtime Skipping Patches #504

時間如流水，只能流去不流回。