Documentation Overhaul (#1161)
* Add XML docs
* Clean up style switcher
* Squash commits on branch docs/faq-n-patches
* Fix broken theme selector
* Add local image embed instruction
* Add a bunch of XML docs
* Add a bunch of XML docs
* Fix broken search
+ DocFX by default ships with an older version of jQuery, switching to a newer version confuses parts of the DocFX Javascript.
* Minor fixes for CONTRIBUTING.md and README.md
* Clean up filterConfig.yml
+ New config exposes Discord.Net namespace since it has several common public exceptions that may be helpful to users
* Add XML docs
* Read token from Environment Variable instead of hardcode
* Add XMLDocs
* Compress some assets & add OAuth2 URL generator
* Fix sample link & add missing pictures
* Add tag examples
* Fix embed docs consistency
* Add details regarding userbot support
* Add XML Docs
* Add XML Docs
* Add XML Docs
* Minor fixes in documentations
+ Fix unescaped '<'
+ Fix typo
* Fix seealso for preconditions and add missing descriptions
* Add missing exceptions
* Document exposed TypeReaders
* Fix letter-casing for files
* Add 'last modified' plugin
Source: https://github.com/Still34/DocFx.Plugin.LastModified
Licensed under MIT License
* XML Docs
* Fix minor consistencies & redundant impl
* Add properties examples to overwrite
* Fix missing Username prop
* Add warning for bulk-delete endpoint
* Replace note block
* Add BaseSocketClient docs
* Add XML docs
* Replace langword null to code block null instead
- Because DocFX sucks at rendering langword
* Replace all langword placements with code block
* Add more IGuild docs
* Add details to SpotifyGame
* Initial proofread of the articles
* Add explanation for RunMode
* Add event docs
- MessageReceived
- ChannelUpdated/Destroyed/Created
* Fix light theme link color
* Fix xml docs error
* Add partial documentation for audit log impl
* Add documentation for some REST-based objects
* Add partial documentation for audit log objects
* Add more XML comments to quotation mark alias map stuff, including an example
* Add reference to CommandServiceConfig from the util docs'
* Add explanation that if " is removed then it wont work
* Fix missing service provider in example
* Add documentation for new INestedChannel
* Add documentation
* Add documentation for new API version & few events
* Revise guide paragraphs/samples
+ Fix various formatting.
+ Provide a more detailed walkthrough for dependency injection.
+ Add C# note at intro.
* Fix typos & formatting
* Improve group module example
* Small amount to see if I'm doing it right
* Remove/cleanup redundant variables
* Fix EnterTypingState impl for doc inheritance
* Fix Test to resolve changes made in 15b58e
* Improve precondition documentation
+ Add precondition usage sample
+ Add precondition group usage sample
+ Move precondition samples to its own sample folder
* Move samples to individual folders
* Clarify token source
* Cleanup styling of README.md for docs
* Replace InvalidPathChars for NS1.3
* InvalidPathChars does not exist in NS1.3; replaced with GetInvalidPathChars instead.
* Add a missing change for 2c7cc738
* Update LastModified to v1.1.0 & add license
* Rewrite installation page for Core 2.1
* Fix anchor link
* Bump post-processor to v1.1.1
* Add fixes to partial file & add license
* Moved theme-switcher code to scripts partial file
+ Add author's MIT license to featherlight javascript
* Remove unused bootstrap plugin
* Bump LastModified plugin
* Changed the path from 'lastmodified' to 'last-modified' for consistency
* Cleanup README & Contribution guide
* Changes to last pr
* Fix GetCategoryAsync docs
* Proofread and cleanup articles
* Change passive voice in "Get Started" to active
* Fix improper preposition in Commands Introduction page
* Fix minor grammar mistakes in "Your First Bot" (future tense -> present tense/subjunctive mood -> indicative mood/proper noun casing/incorrect noun/add missing article)
* Fix minor grammar mistakes in "Installation" (missing article)
* no hablo ingles
* Try try try again
* I'm sure you're having as much fun as I am
* Cleanup TOC & fix titles
* Improve styling
+ Change title font to Noto Sans
+ Add materialized design for commit message box
* Add DescriptionGenerator plugin
* Add nightly section for clarification
* Fix typos in Nightlies & Post-execution
* Bump DescriptionGenerator to v1.1.0
+ This build adds the functionality of generating managed references' summary into the description tag.
* Initial emoji article draft
* Add 'additional information' section for emoji article
* Add cosmetic changes to the master css
* Alter info box color
+ Add transition to article content
* Add clarification in the emoji article
* Emphasize that normal emoji string will not translate to its Unicode representation.
* Clean up or add some of the samples featured in the article.
+ Add emoji/emote declaration section for clarification.
+ Add WebSocket emote sample.
- Remove inconsistent styling ('wacky memes' proves to be too out of place).
* Improve readability for nightlies article
* Move 'Bundled Preconditions' section
* Bump LastModified to fix UTC DateTime parsing
* Add langwordMapping.yml
* Add XML docs
* Add VSC workspace rule
* The root workspace limits the ruler to 120 characters for member documentations and excludes folders such as 'samples' and 'docs'.
* The docs workspace limits the ruler to 70 characters for standard conceptual article to comply with documentation's CONTRIBUTING.md rule, and excludes temprorary folders created by DocFX.
* Update CONTRIBUTING.md
* Add documentation style rule
* Fix styling of several member documentation
* Fix ' />' caused by Agent Smith oddities
* Fix styling to be more specific about the mention of IDs
* Fix exception summary to comply with official Microsoft Docs style
* References
https://docs.microsoft.com/en-us/dotnet/api/system.argumentnullexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.platformnotsupportedexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.badimageformatexception?view=netframework-4.7.2
* Add XML documentations
* Shift color return docs
* Fix minor docs
* Added documentation for SocketDMChannel, SocketGuildChannel, and SocketTextChannel
* Add XML docs
* Corrections to SocketGuildChannel
* Corrections to SocketTextChannel
* Corrections to SocketDMChannel
* Swapped out 'id' for 'snowflake identifier
* Swapped out 'id' for 'snowflake identifier'
* SocketDMChannel amendments
* SocketGuildChannel amendments
* SocketTextChannel amendments
* Add XML docs & patch return types
+ Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com
References:
https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___
And many more other asynchronous method documentations featured in the latest BCL.
* Added documentation for many audit log data types, fixed vowel indefinite articles
* Change audit log data types to start with 'Contains' (verb) instead of an article
* Fix some documentation issues and document some more audit log data types
* Fix English posession
* Add XML doc
* Documented two more types
* Documented RoleCreateAuditLogData
* Document remaining audit log data types
* Added RestDMChannel documentation
* Added RestGuildChannel documentation
* Added RestTextChannel documentation
* Added RestVoiceChannel documentation
* Added RestUser documentation
* Added RestRole documentation
* Added RestMessage documentation
* Slightly better wording
* Contains -> Contains a piece of (describe article)
* [EN] Present perf. -> past perf.
* Add XML docs
* Fix arrow alignment
* Clarify supported nullable type
* Fixed a typo in ISnowflakeEntity
* Added RestUser Documentation
* Added RestInvite documentation
* Add XML docs & minor optimizations
* Minor optimization for doc rendering
* Rollback font optimization changes
* Amendments to RestUser
* Added SocketDMChannel documentation
* Added RestDMChannel documentation
* Added RestGuild documentation
* Adjustment to SocketDMChannel
* Added minimal descriptions from the API documentation for Integration types
* Added obsolete mention to the ReadMessages flag.
* Added remarks about 2FA requirement for guild permissions
* Added xmldoc for GuildPermission methods
* Added xml doc for ToAllowList and ToDenyList
* Added specification of how the bits of the color raw value are packed
* Added discord API documentation to IConnection interface
* I can spell :^)
* Fix whitespace in ChannelPermission
* fix spacing of values in guildpermission
* Made changes to get field descriptions from feedback, added returns tag to IConnection
* Added property get standard for IntegrationAccount
* Added property get pattern to xml docs and identical returns tag.
* Change all color class references to struct
...because it isn't a class.
* Add XML docs
* Rewrote the returns tags in IGuildIntegration, removed the ones I was unsure about.
* Rewrote the rest of the returns tags
* Amendments
* Cleanup doc for c1d78189
* Added types to <returns> tags where missing
* Added second sample for adding reactions
* Added some class summaries
* Missed a period
* Amendments
* restored the removed line break
* Removed unnecessary see tag
* Use consistent quotation marks around subscribers, the name for these users are dependant on the source of where they are integrated from (youtube or twitch), so we should not use a name that is specific to one platform
* Add <remarks> tag to the IGuildIntegration xmldocs
* Fix grammar issue
* Update DescriptionGenerator
* Cleanup of https://github.com/Still34/Discord.Net/pull/8
* Cleanup previous PR
* Fix for misleading behaviour in the emoji guide
+ Original lines stated that sending a emoji wrapped in colon will not be parsed, but that was incorrect; replaced with reactions instead of sending messages as the example
* Add strings for dictionary in DotSettings
* Add XML docs
* Fix lots of typos in comments
+ Geez, I didn't know there were so many.
* Add XML docs & rewrite GetMessagesAsync docs
This commit rewrites the remarks section of GetMessagesAsync, as well as adding examples to several methods.
* Update 'Your First Bot'
+ This commit reflects the new changes made to the Discord Application Developer Portal after its major update
* Initial optimization for DocFX render & add missing files
* Add examples in message methods
* Cleanup https://github.com/RogueException/Discord.Net/pull/1128
* Fix first bot note
* Cleanup FAQ structure
* Add XML docs
* Update docfx plugins
* Fix navbar collapsing issue
* Fix broken xref
* Cleanup FAQ section
+ Add introductory paragraphs to each FAQ section.
+ Add 'missing dependency' entry to commands FAQ.
* Split commands FAQ to 'General' and 'DI' sections.
* Cleanup https://github.com/RogueException/Discord.Net/pull/1139
* Fix missing namespace
* Add missing highlighting css for the light theme
* Add additional clarification for installing packages
* Add indentation to example for clarity
* Cleanup several articles to be more human-friendly and easier to read
* Remove RPC-related notes
* Cleanup slow-mode-related documentation strings
* Add an additional note about cross-guild emote usage
* Add CreateTextChannel sample
* Add XMLDocs
This commit is contained in:
Still Hsu
123
docs/faq/basics/basic-operations.md
Normal file
123
docs/faq/basics/basic-operations.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
uid: FAQ.Basics.BasicOp
|
||||
title: Questions about Basic Operations
|
||||
---
|
||||
|
||||
# Basic Operations Questions
|
||||
|
||||
In the following section, you will find commonly asked questions and
|
||||
answers regarding basic usage of the library, as well as
|
||||
language-specific tips when using this library.
|
||||
|
||||
## How should I safely check a type?
|
||||
|
||||
> [!WARNING]
|
||||
> Direct casting (e.g., `(Type)type`) is **the least recommended**
|
||||
> way of casting, as it *can* throw an [InvalidCastException]
|
||||
> when the object isn't the desired type.
|
||||
>
|
||||
> Please refer to [this post] for more details.
|
||||
|
||||
In Discord.Net, the idea of polymorphism is used throughout. You may
|
||||
need to cast the object as a certain type before you can perform any
|
||||
action.
|
||||
|
||||
A good and safe casting example:
|
||||
|
||||
[!code-csharp[Casting](samples/cast.cs)]
|
||||
|
||||
[InvalidCastException]: https://docs.microsoft.com/en-us/dotnet/api/system.invalidcastexception
|
||||
[this post]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/types/how-to-safely-cast-by-using-as-and-is-operators
|
||||
|
||||
## How do I send a message?
|
||||
|
||||
> [!TIP]
|
||||
> The [GetChannel] method by default returns an [IChannel], allowing
|
||||
> channel types such as [IVoiceChannel], [ICategoryChannel]
|
||||
> to be returned; consequently, you cannot send a message
|
||||
> to channels like those.
|
||||
|
||||
Any implementation of [IMessageChannel] has a [SendMessageAsync]
|
||||
method. You can get the channel via [GetChannel] under the client.
|
||||
Remember, when using Discord.Net, polymorphism is a common recurring
|
||||
theme. This means an object may take in many shapes or form, which
|
||||
means casting is your friend. You should attempt to cast the channel
|
||||
as an [IMessageChannel] or any other entity that implements it to be
|
||||
able to message.
|
||||
|
||||
[SendMessageAsync]: xref:Discord.IMessageChannel.SendMessageAsync*
|
||||
[GetChannel]: xref:Discord.WebSocket.DiscordSocketClient.GetChannel*
|
||||
|
||||
## How can I tell if a message is from X, Y, Z channel?
|
||||
|
||||
You may check the message channel type. Visit [Glossary] to see the
|
||||
various types of channels.
|
||||
|
||||
[Glossary]: xref:FAQ.Glossary#message-channels
|
||||
|
||||
## How can I get the guild from a message?
|
||||
|
||||
There are 2 ways to do this. You can do either of the following,
|
||||
|
||||
1. Cast the user as an [IGuildUser] and use its [IGuild] property.
|
||||
2. Cast the channel as an [IGuildChannel] and use its [IGuild] property.
|
||||
|
||||
## How do I add hyperlink text to an embed?
|
||||
|
||||
Embeds can use standard [markdown] in the description field as well
|
||||
as in field values. With that in mind, links can be added with
|
||||
`[text](link)`.
|
||||
|
||||
[markdown]: https://support.discordapp.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline-
|
||||
|
||||
## How do I add reactions to a message?
|
||||
|
||||
Any entity that implements [IUserMessage] has an [AddReactionAsync]
|
||||
method. This method expects an [IEmote] as a parameter.
|
||||
In Discord.Net, an Emote represents a custom-image emote, while an
|
||||
Emoji is a Unicode emoji (standard emoji). Both [Emoji] and [Emote]
|
||||
implement [IEmote] and are valid options.
|
||||
|
||||
# [Adding a reaction to another message](#tab/emoji-others)
|
||||
|
||||
[!code-csharp[Emoji](samples/emoji-others.cs)]
|
||||
|
||||
# [Adding a reaction to a sent message](#tab/emoji-self)
|
||||
|
||||
[!code-csharp[Emoji](samples/emoji-self.cs)]
|
||||
|
||||
***
|
||||
|
||||
[AddReactionAsync]: xref:Discord.IUserMessage.AddReactionAsync*
|
||||
|
||||
## What is a "preemptive rate limit?"
|
||||
|
||||
A preemptive rate limit is Discord.Net's way of telling you to slow
|
||||
down before you get hit by the real rate limit. Hitting a real rate
|
||||
limit might prevent your entire client from sending any requests for
|
||||
a period of time. This is calculated based on the HTTP header
|
||||
returned by a Discord response.
|
||||
|
||||
## Why am I getting so many preemptive rate limits when I try to add more than one reactions?
|
||||
|
||||
This is due to how HTML header works, mistreating
|
||||
0.25sec/action to 1sec. This causes the lib to throw preemptive rate
|
||||
limit more frequently than it should for methods such as adding
|
||||
reactions.
|
||||
|
||||
## Can I opt-out of preemptive rate limits?
|
||||
|
||||
Unfortunately, not at the moment. See [#401](https://github.com/RogueException/Discord.Net/issues/401).
|
||||
|
||||
[IChannel]: xref:Discord.IChannel
|
||||
[ICategoryChannel]: xref:Discord.ICategoryChannel
|
||||
[IGuildChannel]: xref:Discord.IGuildChannel
|
||||
[ITextChannel]: xref:Discord.ITextChannel
|
||||
[IGuild]: xref:Discord.IGuild
|
||||
[IVoiceChannel]: xref:Discord.IVoiceChannel
|
||||
[IGuildUser]: xref:Discord.IGuildUser
|
||||
[IMessageChannel]: xref:Discord.IMessageChannel
|
||||
[IUserMessage]: xref:Discord.IUserMessage
|
||||
[IEmote]: xref:Discord.IEmote
|
||||
[Emote]: xref:Discord.Emote
|
||||
[Emoji]: xref:Discord.Emoji
|
||||
66
docs/faq/basics/client-basics.md
Normal file
66
docs/faq/basics/client-basics.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
uid: FAQ.Basics.ClientBasics
|
||||
title: Basic Questions about Client
|
||||
---
|
||||
|
||||
# Client Basics Questions
|
||||
|
||||
In the following section, you will find commonly asked questions and
|
||||
answers about common issues that you may face when utilizing the
|
||||
various clients offered by the library.
|
||||
|
||||
## My client keeps returning 401 upon logging in!
|
||||
|
||||
> [!WARNING]
|
||||
> Userbot/selfbot (logging in with a user token) is no
|
||||
> longer supported with this library starting from 2.0, as
|
||||
> logging in under a user account may result in account termination.
|
||||
>
|
||||
> For more information, see issue [827] & [958], as well as the official
|
||||
> [Discord API Terms of Service].
|
||||
|
||||
There are few possible reasons why this may occur.
|
||||
|
||||
1. You are not using the appropriate [TokenType]. If you are using a
|
||||
bot account created from the Discord Developer portal, you should
|
||||
be using `TokenType.Bot`.
|
||||
2. You are not using the correct login credentials. Please keep in
|
||||
mind that a token is **different** from a *client secret*.
|
||||
|
||||
[TokenType]: xref:Discord.TokenType
|
||||
[827]: https://github.com/RogueException/Discord.Net/issues/827
|
||||
[958]: https://github.com/RogueException/Discord.Net/issues/958
|
||||
[Discord API Terms of Service]: https://discordapp.com/developers/docs/legal
|
||||
|
||||
## How do I do X, Y, Z when my bot connects/logs on? Why do I get a `NullReferenceException` upon calling any client methods after connect?
|
||||
|
||||
Your bot should **not** attempt to interact in any way with
|
||||
guilds/servers until the [Ready] event fires. When the bot
|
||||
connects, it first has to download guild information from
|
||||
Discord for you to get access to any server
|
||||
information; the client is not ready at this point.
|
||||
|
||||
Technically, the [GuildAvailable] event fires once the data for a
|
||||
particular guild has downloaded; however, it is best to wait for all
|
||||
guilds to be downloaded. Once all downloads are complete, the [Ready]
|
||||
event is triggered, then you can proceed to do whatever you like.
|
||||
|
||||
[Ready]: xref:Discord.WebSocket.DiscordSocketClient.Ready
|
||||
[GuildAvailable]: xref:Discord.WebSocket.BaseSocketClient.GuildAvailable
|
||||
|
||||
## How do I get a message's previous content when that message is edited?
|
||||
|
||||
If you need to do anything with messages (e.g., checking Reactions,
|
||||
checking the content of edited/deleted messages), you must set the
|
||||
[MessageCacheSize] in your [DiscordSocketConfig] settings in order to
|
||||
use the cached message entity. Read more about it [here](xref:Guides.Concepts.Events#cacheable).
|
||||
|
||||
1. Message Cache must be enabled.
|
||||
2. Hook the MessageUpdated event. This event provides a *before* and
|
||||
*after* object.
|
||||
3. Only messages received *after* the bot comes online will be
|
||||
available in the cache.
|
||||
|
||||
[MessageCacheSize]: xref:Discord.WebSocket.DiscordSocketConfig.MessageCacheSize
|
||||
[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
|
||||
[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient.MessageUpdated
|
||||
79
docs/faq/basics/getting-started.md
Normal file
79
docs/faq/basics/getting-started.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
uid: FAQ.Basics.GetStarted
|
||||
title: Beginner Questions / How to Get Started
|
||||
---
|
||||
|
||||
# Basic Concepts / Getting Started
|
||||
|
||||
In this following section, you will find commonly asked questions and
|
||||
answers about how to get started with Discord.Net, as well as basic
|
||||
introduction to the Discord API ecosystem.
|
||||
|
||||
## How do I add my bot to my server/guild?
|
||||
|
||||
You can do so by using the [permission calculator] provided
|
||||
by [FiniteReality].
|
||||
This tool allows you to set permissions that the bot will be assigned
|
||||
with, and invite the bot into your guild. With this method, bots will
|
||||
also be assigned a unique role that a regular user cannot use; this
|
||||
is what we call a `Managed` role. Because you cannot assign this
|
||||
role to any other users, it is much safer than creating a single
|
||||
role which, intentionally or not, can be applied to other users
|
||||
to escalate their privilege.
|
||||
|
||||
[FiniteReality]: https://github.com/FiniteReality/permissions-calculator
|
||||
[permission calculator]: https://finitereality.github.io/permissions-calculator
|
||||
|
||||
## What is a token?
|
||||
|
||||
A token is a credential used to log into an account. This information
|
||||
should be kept **private** and for your eyes only. Anyone with your
|
||||
token can log into your account. This risk applies to both user
|
||||
and bot accounts. That also means that you should **never** hardcode
|
||||
your token or add it into source control, as your identity may be
|
||||
stolen by scrape bots on the internet that scours through
|
||||
constantly to obtain a token.
|
||||
|
||||
## What is a client/user/object ID?
|
||||
|
||||
Each user and object on Discord has its own snowflake ID generated
|
||||
based on various conditions.
|
||||
|
||||
|
||||
|
||||
Anyone can see the ID; it is public. It is merely used to
|
||||
identify an object in the Discord ecosystem. Many things in the
|
||||
Discord ecosystem require an ID to retrieve or identify the said
|
||||
object.
|
||||
|
||||
There are 2 common ways to obtain the said ID.
|
||||
|
||||
### [Discord Developer Mode](#tab/dev-mode)
|
||||
|
||||
By enabling the developer mode you can right click on most objects
|
||||
to obtain their snowflake IDs (please note that this may not apply to
|
||||
all objects, such as role IDs, or DM channel IDs).
|
||||
|
||||
|
||||
|
||||
### [Escape Character](#tab/escape-char)
|
||||
|
||||
You can escape an object by using `\` in front the object in the
|
||||
Discord client. For example, when you do `\@Example#1234` in chat,
|
||||
it will return the user ID of the aforementioned user.
|
||||
|
||||
|
||||
|
||||
***
|
||||
|
||||
## How do I get the role ID?
|
||||
|
||||
> [!WARNING]
|
||||
> Right-clicking on the role and copying the ID will **not** work.
|
||||
> This will only copy the message ID.
|
||||
|
||||
Several common ways to do this:
|
||||
|
||||
1. Make the role mentionable and mention the role, and escape it
|
||||
using the `\` character in front.
|
||||
2. Inspect the roles collection within the guild via your debugger.
|
||||
BIN
docs/faq/basics/images/dev-mode.png
Normal file
BIN
docs/faq/basics/images/dev-mode.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
BIN
docs/faq/basics/images/mention-escape.png
Normal file
BIN
docs/faq/basics/images/mention-escape.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
docs/faq/basics/images/snowflake.png
Normal file
BIN
docs/faq/basics/images/snowflake.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
15
docs/faq/basics/samples/cast.cs
Normal file
15
docs/faq/basics/samples/cast.cs
Normal file
@@ -0,0 +1,15 @@
|
||||
public async Task MessageReceivedHandler(SocketMessage msg)
|
||||
{
|
||||
// Option 1:
|
||||
// Using the `as` keyword, which will return `null` if the object isn't the desired type.
|
||||
var usermsg = msg as SocketUserMessage;
|
||||
// We bail when the message isn't the desired type.
|
||||
if (msg == null) return;
|
||||
|
||||
// Option 2:
|
||||
// Using the `is` keyword to cast (C#7 or above only)
|
||||
if (msg is SocketUserMessage usermsg)
|
||||
{
|
||||
// Do things
|
||||
}
|
||||
}
|
||||
18
docs/faq/basics/samples/emoji-others.cs
Normal file
18
docs/faq/basics/samples/emoji-others.cs
Normal file
@@ -0,0 +1,18 @@
|
||||
// bail if the message is not a user one (system messages cannot have reactions)
|
||||
var usermsg = msg as IUserMessage;
|
||||
if (usermsg == null) return;
|
||||
|
||||
// standard Unicode emojis
|
||||
Emoji emoji = new Emoji("👍");
|
||||
// or
|
||||
// Emoji emoji = new Emoji("\uD83D\uDC4D");
|
||||
|
||||
// custom guild emotes
|
||||
Emote emote = Emote.Parse("<:dotnet:232902710280716288>");
|
||||
// using Emote.TryParse may be safer in regards to errors being thrown;
|
||||
// please note that the method does not verify if the emote exists,
|
||||
// it simply creates the Emote object for you.
|
||||
|
||||
// add the reaction to the message
|
||||
await usermsg.AddReactionAsync(emoji);
|
||||
await usermsg.AddReactionAsync(emote);
|
||||
17
docs/faq/basics/samples/emoji-self.cs
Normal file
17
docs/faq/basics/samples/emoji-self.cs
Normal file
@@ -0,0 +1,17 @@
|
||||
// capture the message you're sending in a variable
|
||||
var msg = await channel.SendMessageAsync("This will have reactions added.");
|
||||
|
||||
// standard Unicode emojis
|
||||
Emoji emoji = new Emoji("👍");
|
||||
// or
|
||||
// Emoji emoji = new Emoji("\uD83D\uDC4D");
|
||||
|
||||
// custom guild emotes
|
||||
Emote emote = Emote.Parse("<:dotnet:232902710280716288>");
|
||||
// using Emote.TryParse may be safer in regards to errors being thrown;
|
||||
// please note that the method does not verify if the emote exists,
|
||||
// it simply creates the Emote object for you.
|
||||
|
||||
// add the reaction to the message
|
||||
await msg.AddReactionAsync(emoji);
|
||||
await msg.AddReactionAsync(emote);
|
||||
54
docs/faq/commands/dependency-injection.md
Normal file
54
docs/faq/commands/dependency-injection.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
uid: FAQ.Commands.DI
|
||||
title: Questions about Dependency Injection with Commands
|
||||
---
|
||||
|
||||
# Dependency-injection-related Questions
|
||||
|
||||
In the following section, you will find common questions and answers
|
||||
to utilizing dependency injection with @Discord.Commands, as well as
|
||||
common troubleshooting steps regarding DI.
|
||||
|
||||
## What is a service? Why does my module not hold any data after execution?
|
||||
|
||||
In Discord.Net, modules are created similarly to ASP.NET, meaning
|
||||
that they have a transient nature; modules are spawned whenever a
|
||||
request is received, and are killed from memory when the execution
|
||||
finishes. In other words, you cannot store persistent
|
||||
data inside a module. Consider using a service if you wish to
|
||||
workaround this.
|
||||
|
||||
Service is often used to hold data externally so that they persist
|
||||
throughout execution. Think of it like a chest that holds
|
||||
whatever you throw at it that won't be affected by anything unless
|
||||
you want it to. Note that you should also learn Microsoft's
|
||||
implementation of [Dependency Injection] \([video]) before proceeding,
|
||||
as well as how it works in [Discord.Net](xref:Guides.Commands.DI#usage-in-modules).
|
||||
|
||||
A brief example of service and dependency injection can be seen below.
|
||||
|
||||
[!code-csharp[DI](samples/DI.cs)]
|
||||
|
||||
[Dependency Injection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection
|
||||
[video]: https://www.youtube.com/watch?v=QtDTfn8YxXg
|
||||
|
||||
## Why is my `CommandService` complaining about a missing dependency?
|
||||
|
||||
If you encounter an error similar to `Failed to create MyModule,
|
||||
dependency MyExternalDependency was not found.`, you may have
|
||||
forgotten to add the external dependency to the dependency container.
|
||||
|
||||
Starting from Discord.Net 2.0, all dependencies required by each
|
||||
module must be present when the module is loaded into the
|
||||
[CommandService]. This means when loading the module, you must pass a
|
||||
valid [IServiceProvider] with the dependency loaded before the module
|
||||
can be successfully registered.
|
||||
|
||||
For example, if your module, `MyModule`, requests a `DatabaseService`
|
||||
in its constructor, the `DatabaseService` must be present in the
|
||||
[IServiceProvider] when registering `MyModule`.
|
||||
|
||||
[!code-csharp[Missing Dependencies](samples/missing-dep.cs)]
|
||||
|
||||
[IServiceProvider]: xref:System.IServiceProvider
|
||||
[CommandService]: xref:Discord.Commands.CommandService
|
||||
142
docs/faq/commands/general.md
Normal file
142
docs/faq/commands/general.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
uid: FAQ.Commands.General
|
||||
title: General Questions about Commands
|
||||
---
|
||||
|
||||
# Command-related Questions
|
||||
|
||||
In the following section, you will find commonly asked questions and
|
||||
answered regarding general command usage when using @Discord.Commands.
|
||||
|
||||
## How can I restrict some of my commands so only specific users can execute them?
|
||||
|
||||
Based on how you want to implement the restrictions, you can use the
|
||||
built-in [RequireUserPermission] precondition, which allows you to
|
||||
restrict the command based on the user's current permissions in the
|
||||
guild or channel (*e.g., `GuildPermission.Administrator`,
|
||||
`ChannelPermission.ManageMessages`*).
|
||||
|
||||
If, however, you wish to restrict the commands based on the user's
|
||||
role, you can either create your custom precondition or use
|
||||
Joe4evr's [Preconditions Addons] that provides a few custom
|
||||
preconditions that aren't provided in the stock library.
|
||||
Its source can also be used as an example for creating your
|
||||
custom preconditions.
|
||||
|
||||
[RequireUserPermission]: xref:Discord.Commands.RequireUserPermissionAttribute
|
||||
[Preconditions Addons]: https://github.com/Joe4evr/Discord.Addons/tree/master/src/Discord.Addons.Preconditions
|
||||
|
||||
## Why am I getting an error about `Assembly.GetEntryAssembly`?
|
||||
|
||||
You may be confusing @Discord.Commands.CommandService.AddModulesAsync*
|
||||
with @Discord.Commands.CommandService.AddModuleAsync*. The former
|
||||
is used to add modules via the assembly, while the latter is used to
|
||||
add a single module.
|
||||
|
||||
## What does [Remainder] do in the command signature?
|
||||
|
||||
The [RemainderAttribute] leaves the string unparsed, meaning you
|
||||
do not have to add quotes around the text for the text to be
|
||||
recognized as a single object. Please note that if your method has
|
||||
multiple parameters, the remainder attribute can only be applied to
|
||||
the last parameter.
|
||||
|
||||
[!code-csharp[Remainder](samples/Remainder.cs)]
|
||||
|
||||
[RemainderAttribute]: xref:Discord.Commands.RemainderAttribute
|
||||
|
||||
## Discord.Net keeps saying that a `MessageReceived` handler is blocking the gateway, what should I do?
|
||||
|
||||
By default, the library warns the user about any long-running event
|
||||
handler that persists for **more than 3 seconds**. Any event
|
||||
handlers that are run on the same thread as the gateway task, the task
|
||||
in charge of keeping the connection alive, may block the processing of
|
||||
heartbeat, and thus terminating the connection.
|
||||
|
||||
In this case, the library detects that a `MessageReceived`
|
||||
event handler is blocking the gateway thread. This warning is
|
||||
typically associated with the command handler as it listens for that
|
||||
particular event. If the command handler is blocking the thread, then
|
||||
this **might** mean that you have a long-running command.
|
||||
|
||||
> [!NOTE]
|
||||
> In rare cases, runtime errors can also cause blockage, usually
|
||||
> associated with Mono, which is not supported by this library.
|
||||
|
||||
To prevent a long-running command from blocking the gateway
|
||||
thread, a flag called [RunMode] is explicitly designed to resolve
|
||||
this issue.
|
||||
|
||||
There are 2 main `RunMode`s.
|
||||
|
||||
1. `RunMode.Sync`
|
||||
2. `RunMode.Async`
|
||||
|
||||
`Sync` is the default behavior and makes the command to be run on the
|
||||
same thread as the gateway one. `Async` will spin the task off to a
|
||||
different thread from the gateway one.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> While specifying `RunMode.Async` allows the command to be spun off
|
||||
> to a different thread, keep in mind that by doing so, there will be
|
||||
> **potentially unwanted consequences**. Before applying this flag,
|
||||
> please consider whether it is necessary to do so.
|
||||
>
|
||||
> Further details regarding `RunMode.Async` can be found below.
|
||||
|
||||
You can set the `RunMode` either by specifying it individually via
|
||||
the `CommandAttribute` or by setting the global default with
|
||||
the [DefaultRunMode] flag under `CommandServiceConfig`.
|
||||
|
||||
# [CommandAttribute](#tab/cmdattrib)
|
||||
|
||||
[!code-csharp[Command Attribute](samples/runmode-cmdattrib.cs)]
|
||||
|
||||
# [CommandServiceConfig](#tab/cmdconfig)
|
||||
|
||||
[!code-csharp[Command Service Config](samples/runmode-cmdconfig.cs)]
|
||||
|
||||
***
|
||||
|
||||
***
|
||||
|
||||
[RunMode]: xref:Discord.Commands.RunMode
|
||||
[CommandAttribute]: xref:Discord.Commands.CommandAttribute
|
||||
[DefaultRunMode]: xref:Discord.Commands.CommandServiceConfig.DefaultRunMode
|
||||
|
||||
## How does `RunMode.Async` work, and why is Discord.Net *not* using it by default?
|
||||
|
||||
`RunMode.Async` works by spawning a new `Task` with an unawaited
|
||||
[Task.Run], essentially making the task that is used to invoke the
|
||||
command task to be finished on a different thread. This design means
|
||||
that [ExecuteAsync] will be forced to return a successful
|
||||
[ExecuteResult] regardless of the actual execution result.
|
||||
|
||||
The following are the known caveats with `RunMode.Async`,
|
||||
|
||||
1. You can potentially introduce a race condition.
|
||||
2. Unnecessary overhead caused by the [async state machine].
|
||||
3. [ExecuteAsync] will immediately return [ExecuteResult] instead of
|
||||
other result types (this is particularly important for those who wish
|
||||
to utilize [RuntimeResult] in 2.0).
|
||||
4. Exceptions are swallowed.
|
||||
|
||||
However, there are ways to remedy some of these.
|
||||
|
||||
For #3, in Discord.Net 2.0, the library introduces a new event called
|
||||
[CommandExecuted], which is raised whenever the command is
|
||||
**successfully executed**. This event will be raised regardless of
|
||||
the `RunMode` type and will return the appropriate execution result.
|
||||
|
||||
For #4, exceptions are caught in [CommandService.Log] event under
|
||||
[LogMessage.Exception] as [CommandException].
|
||||
|
||||
[Task.Run]: https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.run
|
||||
[async state machine]: https://www.red-gate.com/simple-talk/dotnet/net-tools/c-async-what-is-it-and-how-does-it-work/
|
||||
[ExecuteAsync]: xref:Discord.Commands.CommandService.ExecuteAsync*
|
||||
[ExecuteResult]: xref:Discord.Commands.ExecuteResult
|
||||
[RuntimeResult]: xref:Discord.Commands.RuntimeResult
|
||||
[CommandExecuted]: xref:Discord.Commands.CommandService.CommandExecuted
|
||||
[CommandService.Log]: xref:Discord.Commands.CommandService.Log
|
||||
[LogMessage.Exception]: xref:Discord.LogMessage.Exception*
|
||||
[CommandException]: xref:Discord.Commands.CommandException
|
||||
28
docs/faq/commands/samples/DI.cs
Normal file
28
docs/faq/commands/samples/DI.cs
Normal file
@@ -0,0 +1,28 @@
|
||||
public class MyService
|
||||
{
|
||||
public string MyCoolString { get; set; }
|
||||
}
|
||||
public class Setup
|
||||
{
|
||||
public IServiceProvider BuildProvider() =>
|
||||
new ServiceCollection()
|
||||
.AddSingleton<MyService>()
|
||||
.BuildServiceProvider();
|
||||
}
|
||||
public class MyModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
// Inject via public settable prop
|
||||
public MyService MyService { get; set; }
|
||||
|
||||
// ...or via the module's constructor
|
||||
|
||||
// private readonly MyService _myService;
|
||||
// public MyModule (MyService myService) => _myService = myService;
|
||||
|
||||
[Command("string")]
|
||||
public Task GetOrSetStringAsync(string input)
|
||||
{
|
||||
if (string.IsNullOrEmpty(_myService.MyCoolString)) _myService.MyCoolString = input;
|
||||
return ReplyAsync(_myService.MyCoolString);
|
||||
}
|
||||
}
|
||||
20
docs/faq/commands/samples/Remainder.cs
Normal file
20
docs/faq/commands/samples/Remainder.cs
Normal file
@@ -0,0 +1,20 @@
|
||||
// Input:
|
||||
// !echo Coffee Cake
|
||||
|
||||
// Output:
|
||||
// Coffee Cake
|
||||
[Command("echo")]
|
||||
public Task EchoRemainderAsync([Remainder]string text) => ReplyAsync(text);
|
||||
|
||||
// Output:
|
||||
// CommandError.BadArgCount
|
||||
[Command("echo-hassle")]
|
||||
public Task EchoAsync(string text) => ReplyAsync(text);
|
||||
|
||||
// The message would be seen as having multiple parameters,
|
||||
// while the method only accepts one.
|
||||
// Wrapping the message in quotes solves this.
|
||||
// This way, the system knows the entire message is to be parsed as a
|
||||
// single String.
|
||||
// e.g.,
|
||||
// !echo "Coffee Cake"
|
||||
29
docs/faq/commands/samples/missing-dep.cs
Normal file
29
docs/faq/commands/samples/missing-dep.cs
Normal file
@@ -0,0 +1,29 @@
|
||||
public class MyModule : ModuleBase<SocketCommandContext>
|
||||
{
|
||||
private readonly DatabaseService _dbService;
|
||||
public MyModule(DatabaseService dbService)
|
||||
=> _dbService = dbService;
|
||||
}
|
||||
public class CommandHandler
|
||||
{
|
||||
private readonly CommandService _commands;
|
||||
private readonly IServiceProvider _services;
|
||||
public CommandHandler(DiscordSocketClient client)
|
||||
{
|
||||
_services = new ServiceCollection()
|
||||
.AddService<CommandService>()
|
||||
.AddService(client)
|
||||
// We are missing DatabaseService!
|
||||
.BuildServiceProvider();
|
||||
}
|
||||
public async Task RegisterCommandsAsync()
|
||||
{
|
||||
// ...
|
||||
// The method fails here because DatabaseService is a required
|
||||
// dependency and cannot be resolved by the dependency
|
||||
// injection service at runtime since the service is not
|
||||
// registered in this instance of _services.
|
||||
await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
|
||||
// ...
|
||||
}
|
||||
}
|
||||
7
docs/faq/commands/samples/runmode-cmdattrib.cs
Normal file
7
docs/faq/commands/samples/runmode-cmdattrib.cs
Normal file
@@ -0,0 +1,7 @@
|
||||
[Command("process", RunMode = RunMode.Async)]
|
||||
public async Task ProcessAsync(string input)
|
||||
{
|
||||
// Does heavy calculation here.
|
||||
await Task.Delay(TimeSpan.FromMinute(1));
|
||||
await ReplyAsync(input);
|
||||
}
|
||||
10
docs/faq/commands/samples/runmode-cmdconfig.cs
Normal file
10
docs/faq/commands/samples/runmode-cmdconfig.cs
Normal file
@@ -0,0 +1,10 @@
|
||||
public class Setup
|
||||
{
|
||||
private readonly CommandService _command;
|
||||
|
||||
public Setup()
|
||||
{
|
||||
var config = new CommandServiceConfig{ DefaultRunMode = RunMode.Async };
|
||||
_command = new CommandService(config);
|
||||
}
|
||||
}
|
||||
82
docs/faq/misc/glossary.md
Normal file
82
docs/faq/misc/glossary.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
uid: FAQ.Glossary
|
||||
title: Common Terminologies / Glossary
|
||||
---
|
||||
|
||||
# Glossary
|
||||
|
||||
This is an additional chapter for quick references to various common
|
||||
types that you may see within Discord.Net. To see more information
|
||||
regarding each type of object, click on the object to navigate
|
||||
to our API documentation page where you might find more explanation
|
||||
about it.
|
||||
|
||||
## Common Types
|
||||
|
||||
* A **Guild** ([IGuild]) is an isolated collection of users and
|
||||
channels, and are often referred to as "servers".
|
||||
- Example: [Discord API](https://discord.gg/jkrBmQR)
|
||||
* A **Channel** ([IChannel]) represents a generic channel.
|
||||
- Example: #dotnet_discord-net
|
||||
- See [Channel Types](#channel-types)
|
||||
|
||||
[IGuild]: xref:Discord.IGuild
|
||||
[IChannel]: xref:Discord.IChannel
|
||||
|
||||
## Channel Types
|
||||
|
||||
### Message Channels
|
||||
* A **Text Channel** ([ITextChannel]) is a message channel from a
|
||||
Guild.
|
||||
* A **DM Channel** ([IDMChannel]) is a message channel from a DM.
|
||||
* A **Group Channel** ([IGroupChannel]) is a message channel from a
|
||||
Group.
|
||||
- This is rarely used due to the bot's inability to join groups.
|
||||
* A **Private Channel** ([IPrivateChannel]) is a DM or a Group.
|
||||
* A **Message Channel** ([IMessageChannel]) can be any of the above.
|
||||
|
||||
### Misc Channels
|
||||
* A **Guild Channel** ([IGuildChannel]) is a guild channel in a guild.
|
||||
- This can be any channels that may exist in a guild.
|
||||
* A **Voice Channel** ([IVoiceChannel]) is a voice channel in a guild.
|
||||
* A **Category Channel** ([ICategoryChannel]) (2.0+) is a category that
|
||||
holds one or more sub-channels.
|
||||
* A **Nested Channel** ([INestedChannel]) (2.0+) is a channel that can
|
||||
exist under a category.
|
||||
|
||||
[INestedChannel]: xref:Discord.INestedChannel
|
||||
[IGuildChannel]: xref:Discord.IGuildChannel
|
||||
[IMessageChannel]: xref:Discord.IMessageChannel
|
||||
[ITextChannel]: xref:Discord.ITextChannel
|
||||
[IGroupChannel]: xref:Discord.IGroupChannel
|
||||
[IDMChannel]: xref:Discord.IDMChannel
|
||||
[IPrivateChannel]: xref:Discord.IPrivateChannel
|
||||
[IVoiceChannel]: xref:Discord.IVoiceChannel
|
||||
[ICategoryChannel]: xref:Discord.ICategoryChannel
|
||||
|
||||
## Emoji Types
|
||||
|
||||
* An **Emote** ([Emote]) is a custom emote from a guild.
|
||||
- Example: `<:dotnet:232902710280716288>`
|
||||
* An **Emoji** ([Emoji]) is a Unicode emoji.
|
||||
- Example: `👍`
|
||||
|
||||
[Emote]: xref:Discord.Emote
|
||||
[Emoji]: xref:Discord.Emoji
|
||||
|
||||
## Activity Types
|
||||
|
||||
* A **Game** ([Game]) refers to a user's game activity.
|
||||
* A **Rich Presence** ([RichGame]) refers to a user's detailed
|
||||
gameplay status.
|
||||
- Visit [Rich Presence Intro] on Discord docs for more info.
|
||||
* A **Streaming Status** ([StreamingGame]) refers to user's activity
|
||||
for streaming on services such as Twitch.
|
||||
* A **Spotify Status** ([SpotifyGame]) (2.0+) refers to a user's
|
||||
activity for listening to a song on Spotify.
|
||||
|
||||
[Game]: xref:Discord.Game
|
||||
[RichGame]: xref:Discord.RichGame
|
||||
[StreamingGame]: xref:Discord.StreamingGame
|
||||
[SpotifyGame]: xref:Discord.SpotifyGame
|
||||
[Rich Presence Intro]: https://discordapp.com/developers/docs/rich-presence/best-practices
|
||||
29
docs/faq/misc/legacy.md
Normal file
29
docs/faq/misc/legacy.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
uid: FAQ.Legacy
|
||||
title: Questions about Legacy Versions
|
||||
---
|
||||
|
||||
# Legacy Questions
|
||||
|
||||
This section refers to legacy library-related questions that do not
|
||||
apply to the latest or recent version of the Discord.Net library.
|
||||
|
||||
## X, Y, Z does not work! It doesn't return a valid value anymore.
|
||||
|
||||
If you are currently using an older version of the stable branch,
|
||||
please upgrade to the latest pre-release version to ensure maximum
|
||||
compatibility. Several features may be broken in older
|
||||
versions and will likely not be fixed in the version branch due to
|
||||
their breaking nature.
|
||||
|
||||
Visit the repo's [release tag] to see the latest public pre-release.
|
||||
|
||||
[release tag]: https://github.com/RogueException/Discord.Net/releases
|
||||
|
||||
## I came from an earlier version of Discord.Net 1.0, and DependencyMap doesn't seem to exist anymore in the later revision? What happened to it?
|
||||
|
||||
The `DependencyMap` has been replaced with Microsoft's
|
||||
[DependencyInjection] Abstractions. An example usage can be seen
|
||||
[here](https://github.com/foxbot/DiscordBotBase/blob/csharp/src/DiscordBot/Program.cs#L36).
|
||||
|
||||
[DependencyInjection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection
|
||||
18
docs/faq/toc.yml
Normal file
18
docs/faq/toc.yml
Normal file
@@ -0,0 +1,18 @@
|
||||
- name: Basic Concepts
|
||||
items:
|
||||
- name: Getting Started
|
||||
topicUid: FAQ.Basics.GetStarted
|
||||
- name: Basic Operations
|
||||
topicUid: FAQ.Basics.BasicOp
|
||||
- name: Client Basics
|
||||
topicUid: FAQ.Basics.ClientBasics
|
||||
- name: Commands
|
||||
items:
|
||||
- name: General
|
||||
topicUid: FAQ.Commands.General
|
||||
- name: Dependency Injection
|
||||
topicUid: FAQ.Commands.DI
|
||||
- name: Glossary
|
||||
topicUid: FAQ.Glossary
|
||||
- name: Legacy or Upgrade
|
||||
topicUid: FAQ.Legacy
|
||||
Reference in New Issue
Block a user