22d79c1004
* Improve the Command Service documentation
The following changes have been added to this PR:
• Fix minor grammatical errors.
• Capitalize terms such as Commands, Modules and such, as the context is specific to the lib.
• Wrap methods and properties in code blocks.
The docs page currently has several issues that remains to be fixed.
1.
```md
>[!WARNING]
>This article is out of date and has not been rewritten yet.
Information is not guaranteed to be accurate.
```
The docs doesn't necessarily seem "out of date" as the warning claims. The basics seem pretty relevant to the latest version of the lib.
2.
>“To manually load a module, invoke [CommandService.AddModuleAsync], by passing in the generic type of your module and optionally, a dependency map.”
The latter part of the sentence seems off. Where should the user pass the dependency map to? It seems to suggest that `AddModuleAsync` has an argument to pass the dependency to. If it is referring to `AddModuleAsync(Type type)`, then I feel like it should be clarified here - or perhaps change the wording of the sentence.
3.
>“First, you need to create an @System.IServiceProvider You may create your own IServiceProvider if you wish.”
Any mention of @System.IServiceProvider is currently broken on the docs.
4.
>“Submodules are Modules that reside within another one. Typically, submodules are used to create nested groups (although not required to create nested groups).”
Clarification on the part after "although?"
5.
>“Finally, pass the map into the LoadAssembly method. Your modules will automatically be loaded with this dependency map.”
Where is this `LoadAssembly` method?
6.
```md
>[!NOTE]
>Preconditions can be applied to Modules, Groups, or Commands.
```
The docs should mention `ParameterPreconditionAttribute`'s existence.
* Update line breaks to comply with docs standard
* Change "you should..." to "instead, ..."
* Trim trailing spaces
* Change "inherits" to "inherit"
* Fix Context warning note and add ReplyAsync xref
* Fix broken xrefs
* Fix [Command Service] xref
* Fix consistency between TypeReaders and Preconditions returns
* Add missing semi-colons in ServiceProvider sample
* Change CommandContext to SocketCommandContext & change variable naming
* Cleanup TypeReader section
* Wrap [DontInject] in code block
* Fix commands docs linking in intro
* Improve Getting Started - Installation
- Fix character misalignment to comply with docs standard.
- Fix image numbering issues by moving the tooltips above some of the steps.
- Add codeblocks to search terms like `Discord.Net`.
- Remove broken `addons` reference.
- Specify `.NET 4.6.1` as `.NET Framework 4.6.1`.
- Minor cross-reference cleanup.
* Fix Getting Started - Intro
- Minor grammartical fixes.
- Wrap mentions of the methods, properties, and events in code block.
- Replace `Discord.Net` to `Discord.NET`.
- Fix steps numbering under `Creating a Discord Bot` and `Adding your bot to a server`.
- Change `Task-based Asynchronous Pattern ([TAP])` linking to mark the entire term instead.
- Change code block of `Pong!` to quotation mark instead.
* Fix cross references in Sending Voice
* Mention parameter precondition attribute
* Change `Discord.NET` to `Discord.Net` for consistency
* Wrap project names in code blocks & minor fixes in Terminology
* Change `add-ons` to `addons` for consistency
* Fix cross references in Logging
* Fix minor grammatical issues in "Working with Events"
* Missed a tilda
* Remove out-of-date warning in Commands
* Minor grammatical fixes for Entities
* Fix broken xref in Logging
* Adjust service collection sample
...according to f89aecb7bf (r141530227)
* Update Command Handler sample
- Update Main for C# 7.1.
- Inject CommandService and DiscordSocketClient into the service collection.
- Add Async suffix to asynchronous methods.
* Minor grammatical fixes in Events
* Revert 2 incorrect grammar corrections
* Revert async Main sample
* Add hardcode token notice in sample
* Fix missing method for Command Handler
* Modify module samples to use SocketCommandContext instead
* Emphasize CommandContext and SocketCommandContext
* Fix formatting for module sample
* Add SocketCommandContext for Groups sample
* Remove comma
* Fix DepMap sample formatting
* Replace [DontInject] with DontInjectAttribute with cross reference
* Remove connection logic note
There is no reason that this note should still be here since Ready event exists.
* Add a new warning message informing the users the existence of CommandService
* Make command handler private
excellent change
84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
---
|
|
title: Working with Events
|
|
---
|
|
|
|
Events in Discord.Net are consumed in a similar manner to the standard
|
|
convention, with the exception that every event must be of the type
|
|
`System.Threading.Tasks.Task` and instead of using `EventArgs`, the
|
|
event's parameters are passed directly into the handler.
|
|
|
|
This allows for events to be handled in an async context directly
|
|
instead of relying on `async void`.
|
|
|
|
### Usage
|
|
|
|
To receive data from an event, hook into it using C#'s delegate
|
|
event pattern.
|
|
|
|
You may either opt to hook an event to an anonymous function (lambda)
|
|
or a named function.
|
|
|
|
### Safety
|
|
|
|
All events are designed to be thread-safe; events are executed
|
|
synchronously off the gateway task in the same context as the gateway
|
|
task.
|
|
|
|
As a side effect, this makes it possible to deadlock the gateway task
|
|
and kill a connection. As a general rule of thumb, any task that takes
|
|
longer than three seconds should **not** be awaited directly in the
|
|
context of an event, but should be wrapped in a `Task.Run` or
|
|
offloaded to another task.
|
|
|
|
This also means that you should not await a task that requests data
|
|
from Discord's gateway in the same context of an event. Since the
|
|
gateway will wait on all invoked event handlers to finish before
|
|
processing any additional data from the gateway, this will create
|
|
a deadlock that will be impossible to recover from.
|
|
|
|
Exceptions in commands will be swallowed by the gateway and logged out
|
|
through the client's log method.
|
|
|
|
### Common Patterns
|
|
|
|
As you may know, events in Discord.Net are only given a signature of
|
|
`Func<T1, ..., Task>`. There is no room for predefined argument names,
|
|
so you must either consult IntelliSense, or view the API documentation
|
|
directly.
|
|
|
|
That being said, there are a variety of common patterns that allow you
|
|
to infer what the parameters in an event mean.
|
|
|
|
#### Entity, Entity
|
|
|
|
An event handler with a signature of `Func<Entity, Entity, Task>`
|
|
typically means that the first object will be a clone of the entity
|
|
_before_ a change was made, and the latter object will be an attached
|
|
model of the entity _after_ the change was made.
|
|
|
|
This pattern is typically only found on `EntityUpdated` events.
|
|
|
|
#### Cacheable
|
|
|
|
An event handler with a signature of `Func<Cacheable, Entity, Task>`
|
|
means that the `before` state of the entity was not provided by the
|
|
API, so it can either be pulled from the client's cache or
|
|
downloaded from the API.
|
|
|
|
See the documentation for [Cacheable] for more information on this
|
|
object.
|
|
|
|
[Cacheable]: xref:Discord.Cacheable`2
|
|
|
|
### Samples
|
|
|
|
[!code-csharp[Event Sample](samples/events.cs)]
|
|
|
|
### Tips
|
|
|
|
Many events relating to a Message entity (i.e. `MessageUpdated` and
|
|
`ReactionAdded`) rely on the client's message cache, which is
|
|
**not** enabled by default. Set the `MessageCacheSize` flag in
|
|
[DiscordSocketConfig] to enable it.
|
|
|
|
[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig |