跳到正文
返回搜索

星光 · C# Provider

作者 HosihikariFramework

星光框架的 C# 型插件 Provider:装载时编译脚本,交给 collectible ALC

  • 107 次下载
  • 更新于
0.2.3

README0.2.3

Hosihikari.PluginProvider.CSharp

English | 简体中文

星光框架的 C# 型插件 Provider。与 F# 一样,C# 直接跑在 CLR 上,所以这个 Provider 装载时编译: Roslyn 把 .cs 编成真程序集,再进一个 collectible ALC。

C# 插件因此拿到与其他程序集插件一样的承诺:每插件的依赖互相隔离,卸载是真的验证过而不是假定的。 这是一等 Provider:在插件开始运行前把源码 AOT 为 IL,Provider 把 IL 装进 collectible ALC。

进程内只留 .NET。 框架在进程内保留程序集型、C# 与 F# 三个 Provider;其他语言走 通用的进程外 Provider(Hosihikari.PluginProvider.Rpc,ADR-0031)。

模板

从 CSharpPluginTemplate 开始:复制到 plugins/,改名后重启。预编译程序集用 dotnet new 模板。

插件包长什么样

plugins/Hello/
  manifest.json
    {
      "name": "Hello",
      "entry": "main.cs",
      "type": "hosihikari",
      "version": "1.0.0",
      "dependencies": [
        { "name": "hosihikari" },
        { "name": "hosihikari-csharp" }
      ],
      "extraInfo": { "api": "2", "format_version": "1", "provider": "csharp" }
    }
  main.cs
  Hello.conf          ← 作者给的默认值,随包更新

文件里定义一个实现 IPlugin、有无参构造的类型;找到它是 Provider 的事。

using System.IO;
using Hosihikari;

public sealed class HelloPlugin : IPlugin
{
    private string _data = "";

    public void OnLoad(IPluginContext context)
    {
        _data = context.DataDirectory;
        File.WriteAllText(Path.Combine(_data, "body.txt"), "body:" + context.Configuration["greeting"]);
    }

    public PluginHookResult OnEnable()
    {
        File.WriteAllText(Path.Combine(_data, "enabled.txt"), "enabled");
        return PluginHookResult.Allow();
    }

    public PluginHookResult OnDisable() => PluginHookResult.Allow();
    public void OnUnload() { }
}

编出来的是一个引用了契约的真程序集,所以 C# 插件拿得到任何插件都拿得到的东西 —— 包括那些按类型做键的通道。

file-based 指令

main.cs 开头可以写 #:package Id@Version 与 #:include path.cs,与 .NET file-based apps 对齐。Provider 在 Roslyn 编译前把它们换成空行;打包器在打包期把包还原进插件包并复制被 include 的文件,服务端保持离线。#:include 支持 *、**、? 通配符。#:project、#:property、 #:sdk 与顶层语句不支持。

它怎么编译

用 Roslyn 的 CSharpCompilation(Microsoft.CodeAnalysis.CSharp)。引用 = 宿主的运行时,加上 框架自己那个装载上下文里的程序集 —— 宿主被装在一个隔离的 ALC 里,契约与它的抽象包不在默认上下文。 包根目录内的私有 DLL 也参与编译引用,运行时从包目录解析;共享框架程序集仍保持原来的类型身份。 解析源码时要给编码,否则 Roslyn 拒绝发调试信息(CS8055)。

产物按内容寻址缓存(ADR-0029):<数据目录>/bin/<哈希>/<名字>.dll,哈希覆盖源码内容、Roslyn 版本与 运行时版本,以及包内私有 DLL 的名字和内容。产物旁存一份校验和,加载前对一遍 —— 对不上就重编,绝不照跑。编译先落到临时目录、成功了才 改名进去;同时产出 portable PDB,日志里的栈因此带 file:line。

校验和防的是事故,不防恶意:插件与本框架同进程、且完全受信(ADR-0011)。

跑一遍

dotnet run --project host/Hosihikari.PluginProvider.CSharp.Host.csproj -c Release

验证宿主借核心的 PluginManagerHost 驱动它,所以需要并列的 Hosihikari.PluginManager、 Hosihikari.Abstractions 与 McMaster 的 fork checkout。它验证:Provider 由插件包登记、产物按内容寻址落盘且带校验和 与 PDB、源码装载时编译并读到包外覆盖、启用钩子到达插件、宿主发的通道消息它能收到、包内自带的第三方依赖 可用、本机库按 RID 目录解析、停用与卸载钩子到达、卸载验证通过、同一份源码再装载命中缓存、以及产物被改坏后会被发现并重编。 测试还会构建宿主没有引用的独立 DLL,验证真正私有的依赖也能在插件中使用。

它怎么进宿主进程

作为插件包,名字是 hosihikari-csharp —— 与其他进程内 Provider 同一套。源码包声明依赖,依赖图先排它。

登记之后不能撤销:它造出来的类型住在它的装载上下文里。

打包

pwsh ./pack.ps1 -Version 0.2.3 -OutputRoot artifacts

它把 Provider DLL、私有依赖与清单装进 hosihikari-csharp/,共享层不随包走;打 v* 标签时 CI 把 zip 附到 release(ADR-0036)。

打包脚本调用核心打包器(Hosihikari.PluginManager/tools/Pack),共享层清单由核心统一给出;需要并列检出核心仓,或设置 HOSIHIKARI_PLUGINMANAGER。

发布后:lip install github.com/HosihikariFramework/CSharpProvider(先按载体装 Shim)。

许可

LGPL-3.0-or-later,见 LICENSE.md。

安装 星光 · C# Provider

运行端
  • 服务端
  • 客户端
平台
  • win-x64
  • win-arm64
  • linux-x64
  • linux-arm64
  • android-arm64

在服务端目录中用 lip 运行:

lip install github.com/HosihikariFramework/CSharpProvider@0.2.3

在客户端上,请通过以下方式安装: LeviLauncher

从 GitHub 下载