youys
/
Discord.Net
Not watched
1
0
Fork 0
Code
Releases 34 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
Browse Source

Comply with CONTRIBUTING.md 

- As well as making minor adjustments here and there
pull/988/head
Hsu Still 7 years ago
parent
c86e199a9d
commit
6a5cf07e0a
18 changed files with 430 additions and 228 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +0
    -37
      docs/faq/0-GettingStarted.md
  2. +0
    -18
      docs/faq/1-Basics.md
  3. +0
    -75
      docs/faq/2-BasicOperations.md
  4. +0
    -81
      docs/faq/4-Commands.md
  5. +0
    -11
      docs/faq/5-Legacy.md
  6. +0
    -0
      docs/faq/AdvancedOperations.md
  7. +74
    -0
      docs/faq/BasicOperations.md
  8. +47
    -0
      docs/faq/ClientBasics.md
  9. +114
    -0
      docs/faq/Commands.md
  10. +71
    -0
      docs/faq/GettingStarted.md
  11. +18
    -0
      docs/faq/Glossary.md
  12. +19
    -0
      docs/faq/Legacy.md
  13. BIN
      docs/faq/images/snowflake.png
  14. +15
    -0
      docs/faq/samples/basics/cast.cs
  15. +18
    -0
      docs/faq/samples/basics/emoji.cs
  16. +27
    -0
      docs/faq/samples/commands/DI.cs
  17. +19
    -0
      docs/faq/samples/commands/Remainder.cs
  18. +8
    -6
      docs/faq/toc.yml

+ 0
- 37
docs/faq/0-GettingStarted.md View File

@@ -1,37 +0,0 @@
# Basic Concepts / Getting Started

## How do I get started?
First of all, welcome! Before you delve into using the library, however, you should have some decent understanding of the language you are about to use. This library touches on TAP (Task-based Asynchronous Pattern), polymorphism, interface and many more advanced topics extensively. Please make sure that you understand these topics to some extent before proceeding.
Here are some examples:
1. [Official quick start guide](https://github.com/RogueException/Discord.Net/blob/dev/docs/guides/getting_started/samples/intro/structure.cs)
2. [Official template](https://github.com/foxbot/DiscordBotBase/tree/csharp/src/DiscordBot)
Please note that you should *not* try to blindly copy paste the code. It is meant to be a template or a guide. It is not meant to be something that will work out of the box.
## How do I add my bot to my server/guild?

The [OAuth2 URL](https://discordapp.com/developers/tools/oauth2-url-generator) can be generated via the Discord developer page. This allows you to set the permissions that the bot will be added with. With this method, bots will also be assigned their own special roles that normal users cannot use, which is what we call a `Managed` role.

## What is a Client/User/Object ID? Is it the token?

Each user and object on Discord has its own snowflake ID generated based on various conditions, see [here](https://this.is-a-professional-domain.com/7da0e4.png). The ID can be seen by anyone; it is public. It is merely used to identify an object in the Discord ecosystem. Many things in the library require an ID to retrieve the said object.
There are 2 ways to obtain the said ID.
1. Enable Discord's developer mode. With developer mode enabled, you can - as an example - right click on a guild and copy the guild id (please note that this does not apply to Role IDs, see below).
![Developer Mode](images/dev-mode.png)
2. Escape the object using `\` in front the object. For example, when you do `\@Example#1234`, it will return the user ID of the aforementioned user.
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 applies to both user and bot accounts. That also means that you should never ever 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.

## How do I get the role 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.
Please note that right-clicking on the role and copying the ID will **not** work. It will only copy the message ID.

## I have more questions!

Please visit us at #dotnet_discord-net at the Discord API server. Describe the problem in details to us, and preferably with the problematic code uploaded onto [Hastebin](https://hastebin.com).

+ 0
- 18
docs/faq/1-Basics.md View File

@@ -1,18 +0,0 @@
# Client Basics Questions

## My client keeps returning 401 upon logging in!

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 tokens start with `Mj*`. If it starts with any other characters, chances are, you are using the *client secret*, which has nothing to do with the login token.

## 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 in order 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's 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.

## 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](https://discord.foxbot.me/docs/guides/concepts/events.html#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.

+ 0
- 75
docs/faq/2-BasicOperations.md View File

@@ -1,75 +0,0 @@
# Basic Operations Questions

## How should I safely check a type?
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. There are several ways to cast, with direct casting `(Type)type` being the the least recommended, as it *can* throw an `InvalidCastException` when the object isn't the desired type. Please refer to [this post](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/types/how-to-safely-cast-by-using-as-and-is-operators) for more details.

A good and safe casting example:
```cs
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
}
}
```

## How do I send a message?

Any implementation of **IMessageChannel** has a **SendMessageAsync** method. Using the client, you can get an appropriate channel (**GetChannel(id)**) to send a message to. 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.

## How can I tell if a message is from X, Y, Z?

You may check message channel type.
* 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 a group).
* A **Private channel** (`IPrivateChannel`) is a DM or a Group.
* A **Message channel** (`IMessageChannel`) is all of the above.
## How do I add hyperlink text to an embed?

Embeds can use standard [markdown](https://support.discordapp.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline-) in the Description as well as in field values. With that in mind, links can be added using the following format \[text](link).
## How do I add reactions to a message?

Any entities that implement `IUserMessage` has an **AddReactionAsync** method. This method expects an `IEmote` as a parameter. In Discord.Net, an Emote represents a server custom emote, while an Emoji is a Unicode emoji (standard emoji). Both `Emoji` and `Emote` implement `IEmote` and are valid options.
```cs
// 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("\u23F8");
// 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);
```
## Why am I getting so many preemptive rate limits when I try to add more than one reactions?

This is due to how .NET parses the HTML header, mistreating 0.25sec/action to 1sec. This casues 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).

+ 0
- 81
docs/faq/4-Commands.md View File

@@ -1,81 +0,0 @@
# Command-related Questions

## How can I restrict some of my commands so only certain 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` etc.*).
If, however, you wish to restrict the commands based on the user's role, you can eithe create your own custom precondition or use Joe4evr's [Preconditions Addons](https://github.com/Joe4evr/Discord.Addons/tree/master/src/Discord.Addons.Preconditions) 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 own custom preconditions.

## I'm getting an error about `Assembly#GetEntryAssembly`. What now?

You may be confusing `CommandService#AddModulesAsync` with `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 don't 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.
```cs
// !echo repeat this message in chat
[Command("echo")]
[Summary("Replies whatever the user adds")]
[Remarks("The entire message is considered one String")]
public Task EchoAsync([Remainder]String text) => ReplyAsync(text);
// !echo repeat this message in chat
[Command("echo")]
[Summary("Replies whatever the user adds")]
[Remarks("This command will error for having too many arguments.
The message would be seen as having 5 parameters while the method only accepts one.
Wrapping the message in quotes solves this - '!echo repeat this message in chat' -
this way, the system knows the entire message is to be parsed as a single String")]
public Task EchoAsync(String text) => ReplyAsync(text);
```
## 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. This means that they are spawned every time when a request is received, and are killed from memory when the execution finishes. This is why you cannot store persistent data inside a module. To workaround this, consider using a service. Service is often used to hold data externally, so that they will 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 before proceeding. You can learn more about it [here](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection), and how it works in Discord.NET [here](https://discord.foxbot.me/latest/guides/commands/commands.html#usage-in-modules). A brief example of service and dependency injection can be seen below,
```cs
public class MyService
{
public string MyCoolString {get; set;}
}
public class SetupOrWhatever
{
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 ctor
private readonly MyService _myService;
public MyModule (MyService myService) => _myService = myService;
[Command("setorprintstring")]
public Task GetOrSetStringAsync()
{
if (_myService.MyCoolString == null) _myService.MyCoolString = "ya boi";
return ReplyAsync(_myService.MyCoolString);
}
}
```
## I have a long-running Task in my command, and Discord.NET keeps saying that a `MessageReceived` handler is blocking the gateway. What gives?

By default, all commands are executed on the same thread as the gateway task, which is responsible for keeping the connection from your client to Discord alive. When you execute a long-running task, this blocks the gateway from communicating for as long as the command task is being executed. The library will warn you about any long running event handler (in this case, the command handler) that persists for more than 3 seconds.
To resolve this, the library has designed a flag called `RunMode`. There are 2 main `RunMode`s. One being `RunMode.Sync`, which is the default; another being `RunMode.Async`. `RunMode.Async` essentially calls an unawaited Task and continues with the execution without waiting for the command task to finish. You should use `RunMode.Async` in either the `CommandAttribute` or the `DefaultRunMode` flag in `CommandServiceConfig`. Further details regarding `RunMode.Async` can be found below.
## Okay, that's great and all, but how does `RunMode.Async` work, and if it's so great, why is the lib *not* using it by default?

As with any async operation, `RunMode.Async` also comes at a cost. The following are the caveats with RunMode.Async,
1) You introduce race condition.
2) Unnecessary overhead caused by async state machine (learn more about it [here](https://www.red-gate.com/simple-talk/dotnet/net-tools/c-async-what-is-it-and-how-does-it-work/)).
3) `CommandService#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 #3 and #4.
For #3, in Discord.NET 2.0, the library introduces a new event called `CommandExecuted`, which is raised whenever the command is finished. This event will be called regardless of the `RunMode` type and will return the appropriate execution result
For #4, exceptions are caught in `CommandService#Log` under `(CommandException)LogMessage.Exception`.

+ 0
- 11
docs/faq/5-Legacy.md View File

@@ -1,11 +0,0 @@
# Legacy Questions
## X, Y, Z does not work! It doesn't return a valid value anymore.
If you're currently using 1.0.0, please upgrade to the latest 2.0 beta to ensure maximum compatibility. Several methods or props may be broken in 1.0.x and will not be fixed in the 1.0 branch due to their breaking nature.
Notable breaking changes are as follows,
* `IChannel#IsNsfw` has been replaced with `ITextChannel#IsNsfw` and now returns valid value in 2.0.
* Bulk message removal (`DeletedMessagesAsync`) has been moved from `IMessageChannel` to `ITextChannel`.
* `IAsyncEnumerable#Flatten` has been renamed to `FlattenAsync`.
## 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection) Abstractions. An example usage can be seen [here](https://github.com/foxbot/DiscordBotBase/blob/csharp/src/DiscordBot/Program.cs#L36).

docs/faq/3-AdvancedOperations.md → docs/faq/AdvancedOperations.md View File


+ 74
- 0
docs/faq/BasicOperations.md View File

@@ -0,0 +1,74 @@
# Basic Operations Questions

## How should I safely check a type?
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. There are several ways to cast, with direct casting
`(Type)type` being the the least recommended, as it *can* throw an
[InvalidCastException] when the object isn't the desired type.
Please refer to [this post] for more details.

A good and safe casting example:

[!code-csharp[Casting](samples/basics/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?

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#Discord_IMessageChannel_SendMessageAsync_System_String_System_Boolean_Discord_Embed_Discord_RequestOptions_
[GetChannel]: xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_GetChannel_System_UInt64_

## How can I tell if a message is from X, Y, Z?

You may check the message channel type. Visit [Glossary] to see the
various types of channels.

[Glossary]: Glossary.md

## 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 using the
following format \[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 entities that implement [IUserMessage] has an [AddReactionAsync]
method. This method expects an [IEmote] as a parameter.
In Discord.Net, an Emote represents a server custom emote, while an
Emoji is a Unicode emoji (standard emoji). Both [Emoji] and [Emote]
implement [IEmote] and are valid options.

[!code-csharp[Emoji](samples/basics/emoji.cs)]

[AddReactionAsync]: xref:Discord.IUserMessage#Discord_IUserMessage_AddReactionAsync_Discord_IEmote_Discord_RequestOptions_
## Why am I getting so many preemptive rate limits when I try to add more than one reactions?

This is due to how .NET parses the HTML header, mistreating
0.25sec/action to 1sec. This casues 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).

[IMessageChannel]: xref:Discord.IMessageChannel
[IUserMessage]: xref:Discord.IUserMessage
[IEmote]: xref:Discord.IEmote
[Emote]: xref:Discord.Emote
[Emoji]: xref:Discord.Emoji

+ 47
- 0
docs/faq/ClientBasics.md View File

@@ -0,0 +1,47 @@
# Client Basics Questions

## My client keeps returning 401 upon logging in!

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 tokens start with `Mj*`.
If it starts with any other characters, chances are, you might be
using the *client secret*, which has nothing to do with the login
token.

[TokenType]: xref:Discord.TokenType

## 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 in order 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's 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#Discord_WebSocket_DiscordSocketClient_Ready
[GuildAvailable]: xref:Discord.WebSocket.BaseSocketClient#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](../guides/concepts/events.md#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#Discord_WebSocket_DiscordSocketConfig_MessageCacheSize
[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient#Discord_WebSocket_BaseSocketClient_MessageUpdated

+ 114
- 0
docs/faq/Commands.md View File

@@ -0,0 +1,114 @@
# Command-related Questions

## How can I restrict some of my commands so only certain 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` etc.*).

If, however, you wish to restrict the commands based on the user's
role, you can either create your own 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 own
custom preconditions.

[RequireUserPermission]: xref:Discord.Commands.RequireUserPermissionAttribute
[Preconditions Addons]: https://github.com/Joe4evr/Discord.Addons/tree/master/src/Discord.Addons.Preconditions

## I'm getting an error about `Assembly#GetEntryAssembly`. What now?

You may be confusing [CommandService#AddModulesAsync] with
[CommandService#AddModuleAsync]. The former is used to add modules
via the assembly, while the latter is used to add a single module.

[CommandService#AddModulesAsync]: xref:Discord.Commands.CommandService#Discord_Commands_CommandService_AddModulesAsync_Assembly_System_IServiceProvider_
[CommandService#AddModuleAsync]: xref:Discord.Commands.CommandService#Discord_Commands_CommandService_AddModuleAsync__1_System_IServiceProvider_

## What does [Remainder] do in the command signature?

The [RemainderAttribute] leaves the string unparsed, meaning you
don't 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/commands/Remainder.cs)]

[RemainderAttribute]: xref:Discord.Commands.RemainderAttribute

## 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. This means that they are spawned
every time when a request is received, and are killed from memory
when the execution finishes. This is why you cannot store persistent
data inside a module. To workaround this, consider using a service.

Service is often used to hold data externally, so that they will
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] before proceeding, as well
as how it works in [Discord.NET](../guides/commands/commands.md#usage-in-modules).

A brief example of service and dependency injection can be seen below.

[!code-csharp[DI](samples/commands/DI.cs)]

[Dependency Injection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection

## I have a long-running Task in my command, and Discord.NET keeps saying that a `MessageReceived` handler is blocking the gateway. What gives?

By default, all commands are executed on the same thread as the
gateway task, which is responsible for keeping the connection from
your client to Discord alive. When you execute a long-running task,
this blocks the gateway from communicating for as long as the command
task is being executed. The library will warn you about any long
running event handler (in this case, the command handler) that
persists for more than 3 seconds.

To resolve this, the library has designed a flag called [RunMode].
There are 2 main `RunMode`s. One being `RunMode.Sync`, which is the
default; another being `RunMode.Async`. `RunMode.Async` essentially
calls an unawaited Task and continues with the execution without
waiting for the command task to finish. You should use
`RunMode.Async` in either the [CommandAttribute] or the
[DefaultRunMode] flag in `CommandServiceConfig`.
Further details regarding `RunMode.Async` can be found below.

[RunMode]: xref:Discord.Commands.RunMode
[CommandAttribute]: xref:Discord.Commands.CommandAttribute
[DefaultRunMode]: xref:Discord.Commands.CommandServiceConfig#Discord_Commands_CommandServiceConfig_DefaultRunMode

## Okay, that's great and all, but how does `RunMode.Async` work, and if it's so great, why is the lib *not* using it by default?

As with any async operation, `RunMode.Async` also comes at a cost.
The following are the caveats with RunMode.Async,
1) You introduce race condition.
2) Unnecessary overhead caused by [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 #3 and #4.

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].

[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#Discord_Commands_CommandService_ExecuteAsync_Discord_Commands_ICommandContext_System_Int32_System_IServiceProvider_Discord_Commands_MultiMatchHandling_
[ExecuteResult]: xref:Discord.Commands.ExecuteResult
[RuntimeResult]: xref:Discord.Commands.RuntimeResult
[CommandExecuted]: xref:Discord.Commands.CommandService#Discord_Commands_CommandService_CommandExecuted
[CommandService#Log]: xref:Discord.Commands.CommandService#Discord_Commands_CommandService_Log
[LogMessage.Exception]: xref:Discord.LogMessage#Discord_LogMessage_Exception
[CommandException]: xref:Discord.Commands.CommandException

+ 71
- 0
docs/faq/GettingStarted.md View File

@@ -0,0 +1,71 @@
# Basic Concepts / Getting Started

## How do I get started?
First of all, welcome! Before you delve into using the library;
however, you should have some decent understanding of the language
you are about to use. This library touches on
[Task-based Asynchronous Pattern], [polymorphism], [interface] and
many more advanced topics extensively. Please make sure that you
understand these topics to some extent before proceeding.
Here are some examples:
1. [Official quick start guide](https://github.com/RogueException/Discord.Net/blob/dev/docs/guides/getting_started/samples/intro/structure.cs)
2. [Official template](https://github.com/foxbot/DiscordBotBase/tree/csharp/src/DiscordBot)
Please note that you should *not* try to blindly copy paste the code. It is meant to be a template or a guide. It is not meant to be something that will work out of the box.
[Task-based Asynchronous Pattern]: https://docs.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap
[polymorphism]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/polymorphism
[interface]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/interfaces/
## How do I add my bot to my server/guild?

The [OAuth2 URL](https://discordapp.com/developers/tools/oauth2-url-generator)
can be generated via the Discord developer page. This allows you to
set the permissions that the bot will be added with. With this method,
bots will also be assigned their own special roles that normal users
cannot use, which is what we call a `Managed` role.

## What is a Client/User/Object ID? Is it the token?

Each user and object on Discord has its own snowflake ID generated
based on various conditions.
![Snowflake Generation](images/snowflake.png)
The ID can be seen by anyone; it is public. It is merely used to
identify an object in the Discord ecosystem. Many things in the
library require an ID to retrieve the said object.
There are 2 ways to obtain the said ID.
1. Enable Discord's developer mode. With developer mode enabled,
you can - as an example - right click on a guild and copy the guild
id (please note that this does not apply to Role IDs, see below).
![Developer Mode](images/dev-mode.png)
2. Escape the object using `\` in front the object. For example,
when you do `\@Example#1234` in chat, it will return the user ID of
the aforementioned user.
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 applies to both user and bot
accounts. That also means that you should never ever 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.

## How do I get the role 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.
Please note that right-clicking on the role and copying the ID will
**not** work. It will only copy the message ID.

## I have more questions!

Please visit us at #dotnet_discord-net at [Discord API].
Describe the problem in details to us, and preferably with the
problematic code uploaded onto [Hastebin](https://hastebin.com).

[Discord API]: https://discord.gg/jkrBmQR

+ 18
- 0
docs/faq/Glossary.md View File

@@ -0,0 +1,18 @@
# Glossary

## Channel types

* 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]) is all of the above.


[IMessageChannel]: xref:Discord.IMessageChannel
[ITextChannel]: xref:Discord.ITextChannel
[IGroupChannel]: xref:Discord.IGroupChannel
[IDMChannel]: xref:Discord.IDMChannel
[IPrivateChannel]: xref:Discord.IPrivateChannel

+ 19
- 0
docs/faq/Legacy.md View File

@@ -0,0 +1,19 @@
# Legacy Questions

## X, Y, Z does not work! It doesn't return a valid value anymore.
If you're currently using an older version in stable branch, please
upgrade to the latest pre-release version to ensure maximum
compatibility. Several methods or props 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

BIN
docs/faq/images/snowflake.png View File

Before After
Width: 700  |  Height: 365  |  Size: 71 KiB

+ 15
- 0
docs/faq/samples/basics/cast.cs View 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
- 0
docs/faq/samples/basics/emoji.cs View 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);

+ 27
- 0
docs/faq/samples/commands/DI.cs View File

@@ -0,0 +1,27 @@
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 ctor
private readonly MyService _myService;
public MyModule (MyService myService) => _myService = myService;
[Command("string")]
public Task GetOrSetStringAsync(string input)
{
if (_myService.MyCoolString == null) _myService.MyCoolString = input;
return ReplyAsync(_myService.MyCoolString);
}
}

+ 19
- 0
docs/faq/samples/commands/Remainder.cs View File

@@ -0,0 +1,19 @@
// 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 5 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"

+ 8
- 6
docs/faq/toc.yml View File

@@ -1,10 +1,12 @@
- name: Getting Started - name: Getting Started
href: 0-GettingStarted.md
- name: Basics
href: 1-Basics.md
href: GettingStarted.md
- name: Client Basics
href: ClientBasics.md
- name: Basic Operations - name: Basic Operations
href: 2-BasicOperations.md
href: BasicOperations.md
- name: Commands - name: Commands
href: 4-Commands.md
href: Commands.md
- name: Glossary
href: Glossary.md
- name: Legacy or Upgrade - name: Legacy or Upgrade
href: 5-Legacy.md
href: Legacy.md

Write Preview
Loading…
Cancel
Save
Please read the following content carefully:

Dear OpenI User

Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.

For more agreement content, please refer to the《Openl Qizhi Community AI Collaboration Platform Usage Agreement》

Agree and continue
Disagree, exit