使用 .NET Core 3.0 的 AssemblyLoadContext 實現外掛熱載入

阿新 • • 發佈：2019-10-07

一般情況下，一個 .NET 程式集載入到程式中以後，它的型別資訊以及原生程式碼等資料會一直保留在記憶體中，.NET 執行時無法回收它們，如果我們要實現外掛熱載入 (例如 Razor 或 Aspx 模版的熱更新) 則會造成記憶體洩漏。在以往，我們可以使用 .NET Framework 的 AppDomain 機制，或者使用直譯器 (有一定的效能損失)，或者在編譯一定次數以後重啟程式 (Asp.NET 的 numRecompilesBeforeAppRestart) 來避免記憶體洩漏。

因為 .NET Core 不像 .NET Framework 一樣支援動態建立與解除安裝 AppDomain，所以一直都沒有好的方法實現外掛熱載入，好訊息是，.NET Core 從 3.0 開始支援了可回收程式集 (Collectible Assembly)，我們可以建立一個可回收的 AssemblyLoadContext，用它來載入與解除安裝程式集。關於 AssemblyLoadContext 的介紹與實現原理可以參考 yoyofx 的文章與我的文章。

本文會通過一個 180 行左右的示例程式，介紹如何使用 .NET Core 3.0 的 AssemblyLoadContext 實現外掛熱載入，程式同時使用了 Roslyn 實現動態編譯，最終效果是改動外掛程式碼後可以自動更新到正在執行的程式當中，並且不會造成記憶體洩漏。

完整原始碼與資料夾結構

首先我們來看看完整原始碼與資料夾結構，原始碼分為兩部分，一部分是宿主，負責編譯與載入外掛，另一部分則是外掛，後面會對原始碼的各個部分作出詳細講解。

資料夾結構:

pluginexample (頂級資料夾)
- host (宿主的專案)
  - Program.cs (宿主的程式碼)
  - host.csproj (宿主的專案檔案)
- guest (外掛的程式碼資料夾)
  - Plugin.cs (外掛的程式碼)
  - bin (儲存外掛編譯結果的資料夾)
    - MyPlugin.dll (外掛編譯後的 DLL 檔案)

Program.cs 的內容:

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Runtime.Loader;
using System.Threading;

namespace Common
{
    public interface IPlugin : IDisposable
    {
        string GetMessage();
    }
}

namespace Host
{
    using Common;

    internal class PluginController : IPlugin
    {
        private List<Assembly> _defaultAssemblies;
        private AssemblyLoadContext _context;
        private string _pluginName;
        private string _pluginDirectory;
        private volatile IPlugin _instance;
        private volatile bool _changed;
        private object _reloadLock;
        private FileSystemWatcher _watcher;

        public PluginController(string pluginName, string pluginDirectory)
        {
            _defaultAssemblies = AssemblyLoadContext.Default.Assemblies
                .Where(assembly => !assembly.IsDynamic)
                .ToList();
            _pluginName = pluginName;
            _pluginDirectory = pluginDirectory;
            _reloadLock = new object();
            ListenFileChanges();
        }

        private void ListenFileChanges()
        {
            Action<string> onFileChanged = path =>
            {
                if (Path.GetExtension(path).ToLower() == ".cs")
                    _changed = true;
            };
            _watcher = new FileSystemWatcher();
            _watcher.Path = _pluginDirectory;
            _watcher.IncludeSubdirectories = true;
            _watcher.NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName;
            _watcher.Changed += (sender, e) => onFileChanged(e.FullPath);
            _watcher.Created += (sender, e) => onFileChanged(e.FullPath);
            _watcher.Deleted += (sender, e) => onFileChanged(e.FullPath);
            _watcher.Renamed += (sender, e) => { onFileChanged(e.FullPath); onFileChanged(e.OldFullPath); };
            _watcher.EnableRaisingEvents = true;
        }

        private void UnloadPlugin()
        {
            _instance?.Dispose();
            _instance = null;
            _context?.Unload();
            _context = null;
        }

        private Assembly CompilePlugin()
        {
            var binDirectory = Path.Combine(_pluginDirectory, "bin");
            var dllPath = Path.Combine(binDirectory, $"{_pluginName}.dll");
            if (!Directory.Exists(binDirectory))
                Directory.CreateDirectory(binDirectory);
            if (File.Exists(dllPath))
            {
                File.Delete($"{dllPath}.old");
                File.Move(dllPath, $"{dllPath}.old");
            }

            var sourceFiles = Directory.EnumerateFiles(
                _pluginDirectory, "*.cs", SearchOption.AllDirectories);
            var compilationOptions = new CSharpCompilationOptions(
                OutputKind.DynamicallyLinkedLibrary,
                optimizationLevel: OptimizationLevel.Debug);
            var references = _defaultAssemblies
                .Select(assembly => assembly.Location)
                .Where(path => !string.IsNullOrEmpty(path) && File.Exists(path))
                .Select(path => MetadataReference.CreateFromFile(path))
                .ToList();
            var syntaxTrees = sourceFiles
                .Select(p => CSharpSyntaxTree.ParseText(File.ReadAllText(p)))
                .ToList();
            var compilation = CSharpCompilation.Create(_pluginName)
                .WithOptions(compilationOptions)
                .AddReferences(references)
                .AddSyntaxTrees(syntaxTrees);

            var emitResult = compilation.Emit(dllPath);
            if (!emitResult.Success)
            {
                throw new InvalidOperationException(string.Join("\r\n",
                    emitResult.Diagnostics.Where(d => d.WarningLevel == 0)));
            }
            //return _context.LoadFromAssemblyPath(Path.GetFullPath(dllPath));
            using (var stream = File.OpenRead(dllPath))
            {
                var assembly = _context.LoadFromStream(stream);
                return assembly;
            }
        }

        private IPlugin GetInstance()
        {
            var instance = _instance;
            if (instance != null && !_changed)
                return instance;

            lock (_reloadLock)
            {
                instance = _instance;
                if (instance != null && !_changed)
                    return instance;

                UnloadPlugin();
                _context = new AssemblyLoadContext(
                    name: $"Plugin-{_pluginName}", isCollectible: true);

                var assembly = CompilePlugin();
                var pluginType = assembly.GetTypes()
                    .First(t => typeof(IPlugin).IsAssignableFrom(t));
                instance = (IPlugin)Activator.CreateInstance(pluginType);

                _instance = instance;
                _changed = false;
            }

            return instance;
        }

        public string GetMessage()
        {
            return GetInstance().GetMessage();
        }

        public void Dispose()
        {
            UnloadPlugin();
            _watcher?.Dispose();
            _watcher = null;
        }
    }

    internal class Program
    {
        static void Main(string[] args)
        {
            using (var controller = new PluginController("MyPlugin", "../guest"))
            {
                bool keepRunning = true;
                Console.CancelKeyPress += (sender, e) => {
                    e.Cancel = true;
                    keepRunning = false;
                };
                while (keepRunning)
                {
                    try
                    {
                        Console.WriteLine(controller.GetMessage());
                    }
                    catch (Exception ex)
                    {
                        Console.WriteLine($"{ex.GetType()}: {ex.Message}");
                    }
                    Thread.Sleep(1000);
                }
            }
        }
    }
}

host.csproj 的內容:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="3.3.1" />
  </ItemGroup>

</Project>

Plugin.cs 的內容:

using System;
using Common;

namespace Guest
{
    public class MyPlugin : IPlugin
    {
        public MyPlugin()
        {
            Console.WriteLine("MyPlugin loaded");
        }

        public string GetMessage()
        {
            return "Hello 1";
        }

        public void Dispose()
        {
            Console.WriteLine("MyPlugin unloaded");
        }
    }
}

執行示例程式

進入 pluginexample/host 下執行 dotnet run 即可啟動宿主程式，這時宿主程式會自動編譯與載入外掛，檢測外掛檔案的變化並在變化時重新編譯載入。你可以在執行後修改 pluginexample/guest/Plugin.cs 中的 Hello 1 為 Hello 2，之後可以看到類似以下的輸出：

MyPlugin loaded
Hello 1
Hello 1
Hello 1
MyPlugin unloaded
MyPlugin loaded
Hello 2
Hello 2

我們可以看到程式自動更新並執行修改以後的程式碼，如果你有興趣還可以測試外掛程式碼語法錯誤時會出現什麼。

原始碼講解

接下來是對宿主的原始碼中各個部分的詳細講解：

IPlugin 介面

public interface IPlugin : IDisposable
{
    string GetMessage();
}

這是外掛專案需要的實現介面，宿主專案在編譯外掛後會尋找程式集中實現 IPlugin 的型別，建立這個型別的例項並且使用它，建立外掛時會呼叫建構函式，解除安裝外掛時會呼叫 Dispose 方法。如果你用過 .NET Framework 的 AppDomain 機制可能會想是否需要 Marshalling 處理，答案是不需要，.NET Core 的可回收程式集會載入到當前的 AppDomain 中，回收時需要依賴 GC 清理，好處是使用簡單並且執行效率高，壞處是 GC 清理有延遲，只要有一個外掛中型別的例項沒有被回收則外掛程式集使用的資料會一直殘留，導致記憶體洩漏。

PluginController 型別

internal class PluginController : IPlugin
{
    private List<Assembly> _defaultAssemblies;
    private AssemblyLoadContext _context;
    private string _pluginName;
    private string _pluginDirectory;
    private volatile IPlugin _instance;
    private volatile bool _changed;
    private object _reloadLock;
    private FileSystemWatcher _watcher;

這是管理外掛的代理類，在內部它負責編譯與載入外掛，並且把對 IPlugin 介面的方法呼叫轉發到外掛的實現中。類成員包括預設 AssemblyLoadContext 中的程式集列表 _defaultAssemblies，用於載入外掛的自定義 AssemblyLoadContext _context，外掛名稱與資料夾，外掛實現 _instance，標記外掛檔案是否已改變的 _changed，防止多個執行緒同時編譯載入外掛的 _reloadLock，與監測外掛檔案變化的 _watcher。

PluginController 的建構函式

public PluginController(string pluginName, string pluginDirectory)
{
    _defaultAssemblies = AssemblyLoadContext.Default.Assemblies
        .Where(assembly => !assembly.IsDynamic)
        .ToList();
    _pluginName = pluginName;
    _pluginDirectory = pluginDirectory;
    _reloadLock = new object();
    ListenFileChanges();
}

建構函式會從 AssemblyLoadContext.Default.Assemblies 中獲取預設 AssemblyLoadContext 中的程式集列表，包括宿主程式集、System.Runtime 等，這個列表會在 Roslyn 編譯外掛時使用，表示外掛編譯時需要引用哪些程式集。之後還會呼叫 ListenFileChanges 監聽外掛檔案是否有改變。

PluginController.ListenFileChanges

private void ListenFileChanges()
{
    Action<string> onFileChanged = path =>
    {
        if (Path.GetExtension(path).ToLower() == ".cs")
            _changed = true;
    };
    _watcher = new FileSystemWatcher();
    _watcher.Path = _pluginDirectory;
    _watcher.IncludeSubdirectories = true;
    _watcher.NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName;
    _watcher.Changed += (sender, e) => onFileChanged(e.FullPath);
    _watcher.Created += (sender, e) => onFileChanged(e.FullPath);
    _watcher.Deleted += (sender, e) => onFileChanged(e.FullPath);
    _watcher.Renamed += (sender, e) => { onFileChanged(e.FullPath); onFileChanged(e.OldFullPath); };
    _watcher.EnableRaisingEvents = true;
}

這個方法建立了 FileSystemWatcher，監聽外掛資料夾下的檔案是否有改變，如果有改變並且改變的是 C# 原始碼 (.cs 副檔名) 則設定 _changed 成員為 true，這個成員標記外掛檔案已改變，下次訪問外掛例項的時候會觸發重新載入。

你可能會有疑問，為什麼不在檔案改變後立刻觸發重新載入外掛，一個原因是部分檔案編輯器的儲存檔案實現可能會導致改變的事件連續觸發幾次，延遲觸發可以避免編譯多次，另一個原因是編譯過程中出現的異常可以傳遞到訪問外掛例項的執行緒中，方便除錯與除錯 (儘管使用 ExceptionDispatchInfo 也可以做到)。

PluginController.UnloadPlugin

private void UnloadPlugin()
{
    _instance?.Dispose();
    _instance = null;
    _context?.Unload();
    _context = null;
}

這個方法會解除安裝已載入的外掛，首先呼叫 IPlugin.Dispose 通知外掛正在解除安裝，如果外掛建立了新的執行緒可以在 Dispose 方法中停止執行緒避免洩漏，然後呼叫 AssemblyLoadContext.Unload 允許 .NET Core 執行時解除安裝這個上下文載入的程式集，程式集的資料會在 GC 檢測到所有型別的例項都被回收後回收 (參考文章開頭的連結)。

PluginController.CompilePlugin

private Assembly CompilePlugin()
{
    var binDirectory = Path.Combine(_pluginDirectory, "bin");
    var dllPath = Path.Combine(binDirectory, $"{_pluginName}.dll");
    if (!Directory.Exists(binDirectory))
        Directory.CreateDirectory(binDirectory);
    if (File.Exists(dllPath))
    {
        File.Delete($"{dllPath}.old");
        File.Move(dllPath, $"{dllPath}.old");
    }

    var sourceFiles = Directory.EnumerateFiles(
        _pluginDirectory, "*.cs", SearchOption.AllDirectories);
    var compilationOptions = new CSharpCompilationOptions(
        OutputKind.DynamicallyLinkedLibrary,
        optimizationLevel: OptimizationLevel.Debug);
    var references = _defaultAssemblies
        .Select(assembly => assembly.Location)
        .Where(path => !string.IsNullOrEmpty(path) && File.Exists(path))
        .Select(path => MetadataReference.CreateFromFile(path))
        .ToList();
    var syntaxTrees = sourceFiles
        .Select(p => CSharpSyntaxTree.ParseText(File.ReadAllText(p)))
        .ToList();
    var compilation = CSharpCompilation.Create(_pluginName)
        .WithOptions(compilationOptions)
        .AddReferences(references)
        .AddSyntaxTrees(syntaxTrees);

    var emitResult = compilation.Emit(dllPath);
    if (!emitResult.Success)
    {
        throw new InvalidOperationException(string.Join("\r\n",
            emitResult.Diagnostics.Where(d => d.WarningLevel == 0)));
    }
    //return _context.LoadFromAssemblyPath(Path.GetFullPath(dllPath));
    using (var stream = File.OpenRead(dllPath))
    {
        var assembly = _context.LoadFromStream(stream);
        return assembly;
    }
}

這個方法會呼叫 Roslyn 編譯外掛程式碼到 DLL，並使用自定義的 AssemblyLoadContext 載入編譯後的 DLL。首先它需要刪除原有的 DLL 檔案，因為解除安裝程式集有延遲，原有的 DLL 檔案在 Windows 系統上很可能會刪除失敗並提示正在使用，所以需要先重新命名並在下次刪除。接下來它會查詢外掛資料夾下的所有 C# 原始碼，用 CSharpSyntaxTree 解析它們，並用 CSharpCompilation 編譯，編譯時引用的程式集列表是建構函式中取得的預設 AssemblyLoadContext 中的程式集列表 (包括宿主程式集，這樣外掛程式碼才可以使用 IPlugin 介面）。編譯成功後會使用自定義的 AssemblyLoadContext 載入編譯後的 DLL 以支援解除安裝。

這段程式碼中有兩個需要注意的部分，第一個部分是 Roslyn 編譯失敗時不會丟擲異常，編譯後需要判斷 emitResult.Success 並從 emitResult.Diagnostics 找到錯誤資訊；第二個部分是載入外掛程式集必須使用 AssemblyLoadContext.LoadFromStream 從記憶體資料載入，如果使用 AssemblyLoadContext.LoadFromAssemblyPath 那麼下次從同一個路徑載入時仍然會返回第一次載入的程式集，這可能是 .NET Core 3.0 的實現問題並且有可能在以後的版本修復。

PluginController.GetInstance

private IPlugin GetInstance()
{
    var instance = _instance;
    if (instance != null && !_changed)
        return instance;

    lock (_reloadLock)
    {
        instance = _instance;
        if (instance != null && !_changed)
            return instance;

        UnloadPlugin();
        _context = new AssemblyLoadContext(
            name: $"Plugin-{_pluginName}", isCollectible: true);

        var assembly = CompilePlugin();
        var pluginType = assembly.GetTypes()
            .First(t => typeof(IPlugin).IsAssignableFrom(t));
        instance = (IPlugin)Activator.CreateInstance(pluginType);

        _instance = instance;
        _changed = false;
    }

    return instance;
}

這個方法是獲取最新外掛例項的方法，如果外掛例項已建立並且檔案沒有改變，則返回已有的例項，否則解除安裝原有的外掛、重新編譯外掛、載入並生成例項。注意 AssemblyLoadContext 型別在 netstandard (包括 2.1) 中是 abstract 型別，不能直接建立，只有 netcoreapp3.0 才可以直接建立 (目前也只有 .NET Core 3.0 支援這項機制)，如果需要支援可回收則建立時需要設定 isCollectible 引數為 true，因為支援可回收會讓 GC 掃描物件時做一些額外的工作所以預設不啟用。

PluginController.GetMessage

public string GetMessage()
{
    return GetInstance().GetMessage();
}

這個方法是代理方法，會獲取最新的外掛例項並轉發呼叫引數與結果，如果 IPlugin 有其他方法也可以像這個方法一樣寫。

PluginController.Dispose

public void Dispose()
{
    UnloadPlugin();
    _watcher?.Dispose();
    _watcher = null;
}

這個方法支援主動釋放 PluginController，會解除安裝已載入的外掛並且停止監聽外掛檔案。因為 PluginController 沒有直接管理非託管資源，並且 AssemblyLoadContext 的解構函式會觸發解除安裝，所以 PluginController 不需要提供解構函式。

主函式程式碼

static void Main(string[] args)
{
    using (var controller = new PluginController("MyPlugin", "../guest"))
    {
        bool keepRunning = true;
        Console.CancelKeyPress += (sender, e) => {
            e.Cancel = true;
            keepRunning = false;
        };
        while (keepRunning)
        {
            try
            {
                Console.WriteLine(controller.GetMessage());
            }
            catch (Exception ex)
            {
                Console.WriteLine($"{ex.GetType()}: {ex.Message}");
            }
            Thread.Sleep(1000);
        }
    }
}

主函式建立了 PluginController 例項並指定了上述的 guest 資料夾為外掛資料夾，之後每隔 1 秒呼叫一次 GetMessage 方法，這樣外掛程式碼改變的時候我們可以從控制檯輸出中觀察的到，如果外掛程式碼包含語法錯誤則呼叫時會丟擲異常，程式會繼續執行並在下一次呼叫時重新嘗試編譯與載入。

寫在最後

本文的介紹就到此為止了，在本文中我們看到了一個最簡單的 .NET Core 3.0 外掛熱載入實現，這個實現仍然有很多需要改進的地方，例如如何管理多個外掛、怎麼在重啟宿主程式後避免重新編譯所有外掛，編譯的外掛程式碼如何除錯等，如果你有興趣可以解決它們，做一個外掛系統嵌入到你的專案中，或者寫一個新的框架。

關於 ZKWeb，3.0 會使用了本文介紹的機制實現外掛熱載入，但因為我目前已經退出 IT 行業，所有開發都是業餘空閒時間做的，所以基本上不會有很大的更新，ZKWeb 更多的會作為一個框架的實現參考。此外，我正在使用 C++ 編寫 HTTP 框架 cpv-framework，主要著重效能 (吞吐量是 .NET Core 3.0 的兩倍以上，與 actix-web 持平)，目前還沒有正式釋出。

關於書籍，出版社約定 11 月但目前還沒有讓我看修改過的稿件 (儘管我問的時候會回答)，所以很大可能會繼續延期，抱歉讓期待出版的同學們久等了，書籍目前還是基於 .NET Core 2.2 而不是 .NET Core 3.0

使用 .NET Core 3.0 的 AssemblyLoadContext 實現外掛熱載入

完整原始碼與資料夾結構

執行示例程式

原始碼講解

IPlugin 介面

PluginController 型別

PluginController 的建構函式

PluginController.ListenFileChanges

PluginController.UnloadPlugin

PluginController.CompilePlugin

PluginController.GetInstance

PluginController.GetMessage

PluginController.Dispose

主函式程式碼

寫在最後

使用 .NET Core 3.0 的 AssemblyLoadContext 實現外掛熱載入

.net core 3.0 Signalr - 實現一個業務推送系統

.NET Core 3.0 可回收程式集載入上下文

ASP.NET Core 3.0 原生DI拓展實現IocManager

這就是你想要的 C#8.0 和.NET Core 3.0

ASP.NET Core 3.0 實戰：構建多版本 API 介面

ASP.NET Core 3.0 實戰：構建多版本 API 接口

ASP.NET Core 3.0：將會擁有更少的依賴

ASP.NET Core 3.0 上的gRPC服務模板初體驗(多圖)

[翻譯] 使用 .NET Core 3.0 創建一個 Windows 服務

.NET Core 3.0之Configuration原始碼探究(一)

自動擋換手動擋：在 ASP.NET Core 3.0 Middleware 中手動執行 Controller Action

.NET Core 3.0之深入原始碼理解Configuration(二)

.NET Core 3.0之深入原始碼理解Configuration(三)

.NET Core 3.0之建立基於Consul的Configuration擴充套件元件

從ASP.NET Core 3.0 preview 特性，瞭解CLR的Garbage Collection

.NET Core 3.0 之初識Host原始碼

.NET Core 3.0 Preview 6中對ASP.NET Core和Blazor的更新

使用dotnet-dump 查詢 .net core 3.0 佔用CPU 100%的原因

在.NET Core 3.0中的WPF中使用IOC圖文教程

使用 .NET Core 3.0 的 AssemblyLoadContext 實現外掛熱載入

完整原始碼與資料夾結構

執行示例程式

原始碼講解

IPlugin 介面

PluginController 型別

PluginController 的建構函式

PluginController.ListenFileChanges

PluginController.UnloadPlugin

PluginController.CompilePlugin

PluginController.GetInstance

PluginController.GetMessage

PluginController.Dispose

主函式程式碼

寫在最後

相關推薦