V3 Final merge (#1966)
* Update azure-pipelines.yml * Update deploy.yml * Remove version tag from proj * Update deploy.yml * Removed versions from project files * Removed style of the nuget badge and added logo (#201) The style was not properly added to it and the plastic version does not look good with the discord badge. I thought it would look better with a logo * Fix Type not being set in SocketApplicationCommand * Remove useless GuildId property * meta: update XML * Add Autocomplete to SlashCommandOptionBuilder * Added autocomplete in SlashCommandOptionBuilder. (#206) Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> * Fix duplicate autocomplete * Fix #208 * Fix sub commands being interpreted as a parameter for autocomplete * Fix exposed optional * Support the discord:// protocol in buttons (#207) * Update UrlValidation.cs * Update ComponentBuilder.cs * Add docs and better error messages. * Fix wonky intentation * Add competing activity status type (#205) * Update GuildPermissionsTests.cs * Update GuildPermissions.cs * Add competing status type * Add Icons to IRole (#204) * Added icon field to IRole * Added GetGuildRoleIconUrl() * Added Clean Content Function (#174) * Added Clean Content Function * Fixed Spelling problems and bad var handling * Add StripMarkDown Method * Clean Content Expanded (#212) * Implement CleanContent In IMessage & RestMessage * Update Spelling and Documentation * Add SanatizeMessage to MessageHelper and Refactor Rest and Socket Message * Add event for autocomplete interaction (#214) * Spelling corrections (#215) * Remove null collections * Followup with file async warnings (#216) * Changed from NotNullOrWhitespace to NotNullOrEmpty * Added NotNullOrEmpty on filename * Added system to interpret from the path * Added a check for if it contains a period * It has been done, how ever it will break stuff * Changed to use ??= how ever still added error check * Added space under check * Changed from with a period to valid file extension * Added checks for SendFileAsync * Removed filename != null && * Add channel types in application command options. (#217) * add channel types in application command options * Indent Docs * Stage instance audit logs as well as thread audit log type * Update azure-pipelines.yml * Update azure-pipelines.yml * Fix system messages not including mentioned users. Added ContextMenuCommand message type * Remove file extension check (#218) * Fix NRE in modify guild channel * Fix 429's not being accounted for in ratelimit updates * meta: add net5 framework Co-Authored-By: MrCakeSlayer <13650699+MrCakeSlayer@users.noreply.github.com> * Proper doc logos (#221) * Update GuildPermissionsTests.cs * Update GuildPermissions.cs * Add competing activity status type * logo changes * logo text as path * add missing logo * Update package logo and favicon * Update docfx references * Remove Console.WriteLine * Rename Available to IsAvailable in stickers * Rename Default and Required to IsDefault and IsRequired in IApplicationCommandOption. Rename DefaultPermission to IsDefaultPermission in IApplicationCommand * Fix different rest channels not deserializing properly * Refactor summaries and boolean property names * General cleanup (#223) * General cleanup * Add Async suffix to SendAutocompleteResult * Fix more formatting * Fix unused RequestOptions in GetActiveThreadsAsync * Add message to ArgumentNullException * Ephemeral attachments * Add missing jsonproperty attribute * Add IMessage.Interaction * Update attachment checks for embed urls * meta: bump version * Remove old package configs and update image * Update package logos * Fix logo reference for azure * Deprecate old package definitions in favor for target file * Deprecate old package definitions in favor for target file Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Update package ids * Fix url validation * meta: bump version * Fix assignment of UserMentions (#233) * Fix CleanContent (#231) * Fix SocketSlashCommandData access modifier. (#237) Fixes #229 * Update README with better header (#232) * Update README with better header Adds HTML elements that implement the main logo & improve the redirection tag positions. * Resolving border issue in light-mode * Update sponsor section * Implement checks for interaction respond times and multiple interaction responses. closes #236, #235 * Add response check to socket auto complete * meta: bump versions * Fix #239 * meta: bump version * meta: update logo * meta: bump versions * Revert received at time, confirmed by discord staff to be accurate * Update docs * Update CHANGELOG.md * meta: docs building * Update docs.yml * Update docs.yml * Fix docfx version * Update docs.yml * Update docs.bat * Rename docs repo for clone * update docfx version * Update docs.bat * Update docfx version * Remove docs from pipeline * FAQ revamped, metadata updated (#241) * FAQ revamped, metadata updated * Update FAQ.md * Update README.md * Docs index improvement * Fix InvalidOperationException in modify channel * feature: guild avatars, closes #238 * feature: modify role icons * meta: changelog * meta: bump version * Update README.md * Fix non value type options not being included in autocomplete * Add new activity flags (#254) * Add new activity flags * Add missing commas * Added support for GUILD_JOIN_REQUEST_DELETE event (#253) Fixes #247 * Adding BotHTTPInteraction user flag (#252) * animated guild banner support (#255) * Docs work (WIP) (#242) * Main page work * Metadata logo dir * More main page edits * Naming change * Dnet guide entries pruned * Add student hub guild directory channel (#256) * animated guild banner support * Add guild directory channel * Fix followup with file overwrite having incorrect parameter locations * Update GUILD_JOIN_REQUEST_DELETE event * Update head.tmpl.partial * Removed BannerId and AccentColor (#260) * Removed BannerId property, GetBannerURL method, and AccentColor property from IUser and socket entities. * Fixed errors in IUser.cs * Added back summary for GetAvatarUrl method in IUser.cs * Support Guild Boost Progress Bars (#262) * Support Guild Boost Progress Bars * Update SocketChannel.cs * Fix non-optional and unnecessary values. * Spelling * Reordering and consistency. * Remove log for reconnect * Add missing flags to SystemChannelMessageDeny (#267) * Rename new activity flags * Guild feature revamp and smart gateway intent checks * Get thread user implementation * Amend creating slash command guide (#269) * Adding BotHTTPInteraction user flag * Added comments explaining the Global command create stipulations. * Fix numeric type check for options * Add state checking to ConnectionManager.StartAsync (#272) * initial interface changes * Multi file upload + attachment editing * meta: bump versions * Update CHANGELOG.md * Update CHANGELOG.md * Support Min and Max values on ApplicationCommandOptions (#273) * Support Min and Max values on ApplicationCommandOptions * Support decimal min/max values * Docs imrpovments + use ToNullable * Logomark, doc settings edit (#258) * Logomark, doc settings edit * Replace standard logo * Bumping docfx plugins to latest release * Bump version metadata * Logo svg fix * Change default sticker behavior and add AlwaysResolveSticker to the config * Implement rest based interactions. Added ED25519 checks. Updated summaries. * Update package logo * Automatically fix ordering of optional command options (#276) * auto fix optional command option order * clean up indentation * Fix maximum number of Select Menu Options (#282) As of https://discord.com/developers/docs/interactions/message-components#select-menu-object-select-menu-structure the maximum number of options is 25, not less than 25. Hopefully the change catches all necessary locations * Add voice region to modify voice channels * Update summaries on rest interactions * Interaction Specific Interfaces (#283) * added interaction specific interfaces * fix build error * implement change requests * Update application * Add Guild Scheduled Events (#279) * guild events initial * sharded events * Add new gateway intents and fix bugs * More work on new changes to guild events * Update guild scheduled events * Added events to extended guild and add event start event * Update preconditions * Implement breaking changes guild guild events. Add guild event permissions * Update tests and change privacy level requirements * Update summaries and add docs for guild events * meta: bump version * Increment meta version (#285) * Increment meta version * Update docfx.json * Fix #289 and add configureawaits to rest based interactions * meta: bump version * Add GUILD_SCHEDULED_EVENT_USER_ADD and GUILD_SCHEDULED_EVENT_USER_REMOVE (#287) * Remove newline * Fix autocomplete result value * meta: bump versions * Add `GuildScheduledEventUserAdd` and `GuildScheduledEventUserRemove` to sharded client * Make RestUserCommand public (#292) * Fix Components not showing on FUWF (#288) (#293) Adds Components to Payload JSON Generation * Implement smarter rest resolvable interaction data. Fixes #294 * Add UseInteractionSnowflakeDate to config #286 * Implement Better Discord Errors (#291) * Initial error parsing * Implement better errors * Add missing error codes * Add voice disconnect opcodes * Remove unused class, add summaries to discordjsonerror, and remove public constructor of slash command properties * Add error code summary * Update error message summary * Update src/Discord.Net.Core/DiscordJsonError.cs Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Update src/Discord.Net.WebSocket/API/Voice/VoiceCloseCode.cs Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Fix autocomplete result value Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Change the minimum length of slash commands to 1 (#284) * Change the minimum length of slash commands to 1. This is the correct value according to the docs and it has been changed after user feedback. * Fix the limit in 3 other places Co-authored-by: quin lynch <lynchquin@gmail.com> * Add new thread creation properties * Add role emoji. Fixes #295 * Fix mocked text channel * Fix precondition checks. Closes #281 * Initial fix (#297) * meta: bump version * Update property names and summaries * Add Audit Log Data classes for Threads (#301) * Add ThreadDeleteAuditLogData * Add ThreadCreateAuditLogData * Fix ThreadCreateAuditLogData using old instead of new value * Create ThreadInfo Class * Fix Thread not being a property * Add ThreadUpdateAuditLogData * Cleanup usings * Add RateLimit to ThreadAuditLogData classese Co-authored-by: Playwo <eliaswolf2001@t-online.de> * Fix #300 * Interaction Command Service (#52) * init * attribute rename * added docs * Revert "added docs" This reverts commit 30aa0c4ef7e190a726ec2cb3a183da5e2f9b07d9. * added basic docs * Switched to nested modules for method grouping, changed command traversal method * interface now declares the helper methods * added new method with predicate parameter * added config option for deleting the "thinking" state of unhandled commands * Slash Module Base now exposes helper methods for interacting with the underlying Interaction * Revert "interface now declares the helper methods" This reverts commit 541b0be93530e880c482962d41cd6e0cefa4e771. * IDiscordInteraction now declares the helper methods * new cancelable wait interaction method * added support for user created command types * added option type 'number', added write method to typereaders * added enum and timespan typereaders * revert * added interface method declarations * inline docs * revert interface changes * current user id assignment in sharded client * added wildcards to interactions, tweaks * tweaks on interaction wild card pattern * Pre-app menu * fixed CurrentUserId and added application command events * made event listener persistent * Sharded Client Application Command Events and CurrentUserId Issue (#105) * added interface method declarations * inline docs * current user id assignment in sharded client * fixed CurrentUserId and added application command events * made event listener persistent * removed option type converter, task offloaded to typereaders * added "deleteOGResponse" method to module base * Upstream fetch for Discord-Net-Labs/release/3.x * solved merge conflicts * removed merge artifacts * added new Context Command attributes * added Conxtext Command info classes and changed the naming scheme for the existing classes * added IgnoreGroupNames prop to command attributes * added ContextCommand builder * moved command builders to internal * added ContextCommand methods to the command service * command service now uses InteractionHelper to register commands * bug fixes and refactorings * docs update * added inline docs to public members * added inline docs * added method name property to command infos * added inline docs * changed the execution callback to a declared delegate * createInstance delegate is now created only once per module * declared the ExecuteCallback delegate * introduced a way to modify the command permissions * changed method names * added optional compiled lambda module builder * added the missing sync execution option * moved run mode selection to the base class * info class refactorings * switched to compiled lambda based method invoke * command refactorings * added docs * removed untended class * bug fixes * minor refactorings * reflection changes * bug fix for interaction parameters * commands and modules now groups the preconditons on building * added default permission to context commands * added DontAutoRegister attribute * renamed TypeReader to TypeConverter * added docs to TypeConverterResult, made ISlashModuleBase public * namespace and project change * added inline docs file * renamed ExecuteComponentCommand method * added scoped service support to the dependency injection model * fixed premature disposal of scoped services * extended the scope to cover the precondition checking methods * removed slash command related preconditions from core lib * added sample application * precondition checks are now executed according to the command RunMode * reverting the conflicting changes * reverted SocketInteraction * reverting more conflicts * added indentations to inline docs * implemented change requests * updated the sample app * moved builders to public * added indentations to typeconverter docs * renamed old componentCommandExecuted event * bug fix for generic typeconverters * Revert "bug fix for generic typeconverters" This reverts commit fcc61957deb5dfc17c41367f1c7c72d27024b0ee. * bug fix for context commands * code cleanup * removed public module build method * modev OnModuleBuilding execution inside the module build method * added try-catch blocks encapsulating arg generation * fixed parameter preconditions not raising commandExecuted event * removed OnModuleBuilding execution from ModuleClassBuilder * removed setters from Precondition ErrorMessages * added methods to interaction service for creating user defined modules * added IParameterInfo parameter to TypeConverter.Write * changed the target frameworks * DefaultValueConverter bug fix * GenerateArgs refactorings * WaitForMessageComponent now relies message id * added ChannelTypes support * added ChannelTypes support * fix build error for new lib version * added ToString method to CommandInfo * added ToString method to CommandInfo * Fix index out of bounds error for new non-null slash command option collection * enum converter rework * added user extendable types to command context and module base * added regex anchors to ensure pattern matches the whole string * incomplete guides * add missing ignoreGroupNames assignment for ComponentInteraction * typeconverters now seperate pascal casing parameter names * fix missing IServiceScopefactory ? * Revert "typeconverters now seperate pascal casing parameter names" This reverts commit 141300f3d2c244fc6795999d910462939d16a2e1. * moved the option name pascal casing seperator to RestUtils * fix component command arg generation * removed , from default command delimiters * updated the regex to match every non whitespace value * added Autocomplete interaction support and updated the regex to match every non whitespace value * replaced the posix class with range exps in pascal casing seperator * added inline docs to autocompleter related classes * added regex metacharacter escape to wildcard patterns * added null check to Regex EscapeExcluding * added .net5.0 support and updated the project package * added .net5.0 support and updated the project package * add dependency injection to autocompleters * add net6.0 * bump versions * bug fix: pascal casing parameters are not assigned * rework autocomplete commands to accept command and parameter names seperatly * rename *InteractionCommandContext to *InteractionContext * add max-min value support to number type slash command options * add hide attribute to deafult enum converter * add inline docs * guides update: min/max value and autocomplete interactions * remove net6.0 support * add inline doc to Config.EnableAutocompleters * add autocompleters guide * added attribute usage to min/max value * implement rest based interactions * add handling logic for rest based interactions * update default TypeConverters to accommodate rest based interactions * added interaction specific interfaces * fix build error * implement change requests * bump metapackage version * replace concrete interface types with interfaces in command execution logic * fix min/max value attribute target * add rest specific interaction module for creating interaction responses for rest based interactions within the module * update rest callback to accept an interaction context parameter * clean up RestResponseCallback implementation artifacts * fix command registration bug when using the sharded socket client * update docs * fix build errors * fix slash command depth check * implement requested changes * fix build error * the grand finale * the grand finale Co-authored-by: quin lynch <lynchquin@gmail.com> * Remove XML doc * Add Interactions service to azure build * Add DocFX refs to interaction framework docs * meta: bump docfx version * meta: bump versions * Remove versioning metadata in csproj * Fix user command mismatch in docs * Fix parameter in message commands * Fix SocketVoiceChannel options are created as generic mentionables in Interaction service (#308) * added interaction specific interfaces * fix build error * implement change requests * add autocomplete respond method to IAutocompleteInteraction * fix sharded client current user * fix generic typeconverter picking priority * Revert "fix sharded client current user" This reverts commit a9c15ffd6ab02651e83e72c275889502b60cfddc. * Revert "add autocomplete respond method to IAutocompleteInteraction" This reverts commit f2fc50f1f19a0b41144b6dc93080d2f3a01282fc. * meta: bump version * Improve the `GuildFeatures` converter (#311) * Fix Message/User commands are not being executed when their name have spaces on it (#310) * added interaction specific interfaces * fix build error * implement change requests * add autocomplete respond method to IAutocompleteInteraction * fix sharded client current user * fix generic typeconverter picking priority * Revert "fix sharded client current user" This reverts commit a9c15ffd6ab02651e83e72c275889502b60cfddc. * Revert "add autocomplete respond method to IAutocompleteInteraction" This reverts commit f2fc50f1f19a0b41144b6dc93080d2f3a01282fc. * fix command parsing for names with spaces * meta: bump version * fix minor spelling mistake * add missing $ on docs Co-Authored-By: Liege72 <65319395+Liege72@users.noreply.github.com> * Squashed commit of the following: commit ff0bbbd4d3c4141a6e7eedbe2da0a2cbf5a8a208 Merge: 41b4686b19a66bf8Author: quin lynch <lynchquin@gmail.com> Date: Sat Nov 27 08:39:35 2021 -0400 Merge branch 'dev' of https://github.com/discord-net/Discord.Net into dev commit19a66bf878Author: Daniel Baynton <49287178+230Daniel@users.noreply.github.com> Date: Fri Nov 26 15:41:55 2021 +0000 feature: Add method to clear guild user cache (#1767) * Add method to clear a SocketGuild's user cache * Add optional predicate * Compress overload to be consistant * Fix global user not clearing (may cause other issues) * Remove debug code and add param documentation * Standardise doc string * Remove old hack-fix * Rename new method for consistency * Add missing line to reset downloaderPromise * Undo accidental whitespace changes * Rider better actually keep the tab this time Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> commitb9274d115dAuthor: Monica S <FiniteReality@users.noreply.github.com> Date: Fri Nov 26 15:41:08 2021 +0000 Add characters commonly use in links to Sanitize (#1152) Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> commit51e06e9ce1Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Fri Nov 26 11:30:19 2021 -0400 feature: warn on invalid gateway intents (#1948) commit82276e351aAuthor: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Fri Nov 26 11:29:53 2021 -0400 feature: default application games (#1949) * Initial implementation * Add missing summary commit4f1fe2b084Merge:9d6dc6273cd9f399Author: quin lynch <lynchquin@gmail.com> Date: Fri Nov 26 11:23:32 2021 -0400 Merge branch 'siscodeorg-commands/validate-get-best-match' into dev commit3cd9f39918Merge:9d6dc627adf3a9c4Author: quin lynch <lynchquin@gmail.com> Date: Fri Nov 26 11:23:05 2021 -0400 Merge branch 'commands/validate-get-best-match' of https://github.com/siscodeorg/Discord.Net into siscodeorg-commands/validate-get-best-match commitadf3a9c459Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Fri Nov 26 09:26:53 2021 -0300 Fix incorrect casing on `HandleCommandPipeline` commita92ec56d88Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Thu Nov 25 16:42:18 2021 -0300 Add requested changes Changes: - Use IResult instead of Optional CommandMatch - Rework branching workflow commitd1b31c8f52Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Thu Nov 25 15:31:48 2021 -0300 Add `MatchResult` commit9d6dc6279dAuthor: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Thu Nov 25 11:25:19 2021 -0400 Update socket presence and add new presence event (#1945) commit10afd96e6eAuthor: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Thu Nov 25 11:24:44 2021 -0400 feature: Handle bidirectional usernames (#1943) * Initial implementation * Update summary commit143ca6db43Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Thu Nov 25 11:23:33 2021 -0400 fix NRE when adding parameters thru builders (#1946) commitd5f5ae132cAuthor: Cenk Ergen <57065323+Cenngo@users.noreply.github.com> Date: Thu Nov 25 18:22:50 2021 +0300 fix sharded client current user (#1947) commitb5c150dc16Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Wed Nov 24 12:53:39 2021 -0400 Add Voice binaries (#1944) * Add binaries and read me * Update sending voice docs * Undo markdown formatting commitbc440abd44Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Wed Nov 24 12:52:55 2021 -0400 Implement multi-file upload to webhooks (#1942) commitf7a07aec02Author: Paulo <pnmanjos@hotmail.com> Date: Wed Nov 24 09:57:06 2021 -0300 Add default nullable enum typereader (#1518) commit6abdfcbf87Author: Slate <kristian.f@hotmail.co.uk> Date: Wed Nov 24 12:55:07 2021 +0000 Added negative TimeSpan handling (#1666) - Added unit tests for the TimeSpanTypeReader - Fixes https://github.com/discord-net/Discord.Net/issues/1657 commite0dbe7c695Author: Paulo <pnmanjos@hotmail.com> Date: Wed Nov 24 09:43:57 2021 -0300 Add MaxBitrate to the interface (#1861) Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> commit3cb662ff7aAuthor: d4n <dan3436@hotmail.com> Date: Tue Nov 23 10:49:31 2021 -0500 Add null check to AllowedMentions.ToModel() (#1865) commit900c1f4385Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Tue Nov 23 11:46:18 2021 -0400 Fix emoto try parse (#1941) commit933ea42eaaAuthor: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Tue Nov 23 09:58:05 2021 -0400 Merge Labs 3.X into dev (#1923) * meta: bump version * Null or empty fix (#176) * Add components and stickers to ReplyAsync extension * Fixed null or empty * Changed Label to Description * -||- Co-authored-by: quin lynch <lynchquin@gmail.com> * More regions (#177) * Preconditions * ChannelHelper * RestDMChannel * RestGroupChannel * RestBan * RestGroupUser * EntityExtensions * DiscordSocketClient * DiscordSocketClient * Discord.net.core.xml fix (#178) * Changed Label to Description * Added Discord- .MessageComponent .ISticker[] ,Discord.MessageComponent,Discord.ISticker[] to ReplyAsync * Remove references to labs * Update Discord.Net.sln * Added SendMessagesInThreads and StartEmbeddedActivities. (#175) * Added SendMessagesInThreads and StartEmbeddedActivities. Adjusted owner perms. Change UsePublicThreads -> CreatePublicThreads Change UsePrivateThreads -> CreatePrivateThreads * removed extra /// * Added UsePublicThreads and UsePrivateThreads back with Obsolete Attribute * removed 'false' from Obsolete Attribute * Squashed commit of the following: commit dca41a348e36a9b4e7006ef3a76377eb32aad276 Author: quin lynch <lynchquin@gmail.com> Date: Thu Sep 23 07:02:19 2021 -0300 Autocomplete commands * meta: xml. closes #171 * Revert user agent and $device to dnet * meta: bump version * meta: bump vers * Fix sticker args * Grammer fix (#179) * Made IVoiceChannel mentionable * Embeds array for send message async (#181) * meta: bump version * meta: bump vers * Fix sticker args * Grammer fix (#179) * Added embeds for SendMessageAsync * [JsonProperty("embed")] forgot to remove this public Optional<Embed> Embed { get; set; } * It has been done as requested. * Changed the old way of handeling single embeds * Moved embeds param and added options param * xmls Co-authored-by: quin lynch <lynchquin@gmail.com> * Fix thread permissions (#183) * Update GuildPermissionsTests.cs * Update GuildPermissions.cs * Use compound assignment (#186) * Used compound assignment * -||- * -||- * Remove unnecessary suppression (#188) * Inlined variable declarations (#185) * Fixed some warnings (#184) * Fixed some warnings * Another fixed warning * Changed the SSendFileAsync to SendFileAsync * Removed para AlwaysAcknowledgeInteractions * Moved it back to the previous version * Added periods to the end like quin requested!! :(( Co-authored-by: MrCakeSlayer <13650699+MrCakeSlayer@users.noreply.github.com> * Object initialization can be simplified fixed (#189) * Conditional-expression-simplification (#193) * Capitlazation fixes (#192) * Removed-this. (#191) * Use 'switch' expression (#187) * Use 'switch' expression * Reverted it to the old switch case * Fixed-compiler-error (#194) * Submitting updates to include new permissions. (#195) * Submitting updates to include new permissions. * Make old permissions obsolete and update tests Co-authored-by: quin lynch <lynchquin@gmail.com> * Update azure-pipelines.yml * Update azure-pipelines.yml * Update azure-pipelines.yml * Add support for long in autocomplete option * Add support for sending files with multiple embeds (#196) * Add support for sending files with multiple embeds * Simplify prepending single embed to embed array * Consistency for embeds endpoints (#197) * Changed the way of handling prepending of embeds. For consistency. * reformatted the summary * Revert pipeline * Fix duplicate merge conflicts * Changed minimum slash command name length to 1 per Discord API docs (#198) * Channel endpoints requirements correction (#199) * Added some requirements to channels for topic * Changed check from NotNullOrEmpty to NotNullOrEmpty * Added some requirements to channels for name Preconditions.LessThan * Formatting of file * Added restriction for description not being null (#200) * Update azure-pipelines.yml * Update deploy.yml * Remove version tag from proj * Update deploy.yml * Removed versions from project files * Removed style of the nuget badge and added logo (#201) The style was not properly added to it and the plastic version does not look good with the discord badge. I thought it would look better with a logo * Fix Type not being set in SocketApplicationCommand * Remove useless GuildId property * meta: update XML * Add Autocomplete to SlashCommandOptionBuilder * Added autocomplete in SlashCommandOptionBuilder. (#206) Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> * Fix duplicate autocomplete * Fix #208 * Fix sub commands being interpreted as a parameter for autocomplete * Fix exposed optional * Support the discord:// protocol in buttons (#207) * Update UrlValidation.cs * Update ComponentBuilder.cs * Add docs and better error messages. * Fix wonky intentation * Add competing activity status type (#205) * Update GuildPermissionsTests.cs * Update GuildPermissions.cs * Add competing status type * Add Icons to IRole (#204) * Added icon field to IRole * Added GetGuildRoleIconUrl() * Added Clean Content Function (#174) * Added Clean Content Function * Fixed Spelling problems and bad var handling * Add StripMarkDown Method * Clean Content Expanded (#212) * Implement CleanContent In IMessage & RestMessage * Update Spelling and Documentation * Add SanatizeMessage to MessageHelper and Refactor Rest and Socket Message * Add event for autocomplete interaction (#214) * Spelling corrections (#215) * Remove null collections * Followup with file async warnings (#216) * Changed from NotNullOrWhitespace to NotNullOrEmpty * Added NotNullOrEmpty on filename * Added system to interpret from the path * Added a check for if it contains a period * It has been done, how ever it will break stuff * Changed to use ??= how ever still added error check * Added space under check * Changed from with a period to valid file extension * Added checks for SendFileAsync * Removed filename != null && * Add channel types in application command options. (#217) * add channel types in application command options * Indent Docs * Stage instance audit logs as well as thread audit log type * Update azure-pipelines.yml * Update azure-pipelines.yml * Fix system messages not including mentioned users. Added ContextMenuCommand message type * Remove file extension check (#218) * Fix NRE in modify guild channel * Fix 429's not being accounted for in ratelimit updates * meta: add net5 framework Co-Authored-By: MrCakeSlayer <13650699+MrCakeSlayer@users.noreply.github.com> * Proper doc logos (#221) * Update GuildPermissionsTests.cs * Update GuildPermissions.cs * Add competing activity status type * logo changes * logo text as path * add missing logo * Update package logo and favicon * Update docfx references * Remove XML files and use original pipeline format * Remove console writeline * Remove Console.WriteLine * Remove useless log * Rename Available sticker field to IsAvailable * Rename Available to IsAvailable in stickers * Add summary indent for role members * Add summary indent to SocketInvite * Rename DefaultPermission to IsDefaultPermission * Rename Default to IsDefault and Required to IsRequired in IApplicationCommandOption * Rename Default and Required to IsDefault and IsRequired in IApplicationCommandOption. Rename DefaultPermission to IsDefaultPermission in IApplicationCommand * Remove extra white spaces * Renamed Joined, Archived, and Locked to HasJoined, IsArchived, and IsLocked * Rename Live and DiscoverableDisabled to IsDiscoverableDisabled and IsLive in IStageChannel * Remove newline * Add indent to summaries * Remove unnecessary json serializer field * Fix ToEntity for roletags incorrectly using IsPremiumSubscriber * Update RestChannel for new channel types * Fix different rest channels not deserializing properly * fully qualify internal for UrlValidation and add indent to summary * Add missing periods to InteractionResponseType * Fix summary in IApplicationCommandOptionChoice * Update IApplicationCommandOption summaries * Update IApplicationCommandInteractionDataOption summaries * Update IApplicationCommandInteractionData summaries * Update IApplicationCommand summaries * Update ApplicationCommandType summaries * rename DefaultPermission to IsDefaultPermission in ApplicationCommandProperties * update ApplicationCommandOptionChoiceProperties summaries * Rename Default, Required, and Autocomplete to IsDefault, IsRequired, and IsAutocomplete in ApplicationCommandOptionProperties * Update SlashCommandProperties summaries * update SlashCommandBuilder boolean field names, summaries, and choice parameters * Update SelectMenuOption summaries, Rename Default to IsDefault in SelectMenuOption * update SelectMenuComponent summaries. Rename Disabled to IsDisabled in SelectMenuComponent * update ComponentBuilder summaries and boolean fields. * Update ButtonComponent summaries and boolean fields * update ActionRowComponent summaries * Update UserCommandBuilder * Update MessageCommandBuilder summaries and boolean properties * Update IGuild summary * Update IGuild summaries * Update StagePrivacyLevel summary * update IThreadChannel summaries * Update IStageChannel summaries * Refactor summaries and boolean property names * General cleanup (#223) * General cleanup * Add Async suffix to SendAutocompleteResult * Fix more formatting * Fix unused RequestOptions in GetActiveThreadsAsync * Add message to ArgumentNullException * Ephemeral attachments * Add missing jsonproperty attribute * Add IMessage.Interaction * Update attachment checks for embed urls * meta: bump version * Remove old package configs and update image * Update package logos * Fix logo reference for azure * Deprecate old package definitions in favor for target file * Deprecate old package definitions in favor for target file Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Update package ids * Fix url validation * meta: bump version * Fix assignment of UserMentions (#233) * Fix CleanContent (#231) * Fix SocketSlashCommandData access modifier. (#237) Fixes #229 * Update README with better header (#232) * Update README with better header Adds HTML elements that implement the main logo & improve the redirection tag positions. * Resolving border issue in light-mode * Update sponsor section * Implement checks for interaction respond times and multiple interaction responses. closes #236, #235 * Add response check to socket auto complete * meta: bump versions * Fix #239 * meta: bump version * meta: update logo * meta: bump versions * Revert received at time, confirmed by discord staff to be accurate * Merge branch 'release/3.x' of https://github.com/Discord-Net-Labs/Discord.Net-Labs into merger-labs Update requested changes of obsolete and references to labs. Added `Interaction` to `IMessage` Fixed grammar Fixed bugs relating to interactions. * Update docs * Update CHANGELOG.md * meta: docs building * Update docs.yml * Update docs.yml * Fix docfx version * Update docs.yml * Update docs.bat * Rename docs repo for clone * update docfx version * Update docs.bat * Update docfx version * Remove docs from pipeline * FAQ revamped, metadata updated (#241) * FAQ revamped, metadata updated * Update FAQ.md * Update README.md * Docs index improvement * Fix InvalidOperationException in modify channel * feature: guild avatars, closes #238 * feature: modify role icons * meta: changelog * meta: bump version * Update README.md * Fix non value type options not being included in autocomplete * Add new activity flags (#254) * Add new activity flags * Add missing commas * Added support for GUILD_JOIN_REQUEST_DELETE event (#253) Fixes #247 * Adding BotHTTPInteraction user flag (#252) * animated guild banner support (#255) * Docs work (WIP) (#242) * Main page work * Metadata logo dir * More main page edits * Naming change * Dnet guide entries pruned * Add student hub guild directory channel (#256) * animated guild banner support * Add guild directory channel * Fix followup with file overwrite having incorrect parameter locations * Merge labs 3.x * Update GUILD_JOIN_REQUEST_DELETE event * Update head.tmpl.partial * Removed BannerId and AccentColor (#260) * Removed BannerId property, GetBannerURL method, and AccentColor property from IUser and socket entities. * Fixed errors in IUser.cs * Added back summary for GetAvatarUrl method in IUser.cs * Support Guild Boost Progress Bars (#262) * Support Guild Boost Progress Bars * Update SocketChannel.cs * Fix non-optional and unnecessary values. * Spelling * Reordering and consistency. * Remove log for reconnect * Add missing flags to SystemChannelMessageDeny (#267) * Fix labs reference in analyzer project and provider project * Rename new activity flags * Guild feature revamp and smart gateway intent checks * Get thread user implementation * Amend creating slash command guide (#269) * Adding BotHTTPInteraction user flag * Added comments explaining the Global command create stipulations. * Fix numeric type check for options * Add state checking to ConnectionManager.StartAsync (#272) * initial interface changes * Multi file upload + attachment editing * meta: bump versions * Update CHANGELOG.md * Update CHANGELOG.md * Support Min and Max values on ApplicationCommandOptions (#273) * Support Min and Max values on ApplicationCommandOptions * Support decimal min/max values * Docs imrpovments + use ToNullable * Logomark, doc settings edit (#258) * Logomark, doc settings edit * Replace standard logo * Bumping docfx plugins to latest release * Bump version metadata * Logo svg fix * Change default sticker behavior and add AlwaysResolveSticker to the config * Implement rest based interactions. Added ED25519 checks. Updated summaries. * Update package logo * Automatically fix ordering of optional command options (#276) * auto fix optional command option order * clean up indentation * Fix maximum number of Select Menu Options (#282) As of https://discord.com/developers/docs/interactions/message-components#select-menu-object-select-menu-structure the maximum number of options is 25, not less than 25. Hopefully the change catches all necessary locations * Add voice region to modify voice channels * Update summaries on rest interactions * Interaction Specific Interfaces (#283) * added interaction specific interfaces * fix build error * implement change requests * Update application * Add Guild Scheduled Events (#279) * guild events initial * sharded events * Add new gateway intents and fix bugs * More work on new changes to guild events * Update guild scheduled events * Added events to extended guild and add event start event * Update preconditions * Implement breaking changes guild guild events. Add guild event permissions * Update tests and change privacy level requirements * Update summaries and add docs for guild events * meta: bump version * Increment meta version (#285) * Increment meta version * Update docfx.json * Fix #289 and add configureawaits to rest based interactions * meta: bump version * Add GUILD_SCHEDULED_EVENT_USER_ADD and GUILD_SCHEDULED_EVENT_USER_REMOVE (#287) * Remove newline * Fix autocomplete result value * meta: bump versions * Add `GuildScheduledEventUserAdd` and `GuildScheduledEventUserRemove` to sharded client * Make RestUserCommand public (#292) * Fix Components not showing on FUWF (#288) (#293) Adds Components to Payload JSON Generation * Implement smarter rest resolvable interaction data. Fixes #294 * Add UseInteractionSnowflakeDate to config #286 * Implement Better Discord Errors (#291) * Initial error parsing * Implement better errors * Add missing error codes * Add voice disconnect opcodes * Remove unused class, add summaries to discordjsonerror, and remove public constructor of slash command properties * Add error code summary * Update error message summary * Update src/Discord.Net.Core/DiscordJsonError.cs Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Update src/Discord.Net.WebSocket/API/Voice/VoiceCloseCode.cs Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Fix autocomplete result value Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> * Change the minimum length of slash commands to 1 (#284) * Change the minimum length of slash commands to 1. This is the correct value according to the docs and it has been changed after user feedback. * Fix the limit in 3 other places Co-authored-by: quin lynch <lynchquin@gmail.com> * Add new thread creation properties * Add role emoji. Fixes #295 * Fix mocked text channel * Fix precondition checks. Closes #281 * Initial fix (#297) * meta: bump version * Update from release/3.x * Remove more labs references * Remove doc file for Discord.Net.Analyzers Co-authored-by: Simon Hjorthøj <sh2@live.dk> Co-authored-by: drobbins329 <drobbins329@gmail.com> Co-authored-by: MrCakeSlayer <13650699+MrCakeSlayer@users.noreply.github.com> Co-authored-by: d4n3436 <dan3436@hotmail.com> Co-authored-by: Will <WilliamWelsh@users.noreply.github.com> Co-authored-by: Eugene Garbuzov <kkxo.mail@gmail.com> Co-authored-by: CottageDwellingCat <80918250+CottageDwellingCat@users.noreply.github.com> Co-authored-by: Emily <89871431+emillly-b@users.noreply.github.com> Co-authored-by: marens101 <marens101@gmail.com> Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> Co-authored-by: Armano den Boef <68127614+Rozen4334@users.noreply.github.com> Co-authored-by: Bill <billchirico@gmail.com> Co-authored-by: Liege72 <65319395+Liege72@users.noreply.github.com> Co-authored-by: Floowey <floowey@gmx.at> Co-authored-by: Cenk Ergen <57065323+Cenngo@users.noreply.github.com> Co-authored-by: exsersewo <exsersewo@systemexit.co.uk> Co-authored-by: Dennis Fischer <fischer_dennis@live.de> commit3395700720Author: Nikon <47792796+INikonI@users.noreply.github.com> Date: Mon Aug 23 02:00:18 2021 +0500 feature: IVoiceChannel implements IMentionable (#1896) commit 41b4686b5e77cd9986006866b9ac7ac418bc05f2 Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Tue Aug 3 20:43:10 2021 -0300 Update README.md commit 5fc31451a1fafdc471acfe3a08269d371b20b70b Author: Quin Lynch <49576606+quinchs@users.noreply.github.com> Date: Tue Aug 3 20:28:15 2021 -0300 Update README.md commit56d16397f7Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Fri Nov 27 18:42:23 2020 -0300 Fixes Azure linux build failing due to a CS8652. commitc455b50331Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Fri Nov 27 14:10:39 2020 -0300 Make use of new ValidateAndGetBestMatch api on ExecuteAsync commit7955a09090Author: roridev <t3ctotalmenterandom1@outlook.com> Date: Fri Nov 27 13:52:53 2020 -0300 Creates ValidateAndGetBestMatch function This function will validate all commands from a SearchResult and return the result of said validation, along with the command matched, if a valid match was found. commit574b503e9eAuthor: roridev <t3ctotalmenterandom1@outlook.com> Date: Fri Nov 27 13:38:00 2020 -0300 Moves CalculateScore function to outer scope. * Update from Discord.Net dev - fix merge conflicts * meta: .net6 support * meta: pipelines use .net 6 * meta: bump tests framework versions * Invoke SlashCommandExecuted event on failed type conversion (#314) * added interaction specific interfaces * fix build error * implement change requests * add autocomplete respond method to IAutocompleteInteraction * fix sharded client current user * fix generic typeconverter picking priority * Revert "fix sharded client current user" This reverts commit a9c15ffd6ab02651e83e72c275889502b60cfddc. * Revert "add autocomplete respond method to IAutocompleteInteraction" This reverts commit f2fc50f1f19a0b41144b6dc93080d2f3a01282fc. * fix command parsing for names with spaces * add SlashCommandExecuted event invoke to failed type conversion * update interactions sample app * Revert "update interactions sample app" This reverts commit 6ac8cd0da60b440874cf29abc7202cdc49fd0538. * meta: bump to exclusive net.5 and net6 versions Co-Authored-By: JT <Hawxy@users.noreply.github.com> * meta: bump versions * meta: add net461 support back * Add System.Collections.Immutable back to core * Fix presence NRE * meta: bump versions * Fix presence NRE again... * meta: bump version * Fix current user presence * meta: bump version * Fix NRE on service providerless command execution (#322) * fix not set to an instance of an object exception for service providerless command execution * add methods for manually registering global comands (#325) * fix dependency injection link in docs (#326) * Add back netstandard2.0 / 2.1. Closes #324 * meta: bump version * Add not supported exception on news channels when creating threads, #296 * Revert thread block for news channel. Add check for news channel Co-Authored-By: Nova Fox <novamaday@gmail.com> * Make autocomplete log virtual (#328) * Fix #300 again * Update GUILD_SCHEDULED_EVENT_CREATE (#330) Changed _guildScheduledEventCancelled to _guildScheduledEventCreated in GUILD_SCHEDULED_EVENT_CREATE * correct the number of allowed autocomplete choices (#333) * correct the number of allowed autocomplete choices (#334) * Add FollowupWithFileAsync to IDiscordInteraction (#336) * Add uppercase character check to SlashCommandBuilder and ApplicationCommandOptionProperties (#339) * Make IModuleBase and IInteractionModuleBase public (#341) * fix command validation (#335) * fix autocomplete command traversal and use IList<string> in command map instead of stirng[] (#342) * Refactor Interactions (#340) * Refactor Interactions * Remove ApplicationCommandException * Fix Module Preconditions (#343) * fix module preconditions * fix module preconditions * meta: bump version * Update autocomplete docs * Initial preps * Fix #347 This comit makes `Content` optional for webhook execution. This comit also adds null checks to content when creating the api args to properly specify the optional struct to the model. This is done so the message entity doesn't try to parse a null string. * Fix merge errors * meta: net5 and 6 support * Update README.md * meta: bump version * Trim SlashCommandInfo.ToString() (#346) Co-authored-by: TheStachelfisch <TheStachelfisch@users.noreply.github.com> * Ensure User Left Event (#349) * Update README.md * Add 50055 Error code (#352) Co-authored-by: quin lynch <lynchquin@gmail.com> * remove DeleteUnknownSlashCommandAck (#353) * [Robot] Add missing json error (#354) * Add 20029 Error code * Update DiscordErrorCode.cs Co-authored-by: Robot Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> * Fix #355 and make UpdateAsync return a RestInteractionResponse * fix: unclear parameter naming for MessageCommand (#361) * Update DiscordRestApiClient.cs (#357) Add missing check to Content value to prevent NRE on empty message. Also made `ModifyInteractionFollowupMessageAsync`'s check consistent with `CreateInteractionFollowupMessageAsync` * Introduce emoji role property into rolehelper (#360) * Introduce emoji role property into rolehelper * Add check for exclusive properties * Oversight resolved * Valid order for error responses * Appending suggestions * Rename component to components (#363) * Adding BotHTTPInteraction user flag * change component -> components * added Interactions project * make SearchResult public (#365) * add missing coin emoji (#367) https://github.com/Discord-Net-Labs/Discord.Net-Labs/issues/364 * Add `IsAutocomplete` to rest command options (#368) * Make RestMessageComponent public (#369) * Docs rework, prep for merge into DNET (#359) * Appending previous changes * Deprecating unique feature listing & unused branch * Getting rid of old faq * Add all missed changelog entries This was painful :'') * Appending suggestions, large interior rework * Deleting unused entries * Removing more unused entries * Recover accidental deletion & append docfx file * Resolve a few docfx errors * Resolving more docfx errors * Clearing up final warnings * Appending suggestions * Removing main nightly for dnetlabs * Discord link updates * Add migration guide * Update v2_to_v3_guide.md * Fix spelling mistake Co-authored-by: quin lynch <lynchquin@gmail.com> * Update docFX plugins and xrefs * Add changelog and remove old docs Co-authored-by: Simon Hjorthøj <sh2@live.dk> Co-authored-by: Eugene Garbuzov <kkxo.mail@gmail.com> Co-authored-by: CottageDwellingCat <80918250+CottageDwellingCat@users.noreply.github.com> Co-authored-by: MrCakeSlayer <13650699+MrCakeSlayer@users.noreply.github.com> Co-authored-by: Will <WilliamWelsh@users.noreply.github.com> Co-authored-by: Emily <89871431+emillly-b@users.noreply.github.com> Co-authored-by: marens101 <marens101@gmail.com> Co-authored-by: d4n3436 <dan3436@hotmail.com> Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com> Co-authored-by: Armano den Boef <68127614+Rozen4334@users.noreply.github.com> Co-authored-by: Bill <billchirico@gmail.com> Co-authored-by: KeylAmi <drobbins329@gmail.com> Co-authored-by: Liege72 <65319395+Liege72@users.noreply.github.com> Co-authored-by: Floowey <floowey@gmx.at> Co-authored-by: Cenk Ergen <57065323+Cenngo@users.noreply.github.com> Co-authored-by: exsersewo <exsersewo@systemexit.co.uk> Co-authored-by: Dennis Fischer <fischer_dennis@live.de> Co-authored-by: PoolPirate <94938310+PoolPirate@users.noreply.github.com> Co-authored-by: Playwo <eliaswolf2001@t-online.de> Co-authored-by: JT <Hawxy@users.noreply.github.com> Co-authored-by: Nova Fox <novamaday@gmail.com> Co-authored-by: Daan van den Hoek <28300783+daanvandenhoek@users.noreply.github.com> Co-authored-by: nev-r <gh@f-m.fm> Co-authored-by: TheStachelfisch <50026847+TheStachelfisch@users.noreply.github.com> Co-authored-by: TheStachelfisch <TheStachelfisch@users.noreply.github.com> Co-authored-by: Discord-NET-Robot <95661365+Discord-NET-Robot@users.noreply.github.com> Co-authored-by: Xeno <eliotd@gmail.com>
This commit is contained in:
Quin Lynch
51
docs/guides/text_commands/dependency-injection.md
Normal file
51
docs/guides/text_commands/dependency-injection.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
uid: Guides.TextCommands.DI
|
||||
title: Dependency Injection
|
||||
---
|
||||
|
||||
# Dependency Injection
|
||||
|
||||
The Text Command Service is bundled with a very barebone Dependency
|
||||
Injection service for your convenience. It is recommended that you use
|
||||
DI when writing your modules.
|
||||
|
||||
> [!WARNING]
|
||||
> If you were brought here from the Interaction Service guides,
|
||||
> make sure to replace all namespaces that imply `Discord.Commands` with `Discord.Interactions`
|
||||
|
||||
## Setup
|
||||
|
||||
1. Create a @Microsoft.Extensions.DependencyInjection.ServiceCollection.
|
||||
2. Add the dependencies to the service collection that you wish
|
||||
to use in the modules.
|
||||
3. Build the service collection into a service provider.
|
||||
4. Pass the service collection into @Discord.Commands.CommandService.AddModulesAsync* / @Discord.Commands.CommandService.AddModuleAsync* , @Discord.Commands.CommandService.ExecuteAsync* .
|
||||
|
||||
### Example - Setting up Injection
|
||||
|
||||
[!code-csharp[IServiceProvider Setup](samples/dependency-injection/dependency_map_setup.cs)]
|
||||
|
||||
## Usage in Modules
|
||||
|
||||
In the constructor of your module, any parameters will be filled in by
|
||||
the @System.IServiceProvider that you've passed.
|
||||
|
||||
Any publicly settable properties will also be filled in the same
|
||||
manner.
|
||||
|
||||
> [!NOTE]
|
||||
> Annotating a property with a [DontInjectAttribute] attribute will
|
||||
> prevent the property from being injected.
|
||||
|
||||
> [!NOTE]
|
||||
> If you accept `CommandService` or `IServiceProvider` as a parameter
|
||||
> in your constructor or as an injectable property, these entries will
|
||||
> be filled by the `CommandService` that the module is loaded from and
|
||||
> the `IServiceProvider` that is passed into it respectively.
|
||||
|
||||
### Example - Injection in Modules
|
||||
|
||||
[!code-csharp[Injection Modules](samples/dependency-injection/dependency_module.cs)]
|
||||
[!code-csharp[Disallow Dependency Injection](samples/dependency-injection/dependency_module_noinject.cs)]
|
||||
|
||||
[DontInjectAttribute]: xref:Discord.Commands.DontInjectAttribute
|
||||
221
docs/guides/text_commands/intro.md
Normal file
221
docs/guides/text_commands/intro.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
uid: Guides.TextCommands.Intro
|
||||
title: Introduction to the Chat Command Service
|
||||
---
|
||||
|
||||
# The Text Command Service
|
||||
|
||||
[Discord.Commands](xref:Discord.Commands) provides an attribute-based
|
||||
command parser.
|
||||
|
||||
## Get Started
|
||||
|
||||
To use commands, you must create a [Command Service] and a command
|
||||
handler.
|
||||
|
||||
Included below is a barebone command handler. You can extend your
|
||||
command handler as much as you like; however, the below is the bare
|
||||
minimum.
|
||||
|
||||
> [!NOTE]
|
||||
> The `CommandService` will optionally accept a [CommandServiceConfig],
|
||||
> which *does* set a few default values for you. It is recommended to
|
||||
> look over the properties in [CommandServiceConfig] and their default
|
||||
> values.
|
||||
|
||||
[!code-csharp[Command Handler](samples/intro/command_handler.cs)]
|
||||
|
||||
[Command Service]: xref:Discord.Commands.CommandService
|
||||
[CommandServiceConfig]: xref:Discord.Commands.CommandServiceConfig
|
||||
|
||||
## With Attributes
|
||||
|
||||
Starting from 1.0, commands can be defined ahead of time with
|
||||
attributes, or at runtime with builders.
|
||||
|
||||
For most bots, ahead-of-time commands should be all you need, and this
|
||||
is the recommended method of defining commands.
|
||||
|
||||
### Modules
|
||||
|
||||
The first step to creating commands is to create a _module_.
|
||||
|
||||
A module is an organizational pattern that allows you to write your
|
||||
commands in different classes and have them automatically loaded.
|
||||
|
||||
Discord.Net's implementation of "modules" is influenced heavily by the
|
||||
ASP.NET Core's Controller pattern. This means that the lifetime of a
|
||||
module instance is only as long as the command is being invoked.
|
||||
|
||||
Before we create a module, it is **crucial** for you to remember that
|
||||
in order to create a module and have it automatically discovered,
|
||||
your module must:
|
||||
|
||||
* Be public
|
||||
* Inherit [ModuleBase]
|
||||
|
||||
By now, your module should look like this:
|
||||
|
||||
[!code-csharp[Empty Module](samples/intro/empty-module.cs)]
|
||||
|
||||
> [!NOTE]
|
||||
> [ModuleBase] is an `abstract` class, meaning that you may extend it
|
||||
> or override it as you see fit. Your module may inherit from any
|
||||
> extension of ModuleBase.
|
||||
|
||||
[IoC]: https://msdn.microsoft.com/en-us/library/ff921087.aspx
|
||||
[Dependency Injection]: https://msdn.microsoft.com/en-us/library/ff921152.aspx
|
||||
[ModuleBase]: xref:Discord.Commands.ModuleBase`1
|
||||
|
||||
### Adding/Creating Commands
|
||||
|
||||
> [!WARNING]
|
||||
> **Avoid using long-running code** in your modules wherever possible.
|
||||
> Long-running code, by default, within a command module
|
||||
> can cause gateway thread to be blocked; therefore, interrupting
|
||||
> the bot's connection to Discord.
|
||||
>
|
||||
> You may read more about it in @FAQ.Commands.General .
|
||||
|
||||
The next step to creating commands is actually creating the commands.
|
||||
|
||||
For a command to be valid, it **must** have a return type of `Task`
|
||||
or `Task<RuntimeResult>`. Typically, you might want to mark this
|
||||
method as `async`, although it is not required.
|
||||
|
||||
Then, flag your command with the [CommandAttribute]. Note that you must
|
||||
specify a name for this command, except for when it is part of a
|
||||
[Module Group](#module-groups).
|
||||
|
||||
### Command Parameters
|
||||
|
||||
Adding parameters to a command is done by adding parameters to the
|
||||
parent `Task`.
|
||||
|
||||
For example:
|
||||
|
||||
* To take an integer as an argument from the user, add `int num`.
|
||||
* To take a user as an argument from the user, add `IUser user`.
|
||||
* ...etc.
|
||||
|
||||
Starting from 1.0, a command can accept nearly any type of argument;
|
||||
a full list of types that are parsed by default can
|
||||
be found in @Guides.Commands.TypeReaders.
|
||||
|
||||
[CommandAttribute]: xref:Discord.Commands.CommandAttribute
|
||||
|
||||
#### Optional Parameters
|
||||
|
||||
Parameters, by default, are always required. To make a parameter
|
||||
optional, give it a default value (i.e., `int num = 0`).
|
||||
|
||||
#### Parameters with Spaces
|
||||
|
||||
To accept a space-separated list, set the parameter to `params Type[]`.
|
||||
|
||||
Should a parameter include spaces, the parameter **must** be
|
||||
wrapped in quotes. For example, for a command with a parameter
|
||||
`string food`, you would execute it with
|
||||
`!favoritefood "Key Lime Pie"`.
|
||||
|
||||
If you would like a parameter to parse until the end of a command,
|
||||
flag the parameter with the [RemainderAttribute]. This will
|
||||
allow a user to invoke a command without wrapping a
|
||||
parameter in quotes.
|
||||
|
||||
[RemainderAttribute]: xref:Discord.Commands.RemainderAttribute
|
||||
|
||||
### Command Overloads
|
||||
|
||||
You may add overloads to your commands, and the command parser will
|
||||
automatically pick up on it.
|
||||
|
||||
If, for whatever reason, you have two commands which are ambiguous to
|
||||
each other, you may use the @Discord.Commands.PriorityAttribute to
|
||||
specify which should be tested before the other.
|
||||
|
||||
The `Priority` attributes are sorted in descending order; the higher
|
||||
priority will be called first.
|
||||
|
||||
### Command Context
|
||||
|
||||
Every command can access the execution context through the [Context]
|
||||
property on [ModuleBase]. `ICommandContext` allows you to access the
|
||||
message, channel, guild, user, and the underlying Discord client
|
||||
that the command was invoked from.
|
||||
|
||||
Different types of `Context` may be specified using the generic variant
|
||||
of [ModuleBase]. When using a [SocketCommandContext], for example, the
|
||||
properties on this context will already be Socket entities, so you
|
||||
will not need to cast them.
|
||||
|
||||
To reply to messages, you may also invoke [ReplyAsync], instead of
|
||||
accessing the channel through the [Context] and sending a message.
|
||||
|
||||
> [!WARNING]
|
||||
> Contexts should **NOT** be mixed! You cannot have one module that
|
||||
> uses `CommandContext` and another that uses `SocketCommandContext`.
|
||||
|
||||
[Context]: xref:Discord.Commands.ModuleBase`1.Context
|
||||
[SocketCommandContext]: xref:Discord.Commands.SocketCommandContext
|
||||
[ReplyAsync]: xref:Discord.Commands.ModuleBase`1.ReplyAsync*
|
||||
|
||||
> [!TIP]
|
||||
> At this point, your module should look comparable to this example:
|
||||
> [!code-csharp[Example Module](samples/intro/module.cs)]
|
||||
|
||||
#### Loading Modules Automatically
|
||||
|
||||
The Command Service can automatically discover all classes in an
|
||||
`Assembly` that inherit [ModuleBase] and load them. Invoke
|
||||
[CommandService.AddModulesAsync] to discover modules and
|
||||
install them.
|
||||
|
||||
To opt a module out of auto-loading, flag it with
|
||||
[DontAutoLoadAttribute].
|
||||
|
||||
[DontAutoLoadAttribute]: xref:Discord.Commands.DontAutoLoadAttribute
|
||||
[CommandService.AddModulesAsync]: xref:Discord.Commands.CommandService.AddModulesAsync*
|
||||
|
||||
#### Loading Modules Manually
|
||||
|
||||
To manually load a module, invoke [CommandService.AddModuleAsync] by
|
||||
passing in the generic type of your module and optionally, a
|
||||
service provider.
|
||||
|
||||
[CommandService.AddModuleAsync]: xref:Discord.Commands.CommandService.AddModuleAsync*
|
||||
|
||||
### Module Constructors
|
||||
|
||||
Modules are constructed using [Dependency Injection](xref:Guides.TextCommands.DI). Any parameters
|
||||
that are placed in the Module's constructor must be injected into an
|
||||
@System.IServiceProvider first.
|
||||
|
||||
> [!TIP]
|
||||
> Alternatively, you may accept an
|
||||
> `IServiceProvider` as an argument and extract services yourself,
|
||||
> although this is discouraged.
|
||||
|
||||
### Module Properties
|
||||
|
||||
Modules with `public` settable properties will have the dependencies
|
||||
injected after the construction of the module. See @Guides.Commands.DI
|
||||
to learn more.
|
||||
|
||||
### Module Groups
|
||||
|
||||
Module Groups allow you to create a module where commands are
|
||||
prefixed. To create a group, flag a module with the
|
||||
@Discord.Commands.GroupAttribute.
|
||||
|
||||
Module Groups also allow you to create **nameless Commands**, where
|
||||
the [CommandAttribute] is configured with no name. In this case, the
|
||||
command will inherit the name of the group it belongs to.
|
||||
|
||||
### Submodules
|
||||
|
||||
Submodules are "modules" that reside within another one. Typically,
|
||||
submodules are used to create nested groups (although not required to
|
||||
create nested groups).
|
||||
|
||||
[!code-csharp[Groups and Submodules](samples/intro/groups.cs)]
|
||||
79
docs/guides/text_commands/namedarguments.md
Normal file
79
docs/guides/text_commands/namedarguments.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
uid: Guides.TextCommands.NamedArguments
|
||||
title: Named Arguments
|
||||
---
|
||||
|
||||
# Named Arguments
|
||||
|
||||
By default, arguments for commands are parsed positionally, meaning
|
||||
that the order matters. But sometimes you may want to define a command
|
||||
with many optional parameters, and it'd be easier for end-users
|
||||
to only specify what they want to set, instead of needing them
|
||||
to specify everything by hand.
|
||||
|
||||
## Setting up Named Arguments
|
||||
|
||||
In order to be able to specify different arguments by name, you have
|
||||
to create a new class that contains all of the optional values that
|
||||
the command will use, and apply an instance of
|
||||
[NamedArgumentTypeAttribute] on it.
|
||||
|
||||
### Example - Creating a Named Arguments Type
|
||||
|
||||
```cs
|
||||
[NamedArgumentType]
|
||||
public class NamableArguments
|
||||
{
|
||||
public string First { get; set; }
|
||||
public string Second { get; set; }
|
||||
public string Third { get; set; }
|
||||
public string Fourth { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
## Usage in a Command
|
||||
|
||||
The command where you want to use these values can be declared like so:
|
||||
```cs
|
||||
[Command("act")]
|
||||
public async Task Act(int requiredArg, NamableArguments namedArgs)
|
||||
```
|
||||
|
||||
The command can now be invoked as
|
||||
`.act 42 first: Hello fourth: "A string with spaces must be wrapped in quotes" second: World`.
|
||||
|
||||
A TypeReader for the named arguments container type is
|
||||
automatically registered.
|
||||
It's important that any other arguments that would be required
|
||||
are placed before the container type.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> A single command can have only __one__ parameter of a
|
||||
> type annotated with [NamedArgumentTypeAttribute], and it
|
||||
> **MUST** be the last parameter in the list.
|
||||
> A command parameter of such an annotated type
|
||||
> is automatically treated as if that parameter
|
||||
> has [RemainderAttribute](xref:Discord.Commands.RemainderAttribute)
|
||||
> applied.
|
||||
|
||||
## Complex Types
|
||||
|
||||
The TypeReader for Named Argument Types will look for a TypeReader
|
||||
of every property type, meaning any other command parameter type
|
||||
will work just the same.
|
||||
|
||||
You can also read multiple values into a single property
|
||||
by making that property an `IEnumerable<T>`. So for example, if your
|
||||
Named Argument Type has the following field,
|
||||
```cs
|
||||
public IEnumerable<int> Numbers { get; set; }
|
||||
```
|
||||
then the command can be invoked as
|
||||
`.cmd numbers: "1, 2, 4, 8, 16, 32"`
|
||||
|
||||
## Additional Notes
|
||||
|
||||
The use of [`[OverrideTypeReader]`](xref:Discord.Commands.OverrideTypeReaderAttribute)
|
||||
is also supported on the properties of a Named Argument Type.
|
||||
|
||||
[NamedArgumentTypeAttribute]: xref:Discord.Commands.NamedArgumentTypeAttribute
|
||||
120
docs/guides/text_commands/post-execution.md
Normal file
120
docs/guides/text_commands/post-execution.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
uid: Guides.TextCommands.PostExecution
|
||||
title: Post-command Execution Handling
|
||||
---
|
||||
|
||||
# Post-execution Handling for Text Commands
|
||||
|
||||
When developing commands, you may want to consider building a
|
||||
post-execution handling system so you can have finer control
|
||||
over commands. Discord.Net offers several post-execution workflows
|
||||
for you to work with.
|
||||
|
||||
If you recall, in the [Command Guide], we have shown the following
|
||||
example for executing and handling commands,
|
||||
|
||||
[!code[Command Handler](samples/intro/command_handler.cs)]
|
||||
|
||||
You may notice that after we perform [ExecuteAsync], we store the
|
||||
result and print it to the chat, essentially creating the most
|
||||
fundamental form of a post-execution handler.
|
||||
|
||||
With this in mind, we could start doing things like the following,
|
||||
|
||||
[!code[Basic Command Handler](samples/post-execution/post-execution_basic.cs)]
|
||||
|
||||
However, this may not always be preferred, because you are
|
||||
creating your post-execution logic *with* the essential command
|
||||
handler. This design could lead to messy code and could potentially
|
||||
be a violation of the SRP (Single Responsibility Principle).
|
||||
|
||||
Another major issue is if your command is marked with
|
||||
`RunMode.Async`, [ExecuteAsync] will **always** return a successful
|
||||
[ExecuteResult] instead of the actual result. You can learn more
|
||||
about the impact in @FAQ.Commands.General.
|
||||
|
||||
## CommandExecuted Event
|
||||
|
||||
Enter [CommandExecuted], an event that was introduced in
|
||||
Discord.Net 2.0. This event is raised whenever a command is
|
||||
executed regardless of its execution status. This means this
|
||||
event can be used to streamline your post-execution design,
|
||||
is not prone to `RunMode.Async`'s [ExecuteAsync] drawbacks.
|
||||
|
||||
Thus, we can begin working on code such as:
|
||||
|
||||
[!code[CommandExecuted demo](samples/post-execution/command_executed_demo.cs)]
|
||||
|
||||
So now we have a streamlined post-execution pipeline, great! What's
|
||||
next? We can take this further by using [RuntimeResult].
|
||||
|
||||
### RuntimeResult
|
||||
|
||||
`RuntimeResult` was initially introduced in 1.0 to allow
|
||||
developers to centralize their command result logic.
|
||||
In other words, it is a result type that is designed to be
|
||||
returned when the command has finished its execution.
|
||||
|
||||
However, it wasn't widely adopted due to the aforementioned
|
||||
[ExecuteAsync] drawback. Since we now have access to a proper
|
||||
result-handler via the [CommandExecuted] event, we can start
|
||||
making use of this class.
|
||||
|
||||
The best way to make use of it is to create your version of
|
||||
`RuntimeResult`. You can achieve this by inheriting the `RuntimeResult`
|
||||
class.
|
||||
|
||||
The following creates a bare-minimum required for a sub-class
|
||||
of `RuntimeResult`,
|
||||
|
||||
[!code[Base Use](samples/post-execution/customresult_base.cs)]
|
||||
|
||||
The sky is the limit from here. You can add any additional information
|
||||
you would like regarding the execution result.
|
||||
|
||||
For example, you may want to add your result type or other
|
||||
helpful information regarding the execution, or something
|
||||
simple like static methods to help you create return types easily.
|
||||
|
||||
[!code[Extended Use](samples/post-execution/customresult_extended.cs)]
|
||||
|
||||
After you're done creating your [RuntimeResult], you can
|
||||
implement it in your command by marking the command return type to
|
||||
`Task<RuntimeResult>`.
|
||||
|
||||
> [!NOTE]
|
||||
> You must mark the return type as `Task<RuntimeResult>` instead of
|
||||
> `Task<MyCustomResult>`. Only the former will be picked up when
|
||||
> building the module.
|
||||
|
||||
Here's an example of a command that utilizes such logic:
|
||||
|
||||
[!code[Usage](samples/post-execution/customresult_usage.cs)]
|
||||
|
||||
And now we can check for it in our [CommandExecuted] handler:
|
||||
|
||||
[!code[Usage](samples/post-execution/command_executed_adv_demo.cs)]
|
||||
|
||||
## CommandService.Log Event
|
||||
|
||||
We have so far covered the handling of various result types, but we
|
||||
have not talked about what to do if the command enters a catastrophic
|
||||
failure (i.e., exceptions). To resolve this, we can make use of the
|
||||
[CommandService.Log] event.
|
||||
|
||||
All exceptions thrown during a command execution are caught and sent
|
||||
to the Log event under the [LogMessage.Exception] property
|
||||
as a [CommandException] type. The [CommandException] class allows
|
||||
us to access the exception thrown, as well as the context
|
||||
of the command.
|
||||
|
||||
[!code[Logger Sample](samples/post-execution/command_exception_log.cs)]
|
||||
|
||||
[CommandException]: xref:Discord.Commands.CommandException
|
||||
[LogMessage.Exception]: xref:Discord.LogMessage.Exception
|
||||
[CommandService.Log]: xref:Discord.Commands.CommandService.Log
|
||||
[RuntimeResult]: xref:Discord.Commands.RuntimeResult
|
||||
[CommandExecuted]: xref:Discord.Commands.CommandService.CommandExecuted
|
||||
[ExecuteAsync]: xref:Discord.Commands.CommandService.ExecuteAsync*
|
||||
[ExecuteResult]: xref:Discord.Commands.ExecuteResult
|
||||
[Command Guide]: xref:Guides.TextCommands.Intro
|
||||
83
docs/guides/text_commands/preconditions.md
Normal file
83
docs/guides/text_commands/preconditions.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
uid: Guides.TextCommands.Preconditions
|
||||
title: Preconditions
|
||||
---
|
||||
|
||||
# Preconditions
|
||||
|
||||
Preconditions serve as a permissions system for your Commands. Keep in
|
||||
mind, however, that they are not limited to _just_ permissions and can
|
||||
be as complex as you want them to be.
|
||||
|
||||
There are two types of Preconditions you can use:
|
||||
|
||||
* [PreconditionAttribute] can be applied to Modules, Groups, or Commands.
|
||||
* [ParameterPreconditionAttribute] can be applied to Parameters.
|
||||
|
||||
You may visit their respective API documentation to find out more.
|
||||
|
||||
[PreconditionAttribute]: xref:Discord.Commands.PreconditionAttribute
|
||||
[ParameterPreconditionAttribute]: xref:Discord.Commands.ParameterPreconditionAttribute
|
||||
|
||||
## Bundled Preconditions
|
||||
|
||||
@Discord.Commands ships with several bundled Preconditions for you
|
||||
to use.
|
||||
|
||||
* @Discord.Commands.RequireContextAttribute
|
||||
* @Discord.Commands.RequireOwnerAttribute
|
||||
* @Discord.Commands.RequireBotPermissionAttribute
|
||||
* @Discord.Commands.RequireUserPermissionAttribute
|
||||
* @Discord.Commands.RequireNsfwAttribute
|
||||
|
||||
## Using Preconditions
|
||||
|
||||
To use a precondition, simply apply any valid precondition candidate to
|
||||
a command method signature as an attribute.
|
||||
|
||||
### Example - Using a Precondition
|
||||
|
||||
[!code-csharp[Precondition usage](samples/preconditions/precondition_usage.cs)]
|
||||
|
||||
## ORing Preconditions
|
||||
|
||||
When writing commands, you may want to allow some of them to be
|
||||
executed when only some of the precondition checks are passed.
|
||||
|
||||
This is where the [Group] property of a precondition attribute comes in
|
||||
handy. By assigning two or more preconditions to a group, the command
|
||||
system will allow the command to be executed when one of the
|
||||
precondition passes.
|
||||
|
||||
### Example - ORing Preconditions
|
||||
|
||||
[!code-csharp[OR Precondition](samples/preconditions/group_precondition.cs)]
|
||||
|
||||
[Group]: xref:Discord.Commands.PreconditionAttribute.Group
|
||||
|
||||
## Custom Preconditions
|
||||
|
||||
To write your own Precondition, create a new class that inherits from
|
||||
either [PreconditionAttribute] or [ParameterPreconditionAttribute]
|
||||
depending on your use.
|
||||
|
||||
In order for your Precondition to function, you will need to override
|
||||
the [CheckPermissionsAsync] method.
|
||||
|
||||
If the context meets the required parameters, return
|
||||
[PreconditionResult.FromSuccess], otherwise return
|
||||
[PreconditionResult.FromError] and include an error message if
|
||||
necessary.
|
||||
|
||||
> [!NOTE]
|
||||
> Visual Studio can help you implement missing members
|
||||
> from the abstract class by using the "Implement Abstract Class"
|
||||
> IntelliSense hint.
|
||||
|
||||
### Example - Creating a Custom Precondition
|
||||
|
||||
[!code-csharp[Custom Precondition](samples/preconditions/require_role.cs)]
|
||||
|
||||
[CheckPermissionsAsync]: xref:Discord.Commands.PreconditionAttribute.CheckPermissionsAsync*
|
||||
[PreconditionResult.FromSuccess]: xref:Discord.Commands.PreconditionResult.FromSuccess*
|
||||
[PreconditionResult.FromError]: xref:Discord.Commands.PreconditionResult.FromError*
|
||||
@@ -0,0 +1,65 @@
|
||||
public class Initialize
|
||||
{
|
||||
private readonly CommandService _commands;
|
||||
private readonly DiscordSocketClient _client;
|
||||
|
||||
// Ask if there are existing CommandService and DiscordSocketClient
|
||||
// instance. If there are, we retrieve them and add them to the
|
||||
// DI container; if not, we create our own.
|
||||
public Initialize(CommandService commands = null, DiscordSocketClient client = null)
|
||||
{
|
||||
_commands = commands ?? new CommandService();
|
||||
_client = client ?? new DiscordSocketClient();
|
||||
}
|
||||
|
||||
public IServiceProvider BuildServiceProvider() => new ServiceCollection()
|
||||
.AddSingleton(_client)
|
||||
.AddSingleton(_commands)
|
||||
// You can pass in an instance of the desired type
|
||||
.AddSingleton(new NotificationService())
|
||||
// ...or by using the generic method.
|
||||
//
|
||||
// The benefit of using the generic method is that
|
||||
// ASP.NET DI will attempt to inject the required
|
||||
// dependencies that are specified under the constructor
|
||||
// for us.
|
||||
.AddSingleton<DatabaseService>()
|
||||
.AddSingleton<CommandHandler>()
|
||||
.BuildServiceProvider();
|
||||
}
|
||||
public class CommandHandler
|
||||
{
|
||||
private readonly DiscordSocketClient _client;
|
||||
private readonly CommandService _commands;
|
||||
private readonly IServiceProvider _services;
|
||||
|
||||
public CommandHandler(IServiceProvider services, CommandService commands, DiscordSocketClient client)
|
||||
{
|
||||
_commands = commands;
|
||||
_services = services;
|
||||
_client = client;
|
||||
}
|
||||
|
||||
public async Task InitializeAsync()
|
||||
{
|
||||
// Pass the service provider to the second parameter of
|
||||
// AddModulesAsync to inject dependencies to all modules
|
||||
// that may require them.
|
||||
await _commands.AddModulesAsync(
|
||||
assembly: Assembly.GetEntryAssembly(),
|
||||
services: _services);
|
||||
_client.MessageReceived += HandleCommandAsync;
|
||||
}
|
||||
|
||||
public async Task HandleCommandAsync(SocketMessage msg)
|
||||
{
|
||||
// ...
|
||||
// Pass the service provider to the ExecuteAsync method for
|
||||
// precondition checks.
|
||||
await _commands.ExecuteAsync(
|
||||
context: context,
|
||||
argPos: argPos,
|
||||
services: _services);
|
||||
// ...
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
// After setting up dependency injection, modules will need to request
|
||||
// the dependencies to let the library know to pass
|
||||
// them along during execution.
|
||||
|
||||
// Dependency can be injected in two ways with Discord.Net.
|
||||
// You may inject any required dependencies via...
|
||||
// the module constructor
|
||||
// -or-
|
||||
// public settable properties
|
||||
|
||||
// Injection via constructor
|
||||
public class DatabaseModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
private readonly DatabaseService _database;
|
||||
public DatabaseModule(DatabaseService database)
|
||||
{
|
||||
_database = database;
|
||||
}
|
||||
|
||||
[Command("read")]
|
||||
public async Task ReadFromDbAsync()
|
||||
{
|
||||
await ReplyAsync(_database.GetData());
|
||||
}
|
||||
}
|
||||
|
||||
// Injection via public settable properties
|
||||
public class DatabaseModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
public DatabaseService DbService { get; set; }
|
||||
|
||||
[Command("read")]
|
||||
public async Task ReadFromDbAsync()
|
||||
{
|
||||
await ReplyAsync(DbService.GetData());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
// Sometimes injecting dependencies automatically with the provided
|
||||
// methods in the prior example may not be desired.
|
||||
|
||||
// You may explicitly tell Discord.Net to **not** inject the properties
|
||||
// by either...
|
||||
// restricting the access modifier
|
||||
// -or-
|
||||
// applying DontInjectAttribute to the property
|
||||
|
||||
// Restricting the access modifier of the property
|
||||
public class ImageModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
public ImageService ImageService { get; }
|
||||
public ImageModule()
|
||||
{
|
||||
ImageService = new ImageService();
|
||||
}
|
||||
}
|
||||
|
||||
// Applying DontInjectAttribute
|
||||
public class ImageModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
[DontInject]
|
||||
public ImageService ImageService { get; set; }
|
||||
public ImageModule()
|
||||
{
|
||||
ImageService = new ImageService();
|
||||
}
|
||||
}
|
||||
55
docs/guides/text_commands/samples/intro/command_handler.cs
Normal file
55
docs/guides/text_commands/samples/intro/command_handler.cs
Normal file
@@ -0,0 +1,55 @@
|
||||
public class CommandHandler
|
||||
{
|
||||
private readonly DiscordSocketClient _client;
|
||||
private readonly CommandService _commands;
|
||||
|
||||
// Retrieve client and CommandService instance via ctor
|
||||
public CommandHandler(DiscordSocketClient client, CommandService commands)
|
||||
{
|
||||
_commands = commands;
|
||||
_client = client;
|
||||
}
|
||||
|
||||
public async Task InstallCommandsAsync()
|
||||
{
|
||||
// Hook the MessageReceived event into our command handler
|
||||
_client.MessageReceived += HandleCommandAsync;
|
||||
|
||||
// Here we discover all of the command modules in the entry
|
||||
// assembly and load them. Starting from Discord.NET 2.0, a
|
||||
// service provider is required to be passed into the
|
||||
// module registration method to inject the
|
||||
// required dependencies.
|
||||
//
|
||||
// If you do not use Dependency Injection, pass null.
|
||||
// See Dependency Injection guide for more information.
|
||||
await _commands.AddModulesAsync(assembly: Assembly.GetEntryAssembly(),
|
||||
services: null);
|
||||
}
|
||||
|
||||
private async Task HandleCommandAsync(SocketMessage messageParam)
|
||||
{
|
||||
// Don't process the command if it was a system message
|
||||
var message = messageParam as SocketUserMessage;
|
||||
if (message == null) return;
|
||||
|
||||
// Create a number to track where the prefix ends and the command begins
|
||||
int argPos = 0;
|
||||
|
||||
// Determine if the message is a command based on the prefix and make sure no bots trigger commands
|
||||
if (!(message.HasCharPrefix('!', ref argPos) ||
|
||||
message.HasMentionPrefix(_client.CurrentUser, ref argPos)) ||
|
||||
message.Author.IsBot)
|
||||
return;
|
||||
|
||||
// Create a WebSocket-based command context based on the message
|
||||
var context = new SocketCommandContext(_client, message);
|
||||
|
||||
// Execute the command with the command context we just
|
||||
// created, along with the service provider for precondition checks.
|
||||
await _commands.ExecuteAsync(
|
||||
context: context,
|
||||
argPos: argPos,
|
||||
services: null);
|
||||
}
|
||||
}
|
||||
8
docs/guides/text_commands/samples/intro/empty-module.cs
Normal file
8
docs/guides/text_commands/samples/intro/empty-module.cs
Normal file
@@ -0,0 +1,8 @@
|
||||
using Discord.Commands;
|
||||
|
||||
// Keep in mind your module **must** be public and inherit ModuleBase.
|
||||
// If it isn't, it will not be discovered by AddModulesAsync!
|
||||
public class InfoModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
|
||||
}
|
||||
25
docs/guides/text_commands/samples/intro/groups.cs
Normal file
25
docs/guides/text_commands/samples/intro/groups.cs
Normal file
@@ -0,0 +1,25 @@
|
||||
[Group("admin")]
|
||||
public class AdminModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
[Group("clean")]
|
||||
public class CleanModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
// ~admin clean
|
||||
[Command]
|
||||
public async Task DefaultCleanAsync()
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
// ~admin clean messages 15
|
||||
[Command("messages")]
|
||||
public async Task CleanAsync(int count)
|
||||
{
|
||||
// ...
|
||||
}
|
||||
}
|
||||
// ~admin ban foxbot#0282
|
||||
[Command("ban")]
|
||||
public Task BanAsync(IGuildUser user) =>
|
||||
Context.Guild.AddBanAsync(user);
|
||||
}
|
||||
45
docs/guides/text_commands/samples/intro/module.cs
Normal file
45
docs/guides/text_commands/samples/intro/module.cs
Normal file
@@ -0,0 +1,45 @@
|
||||
// Create a module with no prefix
|
||||
public class InfoModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
// ~say hello world -> hello world
|
||||
[Command("say")]
|
||||
[Summary("Echoes a message.")]
|
||||
public Task SayAsync([Remainder] [Summary("The text to echo")] string echo)
|
||||
=> ReplyAsync(echo);
|
||||
|
||||
// ReplyAsync is a method on ModuleBase
|
||||
}
|
||||
|
||||
// Create a module with the 'sample' prefix
|
||||
[Group("sample")]
|
||||
public class SampleModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
// ~sample square 20 -> 400
|
||||
[Command("square")]
|
||||
[Summary("Squares a number.")]
|
||||
public async Task SquareAsync(
|
||||
[Summary("The number to square.")]
|
||||
int num)
|
||||
{
|
||||
// We can also access the channel from the Command Context.
|
||||
await Context.Channel.SendMessageAsync($"{num}^2 = {Math.Pow(num, 2)}");
|
||||
}
|
||||
|
||||
// ~sample userinfo --> foxbot#0282
|
||||
// ~sample userinfo @Khionu --> Khionu#8708
|
||||
// ~sample userinfo Khionu#8708 --> Khionu#8708
|
||||
// ~sample userinfo Khionu --> Khionu#8708
|
||||
// ~sample userinfo 96642168176807936 --> Khionu#8708
|
||||
// ~sample whois 96642168176807936 --> Khionu#8708
|
||||
[Command("userinfo")]
|
||||
[Summary
|
||||
("Returns info about the current user, or the user parameter, if one passed.")]
|
||||
[Alias("user", "whois")]
|
||||
public async Task UserInfoAsync(
|
||||
[Summary("The (optional) user to get info from")]
|
||||
SocketUser user = null)
|
||||
{
|
||||
var userInfo = user ?? Context.Client.CurrentUser;
|
||||
await ReplyAsync($"{userInfo.Username}#{userInfo.Discriminator}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
public async Task LogAsync(LogMessage logMessage)
|
||||
{
|
||||
if (logMessage.Exception is CommandException cmdException)
|
||||
{
|
||||
// We can tell the user that something unexpected has happened
|
||||
await cmdException.Context.Channel.SendMessageAsync("Something went catastrophically wrong!");
|
||||
|
||||
// We can also log this incident
|
||||
Console.WriteLine($"{cmdException.Context.User} failed to execute '{cmdException.Command.Name}' in {cmdException.Context.Channel}.");
|
||||
Console.WriteLine(cmdException.ToString());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
public async Task OnCommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
|
||||
{
|
||||
switch(result)
|
||||
{
|
||||
case MyCustomResult customResult:
|
||||
// do something extra with it
|
||||
break;
|
||||
default:
|
||||
if (!string.IsNullOrEmpty(result.ErrorReason))
|
||||
await context.Channel.SendMessageAsync(result.ErrorReason);
|
||||
break;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
public async Task SetupAsync()
|
||||
{
|
||||
await _command.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
|
||||
// Hook the execution event
|
||||
_command.CommandExecuted += OnCommandExecutedAsync;
|
||||
// Hook the command handler
|
||||
_client.MessageReceived += HandleCommandAsync;
|
||||
}
|
||||
public async Task OnCommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
|
||||
{
|
||||
// We have access to the information of the command executed,
|
||||
// the context of the command, and the result returned from the
|
||||
// execution in this event.
|
||||
|
||||
// We can tell the user what went wrong
|
||||
if (!string.IsNullOrEmpty(result?.ErrorReason))
|
||||
{
|
||||
await context.Channel.SendMessageAsync(result.ErrorReason);
|
||||
}
|
||||
|
||||
// ...or even log the result (the method used should fit into
|
||||
// your existing log handler)
|
||||
var commandName = command.IsSpecified ? command.Value.Name : "A command";
|
||||
await _log.LogAsync(new LogMessage(LogSeverity.Info,
|
||||
"CommandExecution",
|
||||
$"{commandName} was executed at {DateTime.UtcNow}."));
|
||||
}
|
||||
public async Task HandleCommandAsync(SocketMessage msg)
|
||||
{
|
||||
var message = messageParam as SocketUserMessage;
|
||||
if (message == null) return;
|
||||
int argPos = 0;
|
||||
if (!(message.HasCharPrefix('!', ref argPos) ||
|
||||
message.HasMentionPrefix(_client.CurrentUser, ref argPos)) ||
|
||||
message.Author.IsBot) return;
|
||||
var context = new SocketCommandContext(_client, message);
|
||||
await _commands.ExecuteAsync(context, argPos, _services);
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
public class MyCustomResult : RuntimeResult
|
||||
{
|
||||
public MyCustomResult(CommandError? error, string reason) : base(error, reason)
|
||||
{
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
public class MyCustomResult : RuntimeResult
|
||||
{
|
||||
public MyCustomResult(CommandError? error, string reason) : base(error, reason)
|
||||
{
|
||||
}
|
||||
public static MyCustomResult FromError(string reason) =>
|
||||
new MyCustomResult(CommandError.Unsuccessful, reason);
|
||||
public static MyCustomResult FromSuccess(string reason = null) =>
|
||||
new MyCustomResult(null, reason);
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
public class MyModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
[Command("eat")]
|
||||
public async Task<RuntimeResult> ChooseAsync(string food)
|
||||
{
|
||||
if (food == "salad")
|
||||
return MyCustomResult.FromError("No, I don't want that!");
|
||||
return MyCustomResult.FromSuccess($"Give me the {food}!").
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
// Bad code!!!
|
||||
var result = await _commands.ExecuteAsync(context, argPos, _services);
|
||||
if (result.CommandError != null)
|
||||
switch(result.CommandError)
|
||||
{
|
||||
case CommandError.BadArgCount:
|
||||
await context.Channel.SendMessageAsync(
|
||||
"Parameter count does not match any command's.");
|
||||
break;
|
||||
default:
|
||||
await context.Channel.SendMessageAsync(
|
||||
$"An error has occurred {result.ErrorReason}");
|
||||
break;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
// The following example only requires the user to either have the
|
||||
// Administrator permission in this guild or own the bot application.
|
||||
[RequireUserPermission(GuildPermission.Administrator, Group = "Permission")]
|
||||
[RequireOwner(Group = "Permission")]
|
||||
public class AdminModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
[Command("ban")]
|
||||
public Task BanAsync(IUser user) => Context.Guild.AddBanAsync(user);
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
[RequireOwner]
|
||||
[Command("echo")]
|
||||
public Task EchoAsync(string input) => ReplyAsync(input);
|
||||
@@ -0,0 +1,33 @@
|
||||
using System;
|
||||
using System.Linq;
|
||||
using System.Threading.Tasks;
|
||||
using Discord.Commands;
|
||||
using Discord.WebSocket;
|
||||
|
||||
// Inherit from PreconditionAttribute
|
||||
public class RequireRoleAttribute : PreconditionAttribute
|
||||
{
|
||||
// Create a field to store the specified name
|
||||
private readonly string _name;
|
||||
|
||||
// Create a constructor so the name can be specified
|
||||
public RequireRoleAttribute(string name) => _name = name;
|
||||
|
||||
// Override the CheckPermissions method
|
||||
public override Task<PreconditionResult> CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services)
|
||||
{
|
||||
// Check if this user is a Guild User, which is the only context where roles exist
|
||||
if (context.User is SocketGuildUser gUser)
|
||||
{
|
||||
// If this command was executed by a user with the appropriate role, return a success
|
||||
if (gUser.Roles.Any(r => r.Name == _name))
|
||||
// Since no async work is done, the result has to be wrapped with `Task.FromResult` to avoid compiler errors
|
||||
return Task.FromResult(PreconditionResult.FromSuccess());
|
||||
// Since it wasn't, fail
|
||||
else
|
||||
return Task.FromResult(PreconditionResult.FromError($"You must have a role named {_name} to run this command."));
|
||||
}
|
||||
else
|
||||
return Task.FromResult(PreconditionResult.FromError("You must be in a guild to run this command."));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
public class CommandHandler
|
||||
{
|
||||
private readonly CommandService _commands;
|
||||
private readonly DiscordSocketClient _client;
|
||||
private readonly IServiceProvider _services;
|
||||
|
||||
public CommandHandler(CommandService commands, DiscordSocketClient client, IServiceProvider services)
|
||||
{
|
||||
_commands = commands;
|
||||
_client = client;
|
||||
_services = services;
|
||||
}
|
||||
|
||||
public async Task SetupAsync()
|
||||
{
|
||||
_client.MessageReceived += CommandHandleAsync;
|
||||
|
||||
// Add BooleanTypeReader to type read for the type "bool"
|
||||
_commands.AddTypeReader(typeof(bool), new BooleanTypeReader());
|
||||
|
||||
// Then register the modules
|
||||
await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
|
||||
}
|
||||
|
||||
public async Task CommandHandleAsync(SocketMessage msg)
|
||||
{
|
||||
// ...
|
||||
}
|
||||
}
|
||||
17
docs/guides/text_commands/samples/typereaders/typereader.cs
Normal file
17
docs/guides/text_commands/samples/typereaders/typereader.cs
Normal file
@@ -0,0 +1,17 @@
|
||||
// Please note that the library already supports type reading
|
||||
// primitive types such as bool. This example is merely used
|
||||
// to demonstrate how one could write a simple TypeReader.
|
||||
using Discord;
|
||||
using Discord.Commands;
|
||||
|
||||
public class BooleanTypeReader : TypeReader
|
||||
{
|
||||
public override Task<TypeReaderResult> ReadAsync(ICommandContext context, string input, IServiceProvider services)
|
||||
{
|
||||
bool result;
|
||||
if (bool.TryParse(input, out result))
|
||||
return Task.FromResult(TypeReaderResult.FromSuccess(result));
|
||||
|
||||
return Task.FromResult(TypeReaderResult.FromError(CommandError.ParseFailed, "Input could not be parsed as a boolean."));
|
||||
}
|
||||
}
|
||||
70
docs/guides/text_commands/typereaders.md
Normal file
70
docs/guides/text_commands/typereaders.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
uid: Guides.TextCommands.TypeReaders
|
||||
title: Type Readers
|
||||
---
|
||||
|
||||
# Type Readers
|
||||
|
||||
Type Readers allow you to parse different types of arguments in
|
||||
your commands.
|
||||
|
||||
By default, the following Types are supported arguments:
|
||||
|
||||
* `bool`
|
||||
* `char`
|
||||
* `sbyte`/`byte`
|
||||
* `ushort`/`short`
|
||||
* `uint`/`int`
|
||||
* `ulong`/`long`
|
||||
* `float`, `double`, `decimal`
|
||||
* `string`
|
||||
* `enum`
|
||||
* `DateTime`/`DateTimeOffset`/`TimeSpan`
|
||||
* Any nullable value-type (e.g. `int?`, `bool?`)
|
||||
* Any implementation of `IChannel`/`IMessage`/`IUser`/`IRole`
|
||||
|
||||
## Creating a Type Reader
|
||||
|
||||
To create a `TypeReader`, create a new class that imports @Discord and
|
||||
@Discord.Commands and ensure the class inherits from
|
||||
@Discord.Commands.TypeReader. Next, satisfy the `TypeReader` class by
|
||||
overriding the [ReadAsync] method.
|
||||
|
||||
Inside this Task, add whatever logic you need to parse the input
|
||||
string.
|
||||
|
||||
If you are able to successfully parse the input, return
|
||||
[TypeReaderResult.FromSuccess] with the parsed input, otherwise return
|
||||
[TypeReaderResult.FromError] and include an error message if
|
||||
necessary.
|
||||
|
||||
> [!NOTE]
|
||||
> Visual Studio can help you implement missing members
|
||||
> from the abstract class by using the "Implement Abstract Class"
|
||||
> IntelliSense hint.
|
||||
|
||||
[TypeReaderResult]: xref:Discord.Commands.TypeReaderResult
|
||||
[TypeReaderResult.FromSuccess]: xref:Discord.Commands.TypeReaderResult.FromSuccess*
|
||||
[TypeReaderResult.FromError]: xref:Discord.Commands.TypeReaderResult.FromError*
|
||||
[ReadAsync]: xref:Discord.Commands.TypeReader.ReadAsync*
|
||||
|
||||
### Example - Creating a Type Reader
|
||||
|
||||
[!code-csharp[TypeReaders](samples/typereaders/typereader.cs)]
|
||||
|
||||
## Registering a Type Reader
|
||||
|
||||
TypeReaders are not automatically discovered by the Command Service
|
||||
and must be explicitly added.
|
||||
|
||||
To register a TypeReader, invoke [CommandService.AddTypeReader].
|
||||
|
||||
> [!IMPORTANT]
|
||||
> TypeReaders must be added prior to module discovery, otherwise your
|
||||
> TypeReaders may not work!
|
||||
|
||||
[CommandService.AddTypeReader]: xref:Discord.Commands.CommandService.AddTypeReader*
|
||||
|
||||
### Example - Adding a Type Reader
|
||||
|
||||
[!code-csharp[Adding TypeReaders](samples/typereaders/typereader-register.cs)]
|
||||
Reference in New Issue
Block a user