入门

AppID

通过在程序集上应用 AppIdAttribute 指定 AppID。同一个应用中，AppIdAttribute 必须是唯一的。

插件类

通过为可被实例化的类应用 PluginAttribute 特性指定插件类。在同一个应用中，可以指定多个插件类。插件类只会被实例化一次。

通常情况下，插件类应以 Plugin 类作为基类。

使用 PluginAttribute 特性的有参构造函数指定插件类的加载时机。

[Plugin((int)AppLifecycle.Initializing)]
class MyPlugin : Plugin
{
}

警告

不能直接将 AppLifecycle 枚举的值传入构造函数，否则将导致应用无法编译。

若在 Enabled 阶段加载，允许在构造函数内调用 API或长时间阻塞线程，并且可以显示引发的异常的详细信息。必须在 app.json 中向酷Q注册应用启用事件才能在 Enabled 阶段加载。

通过将加载阶段设置为 NotLoaded (0)，可以禁止插件类的加载。

若在 Initializing 及其他非 Enabled 阶段加载，应遵循以下原则：

✔ 在插件类构造函数内对类进行初始化。
✔ 在 AppEnabled 事件中初始化应用。
✘ 不应在插件类构造函数内调用酷Q API。
✘ 插件类构造函数不应长时间阻塞线程。
✘ 插件类构造函数不应抛出异常。

有关详细信息，请参见酷Q文库。

事件

酷Q事件都被封装为了 .NET 事件。当酷Q使用 StdCall 调用事件对应函数时，将会对事件数据进行封装并引发相应的事件。

✘ 不允许更改 app.json 中预定义的事件函数名。

部分酷Q事件被合并为一个或拆分为多个事件。若要获取详细信息，请参见事件。

事件源

事件源定义了一个或一组相关的事件。事件源是接口类型。定义了单个事件的事件源以 Notify 开头，如 INotifyGroupMessageReceived 接口。定义了多个事件的事件源以 EventSource 结尾，如 IBotEventSource 接口。

处理事件

在插件类构造函数中添加参数以获取事件源。通过向事件源对象附加事件处理程序来处理事件。

public MyPlugin(
    INotifyGroupMessageReceived notifyGroupMessageReceived,
    IBotEventSource botEventSource)
{
    notifyMessageReceived.MessageReceived += ...
    botEventSource.AppEnabled += ...
}

注意

尽可能使用定义事件最少的事件源。例如，若插件只需处理消息接收事件，则应使用 INotifyGroupMessageReceived，而不是 ICurrentUserEventSource。

路由

酷Q的所有事件数据类均派生自 RoutedEventArgs 类。将 Handled 属性设置为 true 以阻断事件。

菜单和悬浮窗状态

菜单项被点击和悬浮窗状态更新均被视为事件。由于事件的数量无法确定，需要手动导出事件处理程序。

有关详细信息，请参见菜单和悬浮窗状态。

调用酷Q API

通过事件数据。

private void OnMemberJoined(object sender, GroupEventArgs e)
{
    e.Operatee.Mute(TimeSpan.FromMinutes(5));
    e.Source.Send("欢迎 " + e.Operatee.DisplayName);
}

通过 PluginContext 类。对于 Current，建议使用 CurrentPluginContext 类。
```
PluginContext.Current.GetUser(114514).Send("Hello!");
```

通过 Plugin 类的 protected 实例方法。通常在插件类中使用此方法。

public class MyPlugin : Plugin
{
    ...
    foreach (var member in Group(1919810).GetMembers())
    ...
}

通过 CurrentPluginContext 类提供的静态方法。通常在非插件类中使用此方法。
```
using static HuajiTech.CoolQ.CurrentPluginContext;

User(114514).Send("Hello!");
```

通过 PluginContextExtensions 类提供的常用扩展方法。

try
{
    ...
    user.AsMemberOf(group);
    ...
}
catch (Exception ex)
{
    ex.LogAsError();
}

通过 Image 和 Record 类。
```
image.GetFile();
```

CQ码

可以使用 ComplexMessage 类处理CQ码。

有关详细信息，请参见如何：处理消息中的使用 ComplexMessage部分。

.NET Core

目前，HuajiTech.CoolQ 暂不支持在 .NET Core 上运行。有计划在未来的版本添加对 .NET Core 的支持。