Mj·Dock 插件开发指南

欢迎来到 Mj·Dock 开发者社区！本指南将带您从零开始创建一个功能完整的插件。

快速开始

1. 创建项目

Mj·Dock 插件本质上是一个 .NET 类库（.dll）。请确保您已安装 .NET 8 SDK。

# 创建类库项目
dotnet new classlib -n MyMjDockPlugin
cd MyMjDockPlugin

# 添加 SDK 引用 (假设 SDK 在上级目录)
dotnet add reference ..\SDK\MjDockApp.SDK.csproj

2. 实现插件入口

创建一个继承自 PluginBase 的类，并添加 [PluginExport] 特性。

using MjDockApp.SDK;
using MjDockApp.SDK.Models.Plugin;

namespace MyMjDockPlugin;

[PluginExport("MyPlugin", "1.0.0", "我的第一个插件")]
public class MyPlugin : PluginBase
{
    public override Task InitializeAsync(IPluginContext context)
    {
        context.LogInfo("插件已启动！");
        return Task.CompletedTask;
    }

    public override Task<QueryResult?> QueryAsync(QueryContext context)
    {
        if (context.Query == "hello")
        {
            return Task.FromResult(new QueryResult
            {
                Items = new List<ResultItem>
                {
                    new ResultItem
                    {
                        Title = "Hello World",
                        Subtitle = "来自我的插件",
                        Action = () => context.ShowToast("你好！")
                    }
                }
            });
        }
        return Task.FromResult<QueryResult?>(null);
    }
}

最佳实践

异常处理

插件运行在主进程中，未捕获的异常可能导致整个应用程序崩溃。请务必在入口方法中使用 try-catch。

public override async Task<QueryResult?> QueryAsync(QueryContext context)
{
    try
    {
        return await DoWorkAsync(context);
    }
    catch (Exception ex)
    {
        Context.LogError($"查询出错: {ex.Message}", ex);
        return null;
    }
}

异步操作

始终使用 async/await 模式，避免使用 .Result 或 .Wait()，这会导致死锁。

资源清理

如果您订阅了事件或打开了非托管资源，请重写 Dispose 方法进行清理。

public override void Dispose()
{
    // 取消事件订阅
    _subscription?.Dispose();
    base.Dispose();
}

发布插件

1. 编译项目为 Release 模式。
2. 将生成的 .dll 文件及依赖复制到 Mj·Dock 的 plugins/MyPlugin 目录下。
3. 重启 Mj·Dock，即可在插件列表中看到您的作品。