diff --git a/docs/faq/basics/basic-operations.md b/docs/faq/basics/basic-operations.md index 545bc0220..16f98c3b9 100644 --- a/docs/faq/basics/basic-operations.md +++ b/docs/faq/basics/basic-operations.md @@ -5,6 +5,10 @@ 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] diff --git a/docs/faq/basics/client-basics.md b/docs/faq/basics/client-basics.md index 48386206c..5c529a3f5 100644 --- a/docs/faq/basics/client-basics.md +++ b/docs/faq/basics/client-basics.md @@ -5,6 +5,10 @@ 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] diff --git a/docs/faq/basics/getting-started.md b/docs/faq/basics/getting-started.md index 1c9ab67e8..f38d2cea7 100644 --- a/docs/faq/basics/getting-started.md +++ b/docs/faq/basics/getting-started.md @@ -5,6 +5,10 @@ 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 diff --git a/docs/faq/commands/dependency-injection.md b/docs/faq/commands/dependency-injection.md new file mode 100644 index 000000000..0a5de3e32 --- /dev/null +++ b/docs/faq/commands/dependency-injection.md @@ -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 diff --git a/docs/faq/commands/commands.md b/docs/faq/commands/general.md similarity index 82% rename from docs/faq/commands/commands.md rename to docs/faq/commands/general.md index 2c905eaad..fb6fe39b6 100644 --- a/docs/faq/commands/commands.md +++ b/docs/faq/commands/general.md @@ -1,10 +1,13 @@ --- -uid: FAQ.Commands -title: Questions about Commands +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 @@ -42,29 +45,6 @@ the last parameter. [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; 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 - ## 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 diff --git a/docs/faq/commands/samples/missing-dep.cs b/docs/faq/commands/samples/missing-dep.cs new file mode 100644 index 000000000..d3fb9085b --- /dev/null +++ b/docs/faq/commands/samples/missing-dep.cs @@ -0,0 +1,29 @@ +public class MyModule : ModuleBase +{ + 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() + .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); + // ... + } +} \ No newline at end of file diff --git a/docs/faq/misc/glossary.md b/docs/faq/misc/glossary.md index 54c13d26a..95bdbaa03 100644 --- a/docs/faq/misc/glossary.md +++ b/docs/faq/misc/glossary.md @@ -5,6 +5,12 @@ 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 diff --git a/docs/faq/misc/legacy.md b/docs/faq/misc/legacy.md index 68ed57016..5931579d3 100644 --- a/docs/faq/misc/legacy.md +++ b/docs/faq/misc/legacy.md @@ -5,7 +5,10 @@ title: Questions about Legacy Versions # Legacy Questions -## X, Y, Z does not work! It doesn't return a valid value anymore +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 diff --git a/docs/faq/toc.yml b/docs/faq/toc.yml index ffacb0046..393e948f6 100644 --- a/docs/faq/toc.yml +++ b/docs/faq/toc.yml @@ -6,8 +6,12 @@ topicUid: FAQ.Basics.BasicOp - name: Client Basics topicUid: FAQ.Basics.ClientBasics -- name: Command - topicUid: FAQ.Commands +- 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 diff --git a/docs/guides/commands/post-execution.md b/docs/guides/commands/post-execution.md index 227cc02df..28f63659b 100644 --- a/docs/guides/commands/post-execution.md +++ b/docs/guides/commands/post-execution.md @@ -31,7 +31,7 @@ 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 the [FAQ](xref:FAQ.Commands). +about the impact in the [FAQ](xref:FAQ.Commands.General). ## CommandExecuted Event diff --git a/src/Discord.Net.Commands/CommandService.cs b/src/Discord.Net.Commands/CommandService.cs index 91a6e9e09..11f4ce276 100644 --- a/src/Discord.Net.Commands/CommandService.cs +++ b/src/Discord.Net.Commands/CommandService.cs @@ -157,7 +157,7 @@ namespace Discord.Commands } /// - /// Add a command module from a . + /// Add a command module from a . /// /// /// The following example registers the module MyModule to commandService.