Class CommandService

Namespace

Discord.Commands

Assembly

Discord.Net.Commands.dll

Provides a framework for building Discord commands.

public class CommandService : IDisposable

Inheritance

object

CommandService

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

CommandServiceExtensions.GetExecutableCommandsAsync(CommandService, ICommandContext, IServiceProvider)

Remarks

The service provides a framework for building Discord commands both dynamically via runtime builders or statically via compile-time modules. To create a command module at compile-time, see ModuleBase (most common); otherwise, see ModuleBuilder.

This service also provides several events for monitoring command usages; such as Log for any command-related log events, and CommandExecuted for information about commands that have been successfully executed.

Constructors

CommandService()

Initializes a new CommandService class.

public CommandService()

CommandService(CommandServiceConfig)

Initializes a new CommandService class with the provided configuration.

public CommandService(CommandServiceConfig config)

Parameters

config CommandServiceConfig

The configuration class.

Exceptions

InvalidOperationException

The RunMode cannot be set to Default.

Properties

Commands

Represents all commands loaded within CommandService.

public IEnumerable<CommandInfo> Commands { get; }

Property Value

IEnumerable<CommandInfo>

Modules

Represents all modules loaded within CommandService.

public IEnumerable<ModuleInfo> Modules { get; }

Property Value

IEnumerable<ModuleInfo>

TypeReaders

Represents all TypeReader loaded within CommandService.

public ILookup<Type, TypeReader> TypeReaders { get; }

Property Value

ILookup<Type, TypeReader>

Methods

AddModuleAsync(Type, IServiceProvider)

Adds a command module from a Type.

public Task<ModuleInfo> AddModuleAsync(Type type, IServiceProvider services)

Parameters

type Type

The type of module.

services IServiceProvider

The IServiceProvider for your dependency injection solution if using one; otherwise, pass null .

Returns

Task<ModuleInfo>

A task that represents the asynchronous operation for adding the module. The task result contains the built module.

Exceptions

ArgumentException

This module has already been added.

InvalidOperationException

The ModuleInfo fails to be built; an invalid type may have been provided.

AddModuleAsync<T>(IServiceProvider)

Add a command module from a Type.

public Task<ModuleInfo> AddModuleAsync<T>(IServiceProvider services)

Parameters

services IServiceProvider

The IServiceProvider for your dependency injection solution if using one; otherwise, pass null.

Returns

Task<ModuleInfo>

A task that represents the asynchronous operation for adding the module. The task result contains the built module.

Type Parameters

T

The type of module.

Examples

The following example registers the module MyModule to commandService.

await commandService.AddModuleAsync<MyModule>(serviceProvider);

Exceptions

ArgumentException

This module has already been added.

InvalidOperationException

The ModuleInfo fails to be built; an invalid type may have been provided.

AddModulesAsync(Assembly, IServiceProvider)

Add command modules from an Assembly.

public Task<IEnumerable<ModuleInfo>> AddModulesAsync(Assembly assembly, IServiceProvider services)

Parameters

assembly Assembly

The Assembly containing command modules.

services IServiceProvider

The IServiceProvider for your dependency injection solution if using one; otherwise, pass null.

Returns

Task<IEnumerable<ModuleInfo>>

A task that represents the asynchronous operation for adding the command modules. The task result contains an enumerable collection of modules added.

AddTypeReader(Type, TypeReader)

Adds a custom TypeReader to this CommandService for the supplied object type. If type is a ValueType, a nullable TypeReader for the value type will also be added. If a default TypeReader exists for type, a warning will be logged and the default TypeReader will be replaced.

public void AddTypeReader(Type type, TypeReader reader)

Parameters

type Type

A Type instance for the type to be read.

reader TypeReader

An instance of the TypeReader to be added.

AddTypeReader(Type, TypeReader, bool)

Adds a custom TypeReader to this CommandService for the supplied object type. If type is a ValueType, a nullable TypeReader for the value type will also be added.

public void AddTypeReader(Type type, TypeReader reader, bool replaceDefault)

Parameters

type Type

A Type instance for the type to be read.

reader TypeReader

An instance of the TypeReader to be added.

replaceDefault bool

Defines whether the TypeReader should replace the default one for Type if it exists.

AddTypeReader<T>(TypeReader)

Adds a custom TypeReader to this CommandService for the supplied object type. If T is a ValueType, a nullable TypeReader will also be added. If a default TypeReader exists for T, a warning will be logged and the default TypeReader will be replaced.

public void AddTypeReader<T>(TypeReader reader)

Parameters

reader TypeReader

An instance of the TypeReader to be added.

Type Parameters

T

The object type to be read by the TypeReader.

AddTypeReader<T>(TypeReader, bool)

Adds a custom TypeReader to this CommandService for the supplied object type. If T is a ValueType, a nullable TypeReader will also be added.

public void AddTypeReader<T>(TypeReader reader, bool replaceDefault)

Parameters

reader TypeReader

An instance of the TypeReader to be added.

replaceDefault bool

Defines whether the TypeReader should replace the default one for Type if it exists.

Type Parameters

T

The object type to be read by the TypeReader.

CreateModuleAsync(string, Action<ModuleBuilder>)

public Task<ModuleInfo> CreateModuleAsync(string primaryAlias, Action<ModuleBuilder> buildFunc)

Parameters

primaryAlias string

buildFunc Action<ModuleBuilder>

Returns

Task<ModuleInfo>

Dispose(bool)

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

ExecuteAsync(ICommandContext, int, IServiceProvider, MultiMatchHandling)

Executes the command.

public Task<IResult> ExecuteAsync(ICommandContext context, int argPos, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception)

Parameters

context ICommandContext

The context of the command.

argPos int

The position of which the command starts at.

services IServiceProvider

The service to be used in the command's dependency injection.

multiMatchHandling MultiMatchHandling

The handling mode when multiple command matches are found.

Returns

Task<IResult>

A task that represents the asynchronous execution operation. The task result contains the result of the command execution.

ExecuteAsync(ICommandContext, string, IServiceProvider, MultiMatchHandling)

Executes the command.

public Task<IResult> ExecuteAsync(ICommandContext context, string input, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception)

Parameters

context ICommandContext

The context of the command.

input string

The command string.

services IServiceProvider

The service to be used in the command's dependency injection.

multiMatchHandling MultiMatchHandling

The handling mode when multiple command matches are found.

Returns

Task<IResult>

A task that represents the asynchronous execution operation. The task result contains the result of the command execution.

RemoveModuleAsync(ModuleInfo)

Removes the command module.

public Task<bool> RemoveModuleAsync(ModuleInfo module)

Parameters

module ModuleInfo

The ModuleInfo to be removed from the service.

Returns

Task<bool>

A task that represents the asynchronous removal operation. The task result contains a value that indicates whether the module is successfully removed.

RemoveModuleAsync(Type)

Removes the command module.

public Task<bool> RemoveModuleAsync(Type type)

Parameters

type Type

The Type of the module.

Returns

Task<bool>

A task that represents the asynchronous removal operation. The task result contains a value that indicates whether the module is successfully removed.

RemoveModuleAsync<T>()

Removes the command module.

public Task<bool> RemoveModuleAsync<T>()

Returns

Task<bool>

A task that represents the asynchronous removal operation. The task result contains a value that indicates whether the module is successfully removed.

Type Parameters

T

The Type of the module.

Search(ICommandContext, int)

Searches for the command.

public SearchResult Search(ICommandContext context, int argPos)

Parameters

context ICommandContext

The context of the command.

argPos int

The position of which the command starts at.

Returns

SearchResult

The result containing the matching commands.

Search(ICommandContext, string)

Searches for the command.

public SearchResult Search(ICommandContext context, string input)

Parameters

context ICommandContext

The context of the command.

input string

The command string.

Returns

SearchResult

The result containing the matching commands.

Search(string)

public SearchResult Search(string input)

Parameters

input string

Returns

SearchResult

TryRemoveTypeReader(Type, bool, out IDictionary<Type, TypeReader>)

Removes a type reader from the list of type readers.

public bool TryRemoveTypeReader(Type type, bool isDefaultTypeReader, out IDictionary<Type, TypeReader> readers)

Parameters

type Type

The type to remove the readers from.

isDefaultTypeReader bool

true if the default readers for type should be removed; otherwise false.

readers IDictionary<Type, TypeReader>

The removed collection of type readers.

Returns

bool

true if the remove operation was successful; otherwise false.

Remarks

Removing a TypeReader from the CommandService will not dereference the TypeReader from the loaded module/command instances. You need to reload the modules for the changes to take effect.

ValidateAndGetBestMatch(SearchResult, ICommandContext, IServiceProvider, MultiMatchHandling)

Validates and gets the best CommandMatch from a specified SearchResult

public Task<IResult> ValidateAndGetBestMatch(SearchResult matches, ICommandContext context, IServiceProvider provider, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception)

Parameters

matches SearchResult

The SearchResult.

context ICommandContext

The context of the command.

provider IServiceProvider

The service provider to be used on the command's dependency injection.

multiMatchHandling MultiMatchHandling

The handling mode when multiple command matches are found.

Returns

Task<IResult>

A task that represents the asynchronous validation operation. The task result contains the result of the command validation as a MatchResult or a SearchResult if no matches were found.

Events

CommandExecuted

Occurs when a command is executed.

public event Func<Optional<CommandInfo>, ICommandContext, IResult, Task> CommandExecuted

Event Type

Func<Optional<CommandInfo>, ICommandContext, IResult, Task>

Remarks

This event is fired when a command has been executed, successfully or not. When a command fails to execute during parsing or precondition stage, the CommandInfo may not be returned.

Log

Occurs when a command-related information is received.

public event Func<LogMessage, Task> Log

Event Type

Func<LogMessage, Task>