In 1.0, Commands are no longer implemented at runtime with a builder pattern.
While a builder pattern may be provided later, commands are created primarily with
attributes.
### Basic Structure
All commands belong to a Module. (See the below section for creating modules.)
All commands in a module must be defined as an `Task`, with at least one argument,
being the @Discord.IMessage representing the context of the command.
To add parameters to your command, add additional arguments to the `Task` of the command.
You are _not_ required to accept all arguments as `String`, they will be automatically parsed
into the type you specify for the arument. See the Example Module for an example of command parameters.
## Modules
Modules serve as a host for commands you create.
@@ -38,6 +55,12 @@ When automatically loading modules, you are limited in your constructor. Using a
Alternatively, you can use an @Discord.Commands.IDependencyMap, as shown below.
### Command Groups
Command groups function similarly to Modules, but they must be contained inside a module. Simply create a **public** class inside a module, and flag it with the @Discord.Commands.GroupAttribute
[!code-csharp[Groups Sample](samples/groups.cs)]
## Dependency Injection
The Commands Service includes a very basic implementation of Dependency Injection that allows you to have completely custom constructors, within certain limitations.
@@ -61,7 +84,56 @@ In the constructor of your module, any parameters will be filled in by the @Disc
[!code-csharp[DependencyMap in Modules](samples/dependency_module.cs)]
## Type Readers
# Preconditions
Preconditions serve as a permissions system for your commands. Keep in mind, however, that they are
not limited to _just_ permissions, and can be as complex as you want them to be.
>[!NOTE]
>Preconditions can be applied to Modules, Groups, or Commands.
## Bundled Preconditions
@Discord.Commands ships with two built-in preconditions, @Discord.Commands.RequireContextAttribute
and @Discord.Commands.RequirePermissionAttribute.
### RequireContext
@Discord.Commands.RequireContextAttribute is a precondition that requires your command to be
executed in the specified context.
You may require three different types of context:
* Guild
* DM
* Group
Since these are `Flags`, you may OR them together.
public class RequireOwnerAttribute : PreconditionAttribute
{
public readonly ulong OwnerId = 66078337084162048;
// Override the CheckPermissions method
public override Task<PreconditionResult> CheckPermissions(IMessage context, Command executingCommand, object moduleInstance)
{
// If the author of the message is '66078337084162048', return success; otherwise fail.
return Task.FromResult(context.Author.Id == OwnerId ? PreconditionResult.FromSuccess() : PreconditionResult.FromError("You must be the owner of the bot."));