discord-net/Discord.Net 2.0 on GitHub

This is a major release. Changes have been made to fix previous design errors, as well as add and remove functionality per the Discord API.

Note: This is a cumulative changelog including all pre-releases of v2.0.0. To view only the changes since v2.0.0-beta, please see CHANGELOG.md.

Thanks to the following for their contributions this release:

A special thanks 🎉 to @Still34 for taking the time over the past few months to completely rewrite our documentation, and ensure that every object and member in the library is documented.

Upgrade Path

Per #731, a correct implementation of IEmote must be used when accessing reaction users. For unicode emojis, you should use the Emoji class; for guild emotes, either parse the emote via Emote.Parse or fetch it from the guild.

IEmote emote = new Emoji("\U0001f603");
// or:
IEmote emote = Emote.Parse("<:fox_moose:381914721642872843>");

var reactions = await msg.GetReactionUsersAsync(emote);

Per #744, IAsyncEnumerable can be flattened into a single, non-paginated Async collection via IAsyncEnumerable#Flatten, or can be flattened into a single IEnumerable via FlattenAsync. All existing code should be moved from await coll.Flatten(); -> await coll.FlattenAsync();

Per #790, EmbedBuilder.AddInlineField has been removed. You should instead use AddField(inline: true)

Per #801, all EmbedBuilders must be built prior to use in a message. All existing code should append the build method: await ReplyAsync("", embed: embed.Build())

Per #804, the overridden signatures of your commands attributes will need to be refactored:

PreconditionAttribute#CheckPermissions -> PreconditionAttribute#CheckPermissionsAsync
TypeReader#Read -> TypeReader#ReadAsync

Per #829, you will need to ensure that you are in an ITextChannel when attempting to bulk delete or access the NSFW property:

if (channel is ITextChannel text)
{
    await text.DeleteMessagesAsync();
    var nsfw = text.Nsfw;
}

Per #874, you should replace all accesses to (Guild|Channel)Permission.ReadMessages with ViewChannel

Per #877, Games have been refactored and made more polymorphic.

IGuildUser#Game -> IGuildUser#Activity
StreamType -> ActivityType
StreamType.NotStreaming -> ActivityType.Playing
StreamType.Twitch -> ActivityType.Streaming
Activities only include the name of the game and the ActivityType.
Activities are a type of Game, StreamingGame, or RichGame - you may want to use a pattern match.

Per #955, the GameParty class now uses long instead of int. Update your domain objects accordingly, if you need to.

Per #958, user tokens are no longer supported. Discord disallows and discourages their usage, so we suggest you bring your selfbot-based projects to an end, or find another Discord library which still supports user token login.

Per #1033, references to ReadMessages should be changed to ViewChannel. This applies to the guild and channel permissions enums, as well as the permissions sets.

Per #1057, IAudioChannel#ConnectAsync was changed from one parameter to three parameters.

Per #1164, the CommandExecuted event has changed signature. You may need to update your event handlers.

Per #1171, all client types now implement IDisposable. You may need to update your own objects to match this change.

Per #1172, invite related methods were moved from IGuildChannel to INestedChannel. You may need to replace these channel accesses with casts to nested channels first.

Per #1196, CreateCategoryAsync now takes a properties function before the request options. If you were specifying request options without using a named parameter before, this will need to be updated.

Added

#747: CommandService now has a CommandExecuted event (e991715)
#765: Parameters may have a name specified via NameAttribute (9c81ab9)
#773: Both socket clients inherit from BaseSocketClient (9b7afec)
#785: Primitives now automatically load a NullableTypeReader (cb0ff78)
#819: Support for Welcome Message channels (30e867a)
#835: Emoji may now be managed from a bot (b4bf046)
#843: Webhooks may now be managed from a bot (7b2ddd0)
#863: An embed may be converted to an EmbedBuilder using the .ToEmbedBuilder() method (5218e6b)
#877: Support for reading rich presences (34b4e5a)
#888: Users may now opt-in to using a proxy (678a723)
#906: API Analyzers to assist users when writing their bot (f69ef2a)
#907: Full support for channel categories (030422f)
#913: Animated emoji may be read and written (a19ff18)
#915: Unused parameters may be discarded, rather than failing the command (5f46aef)
#929: Standard EqualityComparers for use in LINQ operations with the library's entities (b5e7548)
#934: Modules now contain an OnModuleBuilding method, which is invoked when the module is built (bb8ebc1)
#952: Added 'All' permission set for categories (6d58796)
#957: Ratelimit related objects now include request information (500f5f4)
#962: Add GetRecommendedShardCountAsync (fc5e70c)
#970: Add Spotify track support to user Activities (64b9cc7)
#973: Added GetDefaultAvatarUrl to user (109f663)
#978: Embeds can be attached alongside a file upload (e9f9b48)
#984, #1089: VoiceServerUpdate events are now publically accessible (e775853, 48fed06)
#996: Added DeleteMessageAsync to IMessageChannel (bc6009e)
#1005: Added dedicated TimeSpan TypeReader which "doesn't suck" (b52af7a)
#1009: Users can now specify the replacement behavior or default typereaders (6b7c6e9)
#1020: Users can now specify parameters when creating channels (bf5275e)
#1030: Added IsDeprecated, IsCustom properties to VoiceRegion (510f474)
#1037: Added SocketUser.MutualGuilds, various extension methods to commands (637d9fc)
#1043: Discord.Color is now compatible with System.Drawing.Color (c275e57)
#1055: Added audit logs (39dffe8)
#1056: Added GetBanAsync (97c8931)
#1102: Added GetJumpUrl() to messages (afc3a9d)
#1123: Commands can now accept named parameters (419c0a5)
#1124: Preconditions can now set custom error messages (5677f23)
#1126: Color now has equality (a2d8800)
#1159: Guild channels can now by synced with their parent category (5ea1fb3)
#1165: Bring Guild and Message models up to date with the API (d30d122)
#1166: Added GetVoiceRegionsAsync to IGuild (00717cf)
#1183: Added Add Guild Member endpoint for OAuth clients (8ef5f81)
#1196: Channel position can now be specified when creating a channel (a64ab60)
#1198: The Socket client can now access its underlying REST client (65afd37)
#1213: Added GuildEmote#CreatorId (92bf836)
'html' variant added to the EmbedType enum (42c879c)
Modules can now be nested in non-module classes (4edbd8d)
Added BanAsync to guild members (1905fde)
Added the permisison bit for priority speaker (c1d7818)
All result types can use FromError (748e92b)
Added support for reading/writing slow mode (97d17cf)
Added markdown format for URLs (f005af3)
Reactions can now be added to messages in bulk (5421df1)

Fixed

#742: DiscordShardedClient#GetGuildFor will now direct null guilds to Shard 0 (d5e9d6f)
#743: Various issues with permissions and inheritance of permissions (f996338)
#755: IRole.Mention will correctly tag the @everyone role (6b5a6e7)
#768: CreateGuildAsync will include the icon stream (865080a)
#866: Revised permissions constants and behavior (dec7cb2)
#872: Bulk message deletion should no longer fail for incomplete batch sizes (804d918)
#923: A null value should properly reset a user's nickname (227f61a)
#938: The reconnect handler should no longer deadlock during Discord outages (73ac9d7)
#941: Fix behavior of OverrideTypeReader (170a2e0)
#945: Fix properties on SocketCategoryChannel (810f6d6)
#959: Webhooks now use the correct parameter when assigning to the Avatar URL (8876597)
#966: Correct the implementation of HasFlag and ResolveChannel in permissions (32ebdd5)
#968: Add missing parameter in WebSocket4Net constructor (8537924)
#981: Enforce a maximum value when parsing timestamps from Discord (bfaa6fc)
#993: Null content will no longer null-ref on message sends/edits (55299ff)
#1003: Fixed ordering of parameters in permissions classes (a06e212)
#1010: EmbedBuilder no longer produces mutable embeds (2988b38)
#1012: Embed.Length should now yield the correct results (a3ce80c)
#1017: GetReactionUsersAsync includes query parameters (9b29c00)
#1022: GetReactionUsersAsync is now correctly paginated (79811d0)
#1023: Fix/update invite-related behaviors (7022149)
#1031: Messages with no guild-specific data should no longer be lost (3631886)
#1036: Fixed cases where RetryMode.RetryRatelimit were ignored (c618cb3)
#1044: Populate the guild in SocketWebhookUser (6a7810b)
#1048: The REST client will now create a full GuildUser object (033d312)
#1049: Fixed null-ref in GetShardIdFor (7cfed7f)
#1059: Include 'view channel' in voice channel's All permissions set (e764daf)
#1083: Default type readers will now be properly replaced (4bc06a0)
#1093: Fixed race condition in audio client authentication (322d46e)
#1139: Fixed consistency in exceptions (9e9a11d)
#1151: GetReactionUsersAsync now uses the correct pagination constant (c898325)
#1163: Reaction ratelimits are now placed in the same bucket, treated correctly (5ea1fb3)
#1186: Webhooks can now send files with embeds correctly (c1d5152)
#1192: CommandExecuted no longer fires twice for RuntimeResults (10233f3)
#1195: Channel Create audit log events properly deserialize (dca6c33)
#1202: The UDP client should no longer be used after disposed (ccb16e4)
#1203: The Audio client should no longer lock up on disconnect (2c93363)
#1209: MessageUpdated should no longer pass a null after object (91e0f03)
Ignore messages with no ID in bulk delete (676be40)
No longer attempt to load generic types as modules (b1eaa44)
No longer complain when a PRESENCES_REPLACE update is received (beb3d46)
CommandExecuted will be raised on async exception failures (6260749)
ExecuteResult now contains the entire exception, not an abridged message (f549da5)
CommandExecuted will no longer be raised twice for exceptions (aec7105)
The default WebSocket will now close correctly (ac389f5)

Changed

#731: IUserMessage#GetReactionUsersAsync now takes an IEmote instead of a string (5d7f2fc)
#744: IAsyncEnumerable has been redesigned (5bbd9bb)
#777: IGuild#DefaultChannel will now resolve the first accessible channel, per changes to Discord (1ffcd4b)
#781: Attempting to add or remove a member's EveryoneRole will throw (506a6c9)
#801: EmbedBuilder will no longer implicitly convert to Embed, you must build manually (94f7dd2)
#804: Command-related tasks will have the 'async' suffix (14fbe40)
#812: The WebSocket4Net provider has been bumped to version 0.15, allowing support for .NET Standard apps (e25054b)
#829: DeleteMessagesAsync moved from IMessageChannel to ITextChannel (e00f17f)
#853: WebSocket will now use zlib-stream compression (759db34)
#874: The ReadMessages permission is moving to ViewChannel (edfbd05)
#877: Refactored Games into Activities (34b4e5a)
#943: Multiple types of quotation marks can now be parsed (thanks 🍎) (cee71ef)
#955: The GameParty model will now use long values (178ea8d)
#986: Expose the internal entity TypeReaders (660fec0)
#992: Throw an exception when trying to modify someone else's message (d50fc3b)
#998: Commands can specify their own IgnoreExtraArgs behavior (6d30100)
#1033: The ReadMessages permission bit is now named ViewChannel (5f084ad)
#1042: Content parameter of SendMessageAsync is now optional (0ba8b06)
#1057: An audio channel's ConnectAsync now allows users to handle the voice connection elsewhere, such as in Lavalink (890904f)
#1094: Overhauled invites, added vanity invite support (ffe994a)
#1108: Reactions now use the undocumented 1/.25 ratelimit, making them 4x faster (6b21b11)
#1128: Bot tokens will now be validated for common mishaps before use (2de6cef)
#1140: Check the invite maxAge parameter before making the request (649a779)
#1164: All command results will now be raised in CommandExecuted (10f67a8)
#1171: Clients have been changed to properly make use of IDisposable (7366cd4)
#1172: Invite related methods were moved from IGuildChannel to INestedChannel (a3f5e0b)
#1200: HasPrefix extensions now check for null values first (46e2674)
IGuildChannel#Nsfw moved to ITextChannel, now maps to the API property (608bc35)
Preemptive ratelimits are now logged under verbose, rather than warning. (3c1e766)
The default InviteAge when creating Invites is now 24 hours (9979a02)
All parameters to ReplyAsync have been made optional (b38dca7)
The socket client will now use additional fields to fill in member/guild information on messages (8fb2c71)
The Audio Client now uses Voice WS v3 (9ba38d7)

Removed

#790: Redundant overloads for AddField removed from EmbedBuilder (479361b)
#925: RPC is no longer being maintained nor packaged (b30af57)
#958: Remove support for user tokens (2fd4f56)
User logins (including selfbots) are no longer supported (fc5adca)

Misc

#786: Unit tests for the Color structure (22b969c)
#828: We now include a contributing guide (cd82a0f)
#876: We now include a standard editorconfig (5c8c784)
#963: Docs now include a release version, build instructions (88e6244)
#964: Fix documentation spelling of 'echoes' (fda19b5)
#967: Unit test permissions (63e6704)
#968: Bumped version of WebSocket4Net to 0.15.2 (8537924)
#972: Include sample bots in the source repository (217ec34)
#1046: We now support .NET Standard 2.0 (bbbac85)
#1114: Various performance optimizations (82cfdff)
#1149: The CI will now test on Ubuntu as well as Windows (674a0fc)
#1161: The entire documentation has been rewritten, all core entities were docstringed (ff0fea9)
#1175: Documentation changes in command samples (fb8dbca)
#1177: Added documentation for sharded bots (00097d3)
#1219: The project now has a logo! 🎉 (5750c3e)
This project is now licensed to the Discord.Net contributors (710e182)
Added templates for pull requests (f2ddf51)
Fixed documentation layout for the logo (bafdce4)

Another thanks to all of the users who helped maintain and update the documentation.

discord-net/Discord.Net 2.0 v2.0.0 on GitHub