Bumps version to v0.8.0

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<SocketMessage, Guid>` has been changed
+to `Cacheable<IMessage, Guid>`; `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<T>`.
+- `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<T>`.
+- `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<SocketMessage, Guid>` has been changed to `Cacheable<IMessage, Guid>` 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

Kook.Net.targets

@@ -6,7 +6,7 @@
     <IsPackable>false</IsPackable>
     <IsTrimmable>false</IsTrimmable>
     <IsAotCompatible>false</IsAotCompatible>
-    <VersionSuffix>beta4</VersionSuffix>
+<!--    <VersionSuffix>beta4</VersionSuffix>-->
     <LangVersion>latest</LangVersion>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>

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<SocketMessage, Guid>`
+变更为 `Cacheable<IMessage, Guid>`；`SectionAccessoryMode.Unspecified` 现已由 `null` 代替；`Format.StripMarkDown`
+被重命名为 `StripMarkdown`；`SendFileAsync` 中接收 `Steam` 类型的重载中的 `filename`
+参数现在为必选参数。请注意这些变更可能会导致编译错误，应根据实际情况进行修复。
+
+### 新增
+
+- `KookSocketConfig` 新增 `StartupCacheFetchMode`、`LargeNumberOfGuildsThreshold` 及 `SmallNumberOfGuildsThreshold`
+  配置项，用于自定义 Bot 的 Socket 客户端在启动时通过 API 获取缓存所需服务器基础数据的方式
+- `KookSocketConfig` 上新增两个配置项 `AutoUpdateRolePositions` 与 `AutoUpdateChannelPositions`，默认为 `false`
+  。当启用时，会在相关事件下发时自动通过 API 获取数据，以维护缓存中的角色排序信息与频道排序信息。
+- `Embed` 添加了 `CardEmbed`
+- 卡片实体与构造器现在实现了 `IEquatable<T>`
+- 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<T>`
+- `Quote.Empty` 及其公开构造函数已标记 `Obsolete` 特性，应使用 `MessageReference`
+- `fileName` 已重命名为 `filename`
+- `SendFileAsync` 中接收 `Steam` 类型的重载中的 `filename` 参数现在为必选参数
+- `BaseSocketClient._baseConfig` 重命名为 `BaseConfig`
+- 事件参数 `Cacheable<SocketMessage, Guid>` 变更为 `Cacheable<IMessage, Guid>`，以解决下载实体失败的问题
+- `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]
 
 ### 更新路线