Skip to content

Quick Start

Jump to bottom
Ling edited this page Jul 12, 2026 · 4 revisions

快速开始

本页从零创建一个最小的 PCL Nex C# 插件。当前插件 SDK 由 PCL.Plugin.Abstractions 提供，目标框架为 net8.0-windows，公开契约版本为 1.2.1。

1. 创建项目

dotnet new classlib -n HelloPlugin --framework net8.0-windows
cd HelloPlugin

编辑 HelloPlugin.csproj，启用 WPF 并引用插件 SDK：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <UseWPF>true</UseWPF>
    <EnableWindowsTargeting>true</EnableWindowsTargeting>
    <OutputType>Library</OutputType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PlainCraftLauncher.Plugin.Abstractions" Version="1.2.1" ExcludeAssets="runtime" />
  </ItemGroup>
</Project>

ExcludeAssets="runtime" 很重要。启动器会提供自己的 PCL.Plugin.Abstractions.dll，插件包不应再携带一份，否则宿主和插件可能拿到不同的接口类型。

如果 SDK 包尚未发布到 NuGet，可以在本地开发时直接引用源码仓库中的 PCL.Plugin.Abstractions.csproj。

2. 编写入口类

每个 C# 插件程序集应有一个入口类实现 IPclPlugin，并用 [Plugin] 标注。继承 PclPluginBase 可以获得空的默认卸载实现和便捷日志字段。

using System.Threading;
using System.Threading.Tasks;
using PCL.Plugin.Abstractions;

namespace Example.HelloPlugin;

[Plugin(
    id: "com.example.hello",
    name: "Hello Plugin",
    version: "1.0.0.0",
    Author = "Example",
    Description = "A minimal PCL Nex plugin.",
    MinApiVersion = "1.2.1.0",
    Capabilities = PluginCapabilities.None,
    LoadTiming = PluginLoadTiming.WindowCreated)]
public sealed class HelloPlugin : PclPluginBase
{
    public override Task LoadAsync(IPluginContext context, CancellationToken cancellationToken = default)
    {
        context.Host.Core.Hint("Hello from plugin", PluginHintType.Success);
        context.Host.Core.GetLogger("hello").Info("Hello Plugin loaded.");
        return Task.CompletedTask;
    }
}

入口类必须有公共无参构造函数。LoadAsync 加载超时时间为 30 秒，长任务应使用异步方式或放到后台执行。

3. 添加 plugin.json

在插件包根目录放置 plugin.json。C# 插件使用 runtime: "dotnet"，入口程序集字段为 entryAssembly：

{
  "id": "com.example.hello",
  "name": "Hello Plugin",
  "version": "1.0.0.0",
  "author": "Example",
  "description": "A minimal PCL Nex plugin.",
  "runtime": "dotnet",
  "entryAssembly": "HelloPlugin.dll",
  "minApiVersion": "1.2.1.0",
  "capabilities": []
}

plugin.json 用于安装和加载阶段的包校验；[Plugin] 用于在程序集内定位运行时入口。两处的 id、name、version、能力声明应保持一致。

4. 构建

dotnet build .\HelloPlugin.csproj --configuration Release --property:Platform=AnyCPU

构建产物通常位于：

bin/Release/net8.0-windows/HelloPlugin.dll

5. 安装

把插件目录放到启动器插件目录下。当前加载器会扫描 PCL/Plugins/*/plugin.json，并兼容旧的 PCL/Plugins/*.dll 平铺 DLL 布局。

推荐目录结构：

Plugins/
  com.example.hello/
    plugin.json
    HelloPlugin.dll
    DependencyA.dll

重启 PCL Nex 后，插件加载器会读取清单、检查 API/启动器版本兼容性、加载入口程序集并调用 LoadAsync。

下一步

Clone this wiki locally