dotnet 使用 dnlib 检测插件程序集的 API 兼容性

本文将和大家介绍在开发 dotnet 的插件时，如何通过 dnlib 库检测当前的插件是否由于主应用程序的版本差异导致存在 API 兼容性问题

众所周知，在开发插件的过程中，插件与主程序之间的兼容性问题将持续是一个令开发者烦恼的事情。举个例子，我开发的插件是面向 1.0 版本的主程序开发了，我需要用到 A 类型的 B 方法。结果在我插件发布一段时间之后，我的主程序更新到 2.0 版本了，此版本的主程序更改了 A 类型的 B 方法，比如删除了 B 方法，或者修改了 B 方法的函数参数。那么此时我的插件将会与主程序存在 API 不兼容问题，强行运行将会导致运行过程中抛出找不到成员的异常

本文介绍的 dnlib 库，可以用来辅助检测，当前的插件是否和主程序存在不兼容的问题。可以预先知道是否存在兼容问题，从而可以更好的给出用户交互

具体使用方法如下，按照 dotnet 的惯例，先安装 dnlib 库。可以通过如下方式编辑 csproj 项目文件，添加如下代码用来快速安装

  <ItemGroup>
    <PackageReference Include="dnlib" Version="4.4.0" />
  </ItemGroup>

接下来编写一个名为 CompatibilityChecker 的静态类型，将在此类型实现通过 dnlib 提供的功能进行兼容性检测

在 CompatibilityChecker 添加一个名为 CheckCompatibility 的方法，此方法将可以用来检测输入程序集是否存在与主程序的兼容性问题。方法定义如下

using dnlib.DotNet;

static class CompatibilityChecker
{
    /// <summary>
    /// 检查插件API兼容性
    /// </summary>
    /// <param name="assemblyFilePath"></param>
    /// <param name="searchPathList"></param>
    /// <returns>
    /// result: true表示API兼容 false表示不兼容
    /// missingMembers: 缺失的API
    /// exception: 检测过程中的异常
    /// </returns>
    public static (bool result, List<MemberRef> missingMembers, Exception? exception) CheckCompatibility(string assemblyFilePath, List<string> searchPathList)
    {
        try
        {
            var missingMembers = CompatibilityChecker.GetMembersRef(assemblyFilePath, searchPathList).GetMissingMembers();
            return (!missingMembers.Any(), missingMembers, null);
        }
        catch (Exception e)
        {
            return (false, new List<MemberRef>(0), e);
        }
    }
}

以上代码的 GetMembersRef 则需要将程序集进行分析加载，此分析加载过程中并非将程序集加入到当前程序域内，仅仅只是做二进制分析而已

    private static IEnumerable<MemberRef> GetMembersRef(string filePath, List<string> searchPathList)
    {
        var context = new ModuleContext(new AssemblyResolverWithSearchPathList(searchPathList));
        var module = ModuleDefMD.Load(filePath, context);
        return GetModuleMembersRef(module);
    }

以上的 AssemblyResolverWithSearchPathList 类型为自定义类型，作用就是根据输入的程序集依赖寻找路径列表，执行程序集依赖寻找策略。这个类型为本文所需要的核心实现方法，其核心原理就是通过 dnlib 的分析，读取程序集依赖寻找路径，查找是否存在某些依赖成员无法找到，从而了解是否存在兼容性问题

class AssemblyResolverWithSearchPathList : AssemblyResolver
{
    public AssemblyResolverWithSearchPathList(List<string> searchPathList)
    {
        SearchPathList = searchPathList;
    }

    private List<string> SearchPathList { get; }

    protected override IEnumerable<string> GetModuleSearchPaths(ModuleDef module) => base.GetModuleSearchPaths(module).Concat(SearchPathList);
}

以上的 GetModuleMembersRef 方法为获取当前 Module 的成员引用，其实现方法如下

    private static IEnumerable<MemberRef> GetModuleMembersRef(ModuleDefMD module)
    {
        return module.GetMemberRefs()
            .Select(x => (member: x, assembly: x.DeclaringType.DefinitionAssembly))
            .Where(x => x.assembly != module.Assembly)
            .Where(x => x.assembly is not null) // 如果存在动态程序集，那这里可能拿到空值
            .Where(x => !IgnoreAssemblies.Contains(x.assembly.Name.ToString())) // 这是可选的
            .Select(x => x.member);
    }

以上代码里面将过滤出依赖的成员，同时通过 IgnoreAssemblies 加入一些可供忽略的程序集。这些程序集是我实际开发过程中，发现 dnlib 支持较弱的，代码如下

    private static readonly HashSet<string> IgnoreAssemblies = new()
    {
        "Microsoft.CSharp",
        "mscorlib",
        "PresentationCore",
        "PresentationFramework",
        "System",
        "System.Collections",
        "System.Core",
        "System.Diagnostics.Debug",
        "System.Drawing",
        "System.Globalization",
        "System.IO",
        "System.IO.Compression",
        "System.Linq",
        "System.Linq.Expressions", // 尝试解决 dynamic 找不到 CallSite 的锅
        "System.Net.Http",
        "System.Reflection",
        "System.Reflection.Extensions",
        "System.Resources.ResourceManager",
        "System.Runtime",
        "System.Runtime.Extensions",
        "System.Runtime.InteropServices",
        "System.Text.Encoding",
        "System.Threading",
        "System.Threading.Tasks",
        "System.ValueTuple",
        "System.Windows.Forms",
        "System.Xaml",
        "WindowsBase",
        // 以下这个库会提示找不到 get_PageSize 和 Render 方法
        "PdfiumViewer",
        // 以下的几个库提示找不到方法，细节我还不知道
        "OpenAI-DotNet",
        "Azure.AI.OpenAI",
        "Azure.Core",
        "Microsoft.SemanticKernel.Core",
        "Microsoft.SemanticKernel",
        "Microsoft.SemanticKernel.Abstractions",
        "Microsoft.SemanticKernel.Planning.ActionPlanner",
        "Microsoft.SemanticKernel.Planning.SequentialPlanner",
        "Microsoft.SemanticKernel.Skills.Core",
        "Microsoft.SemanticKernel.Connectors.AI.OpenAI",
    };

如果没有忽略这几个程序集，可能插件程序集在寻找依赖是否缺失的过程中，将会寻找失败或者是提示以上程序集里面必定存在某些缺失的成员

最后的 GetMissingMembers 方法则是通过判断其引用成员是否 Resolve 失败，返回失败的列表，代码如下

    private static List<MemberRef> GetMissingMembers(this IEnumerable<MemberRef> members) => members.Where(x => x.Resolve() == null).ToList();

如此即可完成 CompatibilityChecker 类型的实现，下面来看看其使用方法

首先是获取需要检测的插件程序集所在的文件路径，作为 filePath 参数传入，这个属于大家自己的业务逻辑，还请自行解决。接下来构建 依赖寻找文件夹路径列表，一般来说插件程序集所在的文件夹里面可能包含插件本身所需依赖，于是先将插件程序集所在文件夹加入到依赖寻找文件夹路径列表里，代码如下

    var searchPathList = new List<string>();
    var directoryName = Path.GetDirectoryName(filePath);
    if (directoryName != null)
    {
        searchPathList.Add(directoryName);
    }
    else
    {
        // 见鬼了，这个文件不在文件夹里？
    }

接下来将主应用程序所在的文件夹也加入到 依赖寻找文件夹路径列表 里面

最后需要将 dotnet 系列依赖加入，比如我的 dotnet 依赖是打到主应用程序里面的，参考 记将一个大型客户端应用项目迁移到 dotnet 6 的经验和决策

我需要使用如下代码将应用程序所使用的定制版本的 dotnet 加入到依赖寻找列表，如以下代码

    var dotnetRuntimeFolderRoot = Path.Combine(mainApplicationPath, @"..\runtime\shared\Microsoft.NETCore.App\");
    if (Directory.Exists(dotnetRuntimeFolderRoot))
    {
        var dotnetRuntimeFolder = Directory
            .GetDirectories(dotnetRuntimeFolderRoot, "*", SearchOption.TopDirectoryOnly).FirstOrDefault();
        if (dotnetRuntimeFolder != null)
        {
            searchPathList.Add(dotnetRuntimeFolder);
        }
    }

对于 WPF 和 WinForms 项目，我还需要将 Microsoft.WindowsDesktop.App 也加入到依赖寻找列表，如以下代码

    var desktopRuntimeFolderRoot = Path.Combine(mainApplicationPath, @"..\runtime\shared\Microsoft.WindowsDesktop.App\");
    if (Directory.Exists(desktopRuntimeFolderRoot))
    {
        var desktopRuntimeFolder = Directory.GetDirectories(desktopRuntimeFolderRoot, "*", SearchOption.TopDirectoryOnly).FirstOrDefault();
        if (desktopRuntimeFolder != null)
        {
            searchPathList.Add(desktopRuntimeFolder);
        }
    }

完成依赖寻找列表之后，即可调用 CheckCompatibility 方法，如以下代码

    var (result, missingMembers, exception) = CompatibilityChecker.CheckCompatibility(filePath, searchPathList);

通过判断 result 即可知道当前的插件程序集是否和主应用程序之间存在兼容问题，且通过 missingMembers 可以了解存在哪些 API 不兼容

通过此方法即可判断插件是否与主应用程序存在兼容性问题，从而更好进行用户界面交互