このスキルを習得する-. NET APIインターセプトテクニック

こんにちは、私は砂漠の果ての狼です。

この記事では、以下の質問があります。コメント欄で答えを見つけてください。

1. APIインターセプトとは？
2. メソッドが多くの場所で呼び出されている場合、メソッドのソースコードを変更せずにメソッド呼び出しの前後時間を記録する方法は？
3. 同2では，ソースコードを変更せずにメソッドのパラメータをどのように修正（改ざん）するのか.
4. 同様に、ソースコードを変更せずにメソッドの戻り値を偽造する方法は？ ...

1. 前のページ

前言翻译自一个国外的文章，他写的更容易让人理解 - Hacking .NET – rewriting code you don’t control：

自分のものではないが、動作を変更したいクラスライブラリメソッドに遭遇したことがありますか？通常、メソッドは非公開であり、その動作をカバーする良い方法はありません。どのように動作するかがわかります（あなたは素晴らしく、ResharperやdnSpyのような逆コンパイルツールを使用していますよね？）。変えることはできません。Xの理由で変更する必要があります。

** いくつかのオプションがあります。

1. ソースコードを逆コンパイルまたはダウンロードして取得します最初に入手可能な場合。これはしばしば複雑なビルドプロセスと多くの依存関係を伴うため、しばしばリスクがあります。小さな変更を加えたい場合でも、ライブラリのブランチ全体を管理する責任があります。

2. 使用 ILDasm 反编译应用，直接修补 IL 代码，然后使用 ILAs 将其组装回来。在许多方面，这更好，因为您可以创建一个战略性的手术切口，而不是全面的“从头开始”的方法。缺点是您必须完全在IL中实现您的方法，这是一个不平凡的冒险。

署名されたライブラリを扱っている場合、上記のどちらの方法も動作しません。

现在让我们看一下另一种解决方法-内存修补。这与游戏作弊引擎几十年来使用的技术相同，这些引擎附加到正在运行的进程，查找内存位置并改变其行为。听起来很复杂？ 实际上，在 .NET 中做到这一点比听起来容易得多。我们将使用一个名为Harmony的库，该库在NuGet上可通过“Lib.Harmony”包获得。这是一个用于 .NET 的内存修补引擎，主要针对使用 Unity 构建的游戏，当然不止Unity。

この記事では、ウェブマスターが不可能だと思っていたことを変更する方法を説明します。自分のライブラリをブロック（フック）することから始まり、WPFライブラリと. NETベースのライブラリをブロック（フック）することまでです。

2. Hook独自のライブラリを傍受するHook独自のライブラリ

2.1.準備作業の準備

1. 创建一个控制台程序 HelloHook，添加类 Student：

namespace HelloHook;

public class Student
{
    public string GetDetails(string name)
    {
        return $"大家好，我是沙漠尽头的狼网站站长：{name}";
    }
}

Student类中定义了一个GetDetails方法，返回格式化的个人介绍信息，这个方法后面拦截试验使用。

2. Program.cs中添加Student调用：

using HelloHook;

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

実行プログラムの出力は以下のとおりです。

大家好，我是沙漠尽头的狼网站站长：沙漠尽头的狼

基本的な作業準備が完了し、これは簡単なコンソールプログラムであり、以下の記事の内容は、これら2つのプロジェクトに基づいて詳述されます。

2.2. 拦截GetDetails方法

1. インターセプトパッケージを導入-Lib.Harmony

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

<PackageReference Include="Lib.Harmony" Version="2.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. 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 {{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のどのバージョンでも使用できます。同じメソッドへの複数の変更は、上書きではなく累積的です。

傍受が必要なシナリオをもう一度分析して、この記事の記憶を深めます。

1. NETメソッドの一部は、コードレベルで直接変更できない場合があります。
2. 3番目のライブラリはソースコードを提供していませんが、メソッドの一部を変更したいと思います。
3. 3番目のライブラリはソースコードを提供しますが、ソースコードを変更することができますが、3番目のライブラリが反復アップグレードされた場合、更新する必要がある場合、アップグレードに伴う変更が面倒になる可能性があります。

** インターセプト注 **：ご覧の通り、これは多くの新しい可能性を開きます。力が大きければ大きいほど責任が大きいことを覚えなさい。元の開発者が意図しなかった方法で動作を上書きするため、新しいバージョンのコードをリリースしたときにパッチコードが機能する保証はありません。つまり、上記のポイント3では、3番目のライブラリアップグレードAPI構造も変更されていることを排除しません。

从《Harmony wiki patching》中翻译出以下使用注意事项：

1. 最新バージョン2.0は. NET Coreをサポートします。
2. Harmony支持手动（Patch，参考Harmony wiki上的使用）和自动（PatchAll，本文演示使用的这种方式，Lib.Harmony使用的是C#的特性机制）；
3. 元のメソッドごとにDynamicMethodメソッドを作成し、開始時Prefixと終了時Postfixでカスタムメソッドを呼び出すコードを織り込みます。また、元のILコードを処理するフィルタTranspilerを記述することもでき、元のメソッドをより詳細に操作することができます。
4. Getter/Setter、仮想メソッド/ 非仮想メソッド、静的メソッド;
5. パッチメソッドは静的でなければならない。
6. Prefixはvoidまたはbool型を返す必要があります（voidはインターセプトしません）。
7. Postfixはvoid型を返す必要があるか、最初のパラメータと同じ型を返す必要があります（パススルーモード）。
8. 元のメソッドが静的でない場合、__instance（2つのアンダースコア）という名前のパラメータを使用してオブジェクトインスタンスにアクセスできます。
9. メソッドの戻り値には__result（2つのアンダースコア）という名前のパラメータを使用してアクセスできます。Prefixの場合は、戻り値のデフォルト値が得られます。
10. __state（2つのアンダースコア）という名前のパラメータを使用して、Prefixパッチに任意の型の値を格納し、Postfixで使用することができます。Prefixで値を初期化する責任があります。
11. 元のメソッドと同じ名前のパラメータを使用してパラメータにアクセスできます。非参照型を記述する場合は、refキーワードを使用してください。
12. パッチで使用されるパラメータは、型（またはオブジェクト型）と名前に厳密に対応する必要があります。
13. パッチは、すべてのパラメータを記述するのではなく、必要なパラメータを定義するだけです。
14. パッチの再利用を可能にするには、__originalMethod 2つのアンダースコアというパラメータを使用して元のメソッドに注入します。

最后忘了补一条，.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フックにこのライブラリを使用しましたが、XXXです。
2. 私自身も同様の機能を実装しました，共有記事のリンクはXXXです。
3. このAPIをブロックできますか？シーンはXXX X。

[私のシェア] + [あなたのシェア] ∈ [. NETサークルの小さな力]

6. リファレンス

写作本文时以下文章都做了参考，建议大家都看看，特别是 Harmony wiki中写了Harmony的详细使用方法：

• Harmony
• Harmony wiki
• Harmony API文档
• Hacking .NET – rewriting code you don’t control
• Rimworld Mod制作教程6 使用Harmony对C#代码Patch
• 动态IL织入框架Harmony简单入手
• 一个开放源代码，实现动态IL注入(Hook或补丁工具)框架:Lib.Harmony
• .NET 7 Runtime Skipping Patches #504

7. 補足する。

• 2023年9月23日手動登録ブロック

非public类及方法如何拦截拦截|篡改|伪造.NET类库中不限于public的类和方法