From b73613e108743c80ed25f331c65245ae0e51cecc Mon Sep 17 00:00:00 2001 From: Gehongyan Date: Tue, 28 May 2024 21:24:44 +0800 Subject: [PATCH] Bumps version to v0.8.0 --- CHANGELOG.md | 95 +++++++++++++++++++++++++++++++++++++ Kook.Net.targets | 2 +- docs/changelog/changelog.md | 82 ++++++++++++++++++++++++++++++++ 3 files changed, 178 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 72ddf57b..96201c07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,101 @@ --- +## v0.8.0 [2024-05-28] + +### Update Roadmap + +Due to changes in the KOOK API, Bot users can no longer obtain all the necessary basic guild information at startup +through the `/guild/index` interface. Instead, it is now required to traverse each guild via the `/guild/view` +interface. This change can result in a significantly longer startup time and a large number of API requests for Bots +that have joined many guilds. Therefore, the current version introduces the `KookSocketConfig.StartupCacheFetchMode` +configuration item, which defines how the Bot loads the basic guild data needed at startup. + +- `Synchronous`: In synchronous mode, after obtaining a simple list of guilds at client startup, the client fetches the + basic data of each guild through the API before triggering the `Ready` event. +- `Asynchronous`: In asynchronous mode, after obtaining a simple list of guilds at client startup, the `Ready` event is + triggered immediately, and a background task is started to fetch all the basic guild data. +- `Lazy`: In lazy mode, after obtaining a simple list of guilds at client startup, the `Ready` event is triggered + immediately without proactively fetching the basic guild data. When events involving the guild are received from the + gateway, the guild's basic data will be fetched through the API if it has not already been obtained. +- `Auto`: In automatic mode, the default setting, the client's startup mode is automatically determined based on the + number of guilds the Bot has joined. If the number of guilds reaches `LargeNumberOfGuildsThreshold` (default is 50), + it will be `Lazy`; if it reaches `SmallNumberOfGuildsThreshold` (default is 5), it will be `Asynchronous`; otherwise, + it will be `Synchronous`. This determination is made each time the Bot connects to the WebSocket. + +When not using `Synchronous` mode, after the `Ready` event, accessing cached guild entities might result in entities +that do not fully contain basic guild data. The `IsAvailable` property indicates whether the guild entity has fully +cached basic data through the API. In such cases, please proactively call the `UpdateAsync` method to update the cached +guild entity through the API. The basic guild data mentioned above mainly includes the guild's channels, roles, +channel permission overrides, and the current user's nickname within guilds. + +The entire framework code has been updated to support nullable reference static analysis diagnostics. For the concept of +nullable reference types in C#, please refer to [Nullable reference types - C# | Microsoft Learn]. After updating to the +current version, all values that may be null will be marked as nullable types. This may cause some code to generate +warnings during compilation, which should be treated as potential null reference exceptions and fixed accordingly. + +Additionally, `IQuote` has a new implementation `MessageReference`, which only contains the ID of the message to be +referenced and is used when calling the API in user code. Existing user code that creates `Quote` should migrate +to `MessageReference` as soon as possible. + +`fileName` has been renamed to `filename`; the event parameter `Cacheable` has been changed +to `Cacheable`; `SectionAccessoryMode.Unspecified` is now replaced by `null`; `Format.StripMarkDown` has +been renamed to `StripMarkdown`; and the `filename` parameter in the `SendFileAsync` overload that accepts the `Stream` +type is now mandatory. Please note that these changes may cause compilation errors and should be fixed accordingly. + +### Additions + +- `KookSocketConfig` adds the `StartupCacheFetchMode`, `LargeNumberOfGuildsThreshold`, + and `SmallNumberOfGuildsThreshold` configuration items to customize how the Bot's Socket client fetches the basic + guild data needed at startup via the API. +- Two new configuration properties `AutoUpdateRolePositions` and `AutoUpdateChannelPositions` have been added + to `KookSocketConfig`, defaulting to `false`. When enabled, the client will automatically fetch data via the API upon + receiving related events to maintain the cached role and channel sorting information. +- `Embed` adds `CardEmbed`. +- Card entities and builders now implement `IEquatable`. +- `SocketSelfUser` now implements `IUpdateable`. +- Added `IGuild.RecommendInfo.Certifications`. +- `IQuote` has a new implementation `MessageReference`, which only contains the ID of the message to be referenced and + is used when calling the API in user code. +- Support for the event types `embeds_append`, `sort_channel`, `updated_server_type`, `batch_added_channel`, + `batch_updated_channel`, `batch_deleted_channel`, `live_status_changed`, `PERSON` typed `updated_guild`, + `add_guild_mute`, `delete_guild_mute`, `unread_count_changed` has been added, but it is not yet confirmed + whether these events will actually be dispatched. + +### Fixes + +- Fixed the issue where the author of private messages was incorrect. +- Fixed the issue where `SocketUserMessage.Quote.Author` could be null. +- Fixed the issue where Tags were missing corresponding values when referencing nonexistent entities in messages. +- Fixed the issue where the voice client failed to handle undefined events, causing stream crashes. +- Fixed the issue where parsing newly introduced mixed media messages failed. +- Corrected the behavior of updating user nicknames. + +### Changes + +- Enabled nullable reference types feature. For the concept of nullable reference types in C#, please refer + to [Nullable reference types - C# | Microsoft Learn]. +- Various validations for the card builder are now deferred to the `Build` call. +- The types of properties involving lists in cards have been changed to `IList`. +- `Quote.Empty` and its public constructor have been marked as `Obsolete`, and `MessageReference` should be used + instead. +- `fileName` has been renamed to `filename`. +- The `filename` parameter in the `SendFileAsync` overload that accepts the `Stream` type is now mandatory. +- `BaseSocketClient._baseConfig` has been renamed to `BaseConfig`. +- The event parameter `Cacheable` has been changed to `Cacheable` to address the + issue of entity download failure. +- `SectionAccessoryMode.Unspecified` has been removed; please use `null` instead. +- `Format.StripMarkDown` has been renamed to `StripMarkdown`, and the original method has been marked as `Obsolete`. +- `Format.StripMarkdown` now removes hyphens `-`. + +### Others + +- Added a reference to `PolySharp` on .NET 7 and earlier target frameworks to support the implementation of some new + features on older frameworks. +- Added integration tests for some Socket events. + +[Nullable reference types - C# | Microsoft Learn]: https://learn.microsoft.com/en-us/dotnet/csharp/nullable-references + ## v0.7.0 [2024-04-02] ### Update Roadmap diff --git a/Kook.Net.targets b/Kook.Net.targets index c8450161..20ac7fcf 100644 --- a/Kook.Net.targets +++ b/Kook.Net.targets @@ -6,7 +6,7 @@ false false false - beta4 + latest true snupkg diff --git a/docs/changelog/changelog.md b/docs/changelog/changelog.md index 3eb34ec7..922ef1e7 100644 --- a/docs/changelog/changelog.md +++ b/docs/changelog/changelog.md @@ -5,6 +5,88 @@ title: 变更日志 # 变更日志 +## v0.8.0 [2024-05-28] + +### 更新路线 + +由于 KOOK API 变更，Bot 用户现已无法在启动时通过 `/guild/index` +接口一次性获取全部所需的服务器基础信息，而是需要通过 `/guild/view` 接口遍历各个服务器，这会导致加入过多服务器的 Bot +会在启动时消耗过长时间，并大量发起 API 请求。因此，当前版本引入 `KookSocketConfig.StartupCacheFetchMode` 配置项，用于定义 +Bot 启动时加载服务器所需基础数据的方式。 + +- `Synchronous`：同步模式。客户端启动时获取到服务器的简单列表后，会先通过 API + 遍历获取所需服务器的基础数据，全部获取完成后再触发 `Ready` 事件。 +- `Asynchronous`：异步模式。客户端启动时在获取到服务器的简单列表后立即触发 `Ready` 事件，再在启动后台任务拉取所有服务器的基础数据。 +- `Lazy`：懒模式。客户端启动时在获取到服务器的简单列表后立即触发 `Ready` 事件，不主动拉取服务器基础数据，当网关下发涉及到服务器的事件时， + 会对未获取基础数据的服务器对象通过 API 获取信息。 +- `Auto`：自动模式，默认值。客户端的启动模式根据 Bot + 所加入的服务器数量自动判断，当服务器数量达到 `LargeNumberOfGuildsThreshold`（默认为 50）时为 `Lazy` + ，否则若达到 `SmallNumberOfGuildsThreshold`（默认为 5）时为 `Asynchronous`，否则为 `Synchronous`。该判断将在每次 Bot 连接 + WebSocket 时进行。 + +在未使用 `Synchronous` 模式时，在 `Ready` +事件之后，未经事件主动访问缓存的服务器实体时，可能会获取到未完整包含服务器基础数据的缓存实体，`IsAvailable` +属性指示该服务器实体是否已经通过 API 完整缓存基础数据。在这种情况下，请主动调用 `UpdateAsync` 方法来通过 API 更新缓存服务器实体。 +上述的服务器基础数据主要指服务器的频道、角色、频道权限覆盖、当前用户在服务器内的昵称等信息。 + +已针对整个框架的代码添加了空引用静态分析诊断的特性，有关可为空引用类型的 C# +概念，请参阅 [可为空引用类型 - C# | Microsoft Learn]。更新至当前版本后，所有可能为空的类型都会被标记为可为空引用类型， +这可能会导致一些代码在编译时产生警告，这些警告应该被视为潜在的空引用异常，应该根据实际情况进行修复。 + +另外，`IQuote` 新增了一个实现 `MessageReference`，这仅包含要被引用的消息 ID，用于在用户代码调用 API 时传入。原有创建 `Quote` +的用户代码应尽快迁移至 `MessageReference`。 + +`fileName` 已重命名为 `filename`；事件参数 `Cacheable` +变更为 `Cacheable`；`SectionAccessoryMode.Unspecified` 现已由 `null` 代替；`Format.StripMarkDown` +被重命名为 `StripMarkdown`；`SendFileAsync` 中接收 `Steam` 类型的重载中的 `filename` +参数现在为必选参数。请注意这些变更可能会导致编译错误，应根据实际情况进行修复。 + +### 新增 + +- `KookSocketConfig` 新增 `StartupCacheFetchMode`、`LargeNumberOfGuildsThreshold` 及 `SmallNumberOfGuildsThreshold` + 配置项，用于自定义 Bot 的 Socket 客户端在启动时通过 API 获取缓存所需服务器基础数据的方式 +- `KookSocketConfig` 上新增两个配置项 `AutoUpdateRolePositions` 与 `AutoUpdateChannelPositions`，默认为 `false` + 。当启用时，会在相关事件下发时自动通过 API 获取数据，以维护缓存中的角色排序信息与频道排序信息。 +- `Embed` 添加了 `CardEmbed` +- 卡片实体与构造器现在实现了 `IEquatable` +- SocketSelfUser 现在实现了 `IUpdateable` +- 添加了 `IGuild.RecommendInfo.Certifications` +- `IQuote` 新增新的实现 `MessageReference`，这仅包含要被引用的消息 ID，用于在用户代码调用 API 时传入 +- +添加了对事件类型 `embeds_append`、`sort_channel`、`updated_server_type`、`batch_added_channel`、`batch_updated_channel`、 +`batch_deleted_channel`、`live_status_changed`、`PERSON` 类型的 `updated_guild`、`add_guild_mute`、`delete_guild_mute`、 +`unread_count_changed` 的支持，但暂时无法确认这些事件是否会实际下发。 + +### 修复 + +- 修复私聊消息的作者不正确的问题 +- 修复 `SocketUserMessage.Quote.Author` 可能为空的问题 +- 修复消息中引用不存在的实体时，Tags 缺失对应值的问题 +- 修复语音客户端未能正确处理未定义事件导致推流崩溃的问题 +- 修复解析新引入的图文混排消息失败的问题 +- 修正用户昵称更新行为不正确的问题 + +### 变更 + +- 启用可为空引用类型特性，有关可为空引用类型的 C# 概念，请参阅 [可为空引用类型 - C# | Microsoft Learn] +- 卡片构造器的各种验证已推迟到调用 `Build` 时进行 +- 卡片内涉及到列表的属性的类型已变更为 `IList` +- `Quote.Empty` 及其公开构造函数已标记 `Obsolete` 特性，应使用 `MessageReference` +- `fileName` 已重命名为 `filename` +- `SendFileAsync` 中接收 `Steam` 类型的重载中的 `filename` 参数现在为必选参数 +- `BaseSocketClient._baseConfig` 重命名为 `BaseConfig` +- 事件参数 `Cacheable` 变更为 `Cacheable`，以解决下载实体失败的问题 +- `SectionAccessoryMode.Unspecified` 现已移除，请使用 `null` 代替 +- `Format.StripMarkDown` 被重命名为 `StripMarkdown`，原方法已标记 `Obsolete` +- Format.StripMarkdown 现在会移除连字符 `-` + +### 其它 + +- 在 .NET 7 及以前的目标框架上添加了对 `PolySharp` 的引用，以支持一些新特性在旧框架上的实现 +- 新增部分 Socket 事件的集成测试 + +[可为空引用类型 - C# | Microsoft Learn]: https://learn.microsoft.com/zh-cn/dotnet/csharp/nullable-references + ## v0.7.0 [2024-04-02] ### 更新路线