2.9 KiB
Migrating from 0.9
1.0.0 is the biggest breaking change the library has gone through, due to massive changes in the design of the library.
A medium to advanced understanding is recommended when working with this library.
It is recommended to familiarize yourself with the entities in 1.0 before continuing. Feel free to look through the library's source directly, look through IntelliSense, or look through our hosted API Documentation.
Entities
Most API models function similarly to 0.9, however their names have been changed. You should also keep in mind that we now separate different types of Channels and Users.
Before proceeding, please read over @Terminology to understand the naming behind some objects.
Below is a table that compares most common 0.9 entities to their 1.0 counterparts.
This should be used mostly for migration purposes. Please take some time to consider whether or not you are using the right "tool for the job" when working with 1.0
| 0.9 | 1.0 | Notice |
|---|---|---|
| Server | @Discord.WebSocket.SocketGuild | |
| Channel | @Discord.WebSocket.SocketGuildChannel | Applies only to channels that are members of a Guild |
| Channel.IsPrivate | @Discord.WebSocket.SocketDMChannel | |
| ChannelType.Text | @Discord.WebSocket.SocketTextChannel | This applies only to Text Channels in Guilds |
| ChannelType.Voice | @Discord.WebSocket.SocketVoiceChannel | This applies only to Voice Channels in Guilds |
| User | @Discord.WebSocket.SocketGuildUser | This applies only to users belonging to a Guild* |
| Profile | @Discord.WebSocket.SocketGuildUser | |
| Message | @Discord.WebSocket.SocketUserMessage |
* To retrieve an @Discord.WebSocket.SocketGuildUser, you must retrieve the user from an @Discord.WebSocket.SocketGuild.
Event Registration
Prior to 1.0, events were registered using the standard c# Handler(EventArgs) pattern. In 1.0,
events are delegates, but are still registered the same.
For example, let's look at DiscordSocketClient.MessageReceived
To hook an event into MessageReceived, we now use the following code:
[!code-csharpEvent Registration]
All Event Handlers in 1.0 MUST return Task!
If your event handler is marked as async, it will automatically return Task. However,
if you do not need to execute asynchronus code, do not mark your handler as async, and instead,
stick a return Task.CompletedTask at the bottom.
[!code-csharpSync Event Registration]
Event handlers no longer require a sender. The only arguments your event handler needs to accept are the parameters used by the event. It is recommended to look at the event in IntelliSense or on the API docs before implementing it.
Async
Nearly everything in 1.0 is an async Task. You should always await any tasks you invoke.