diff --git a/DisCatSharp.Docs/articles/modules/commandsnext/command_attributes.md b/DisCatSharp.Docs/articles/modules/commandsnext/command_attributes.md index 8ffcd27a7..901b77e4e 100644 --- a/DisCatSharp.Docs/articles/modules/commandsnext/command_attributes.md +++ b/DisCatSharp.Docs/articles/modules/commandsnext/command_attributes.md @@ -1,103 +1,101 @@ --- uid: modules_commandsnext_command_attributes title: Command Attributes --- ## Built-In Attributes CommandsNext has a variety of built-in attributes to enhance your commands and provide some access control. The majority of these attributes can be applied to your command methods and command groups. - @DisCatSharp.CommandsNext.Attributes.AliasesAttribute - @DisCatSharp.CommandsNext.Attributes.CooldownAttribute - @DisCatSharp.CommandsNext.Attributes.DescriptionAttribute - @DisCatSharp.CommandsNext.Attributes.DontInjectAttribute - @DisCatSharp.CommandsNext.Attributes.HiddenAttribute - @DisCatSharp.CommandsNext.Attributes.ModuleLifespanAttribute - @DisCatSharp.CommandsNext.Attributes.PriorityAttribute - @DisCatSharp.CommandsNext.Attributes.RemainingTextAttribute - @DisCatSharp.CommandsNext.Attributes.RequireBotPermissionsAttribute - @DisCatSharp.CommandsNext.Attributes.RequireCommunityAttribute - @DisCatSharp.CommandsNext.Attributes.RequireDirectMessageAttribute -- @DisCatSharp.CommandsNext.Attributes.RequireDiscordCertifiedModeratorAttribute -- @DisCatSharp.CommandsNext.Attributes.RequireDiscordEmployeeAttribute - @DisCatSharp.CommandsNext.Attributes.RequireGuildAttribute - @DisCatSharp.CommandsNext.Attributes.RequireGuildOwnerAttribute - @DisCatSharp.CommandsNext.Attributes.RequireMemberVerificationGateAttribute - @DisCatSharp.CommandsNext.Attributes.RequireNsfwAttribute - @DisCatSharp.CommandsNext.Attributes.RequireOwnerAttribute - @DisCatSharp.CommandsNext.Attributes.RequireOwnerOrIdAttribute - @DisCatSharp.CommandsNext.Attributes.RequirePermissionsAttribute - @DisCatSharp.CommandsNext.Attributes.RequirePrefixesAttribute - @DisCatSharp.CommandsNext.Attributes.RequireRolesAttribute - @DisCatSharp.CommandsNext.Attributes.RequireUserPermissionsAttribute - @DisCatSharp.CommandsNext.Attributes.RequireWelcomeScreenAttribute ## Custom Attributes If the above attributes don't meet your needs, CommandsNext also gives you the option of writing your own! Simply create a new class which inherits from `CheckBaseAttribute` and implement the required method. Our example below will only allow a command to be ran during a specified year. ```cs public class RequireYearAttribute : CheckBaseAttribute { public int AllowedYear { get; private set; } public RequireYearAttribute(int year) { AllowedYear = year; } public override Task ExecuteCheckAsync(CommandContext ctx, bool help) { return Task.FromResult(AllowedYear == DateTime.Now.Year); } } ```
You'll also need to apply the `AttributeUsage` attribute to your attribute.
For our example attribute, we'll set it to only be usable once on methods. ```cs [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)] public class RequireYearAttribute : CheckBaseAttribute { // ... } ``` You can provide feedback to the user using the `CommandsNextExtension#CommandErrored` event. ```cs private async Task MainAsync() { var discord = new DiscordClient(); var commands = discord.UseCommandsNext(); commands.CommandErrored += CmdErroredHandler; } private async Task CmdErroredHandler(CommandsNextExtension _, CommandErrorEventArgs e) { var failedChecks = ((ChecksFailedException)e.Exception).FailedChecks; foreach (var failedCheck in failedChecks) { if (failedCheck is RequireYearAttribute) { var yearAttribute = (RequireYearAttribute)failedCheck; await e.Context.RespondAsync($"Only usable during year {yearAttribute.AllowedYear}."); } } } ```
Once you've got all of that completed, you'll be able to use it on a command! ```cs [Command("generic"), RequireYear(2030)] public async Task GenericCommand(CommandContext ctx, string generic) { await ctx.RespondAsync("Generic response."); } ``` ![Generic Image](/images/commands_command_attributes_01.png) diff --git a/DisCatSharp.Docs/articles/modules/commandsnext/dependency_injection.md b/DisCatSharp.Docs/articles/modules/commandsnext/dependency_injection.md index 50cf2c7f0..483d83fdc 100644 --- a/DisCatSharp.Docs/articles/modules/commandsnext/dependency_injection.md +++ b/DisCatSharp.Docs/articles/modules/commandsnext/dependency_injection.md @@ -1,98 +1,98 @@ --- uid: modules_commandsnext_dependency_injection title: Dependency Injection --- ## Dependency Injection As you begin to write more complex commands, you'll find that you need a way to get data in and out of them. Although you *could* use `static` fields to accomplish this, the preferred solution would be *dependency injection*. This would involve placing all required object instances and types (referred to as *services*) in a container, then providing that container to CommandsNext. Each time a command module is instantiated, CommandsNext will then attempt to populate constructor parameters, `public` properties, and `public` fields exposed by the module with instances of objects from the service container. We'll go through a simple example of this process to help you understand better. ### Create a Service Provider To begin, we'll need to create a service provider; this will act as the container for the services you need for your commands. Create a new variable just before you register CommandsNext with your `DiscordClient` and assign it a new instance of `ServiceCollection`. ```cs var discord = new DiscordClient(); var services = new ServiceCollection(); // Right here! var commands = discord.UseCommandsNext(); ``` We'll use `.AddSingleton` to add type `Random` to the collection, then chain that call with the `.BuildServiceProvider()` extension method. The resulting type will be `ServiceProvider`. ```cs var services = new ServiceCollection() .AddSingleton() .BuildServiceProvider(); ``` Then we'll need to provide CommandsNext with our services. ```cs var commands = discord.UseCommandsNext(new CommandsNextConfiguration() { Services = services }); ``` ### Using Your Services Now that we have our services set up, we're able to use them in commands.
We'll be tweaking our [random number command](xref:modules_commandsnext_intro#argument-converters) to demonstrate. Add a new property to the command module named *Rng*. Make sure it has a `public` setter. ```cs public class MyFirstModule : BaseCommandModule { public Random Rng { private get; set; } // Implied public setter. // ... } ``` Modify the *random* command to use our property. ```cs [Command("random")] public async Task RandomCommand(CommandContext ctx, int min, int max) { await ctx.RespondAsync($"Your number is: {Rng.Next(min, max)}"); } ``` Then we can give it a try! -![Command Execution](/images/commands_dependency_injection_01.png) +![Command Execution](/images/commands_intro_05.png)
CommandsNext has automatically injected our singleton `Random` instance into the `Rng` property when our command module was instantiated. Now, for any command that needs `Random`, we can simply declare one as a property, field, or in the module constructor and CommandsNext will take care of the rest. Ain't that neat? ## Lifespans ### Modules By default, all command modules have a singleton lifespan; this means each command module is instantiated once for the lifetime of the CommandsNext instance. However, if the reuse of a module instance is undesired, you also have the option to change the lifespan of a module to *transient* using the `ModulesLifespan` attribute. ```cs [ModuleLifespan(ModuleLifespan.Transient)] public class MyFirstModule : BaseCommandModule { // ... } ``` Transient command modules are instantiated each time one of its containing commands is executed. ### Services In addition to the `.AddSingleton()` extension method, you're also able to use the `.AddScoped()` and `.AddTransient()` extension methods to add services to the collection. The extension method chosen will affect when and how often the service is instantiated. Scoped and transient services should only be used in transient command modules, as singleton modules will always have their services injected once. Lifespan|Instantiated :---:|:--- Singleton|One time when added to the collection. Scoped|Once for each command module. Transient|Each time its requested. diff --git a/DisCatSharp.Docs/images/_basics_first_bot_07.png b/DisCatSharp.Docs/images/_basics_first_bot_07.png deleted file mode 100644 index 1dc2f5810..000000000 Binary files a/DisCatSharp.Docs/images/_basics_first_bot_07.png and /dev/null differ diff --git a/DisCatSharp.Docs/images/commands_argument_converters_01.png b/DisCatSharp.Docs/images/commands_argument_converters_01.png index 17c224e90..7e2468d05 100644 Binary files a/DisCatSharp.Docs/images/commands_argument_converters_01.png and b/DisCatSharp.Docs/images/commands_argument_converters_01.png differ diff --git a/DisCatSharp.Docs/images/commands_command_attributes_01.png b/DisCatSharp.Docs/images/commands_command_attributes_01.png index a5551aef1..7a66e5b14 100644 Binary files a/DisCatSharp.Docs/images/commands_command_attributes_01.png and b/DisCatSharp.Docs/images/commands_command_attributes_01.png differ diff --git a/DisCatSharp.Docs/images/commands_dependency_injection_01.png b/DisCatSharp.Docs/images/commands_dependency_injection_01.png deleted file mode 100644 index 08e1c7326..000000000 Binary files a/DisCatSharp.Docs/images/commands_dependency_injection_01.png and /dev/null differ diff --git a/DisCatSharp.Docs/images/commands_help_formatter_02.png b/DisCatSharp.Docs/images/commands_help_formatter_02.png deleted file mode 100644 index 64c544afe..000000000 Binary files a/DisCatSharp.Docs/images/commands_help_formatter_02.png and /dev/null differ diff --git a/DisCatSharp.Docs/images/commands_intro_01.png b/DisCatSharp.Docs/images/commands_intro_01.png index 7c71b1b6a..5ceb6dfe2 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_01.png and b/DisCatSharp.Docs/images/commands_intro_01.png differ diff --git a/DisCatSharp.Docs/images/commands_intro_03.png b/DisCatSharp.Docs/images/commands_intro_03.png index 50e9ca3ff..acd1ba27a 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_03.png and b/DisCatSharp.Docs/images/commands_intro_03.png differ diff --git a/DisCatSharp.Docs/images/commands_intro_05.png b/DisCatSharp.Docs/images/commands_intro_05.png index cf537a8e5..20dda5317 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_05.png and b/DisCatSharp.Docs/images/commands_intro_05.png differ diff --git a/DisCatSharp.Docs/images/commands_intro_06.png b/DisCatSharp.Docs/images/commands_intro_06.png index dc09489ab..8cade104b 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_06.png and b/DisCatSharp.Docs/images/commands_intro_06.png differ diff --git a/DisCatSharp.Docs/images/commands_intro_07.png b/DisCatSharp.Docs/images/commands_intro_07.png index ff48bc04c..593fe85a0 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_07.png and b/DisCatSharp.Docs/images/commands_intro_07.png differ diff --git a/DisCatSharp.Docs/images/commands_intro_08.png b/DisCatSharp.Docs/images/commands_intro_08.png index 34271b117..88051458b 100644 Binary files a/DisCatSharp.Docs/images/commands_intro_08.png and b/DisCatSharp.Docs/images/commands_intro_08.png differ diff --git a/DisCatSharp.Docs/images/interactivity_01.png b/DisCatSharp.Docs/images/interactivity_01.png index c37dccff0..0ecbe341e 100644 Binary files a/DisCatSharp.Docs/images/interactivity_01.png and b/DisCatSharp.Docs/images/interactivity_01.png differ diff --git a/DisCatSharp.Docs/images/voicenext_transmit_01.png b/DisCatSharp.Docs/images/voicenext_transmit_01.png index 8db7e369d..11429803c 100644 Binary files a/DisCatSharp.Docs/images/voicenext_transmit_01.png and b/DisCatSharp.Docs/images/voicenext_transmit_01.png differ diff --git a/README.md b/README.md index fd117f75d..4a93c0db7 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,133 @@ # DisCatSharp ![Stable](https://img.shields.io/nuget/v/DisCatSharp?color=%23ebb34b&label=Stable&style=flat-square&logo=nuget) ![Nightly](https://img.shields.io/nuget/vpre/DisCatSharp?color=%23ff1493&label=Nightly&style=flat-square&logo=nuget) ## A Discord Bot Library written in C# for .NET ![DisCatSharp Logo](https://github.com/Aiko-IT-Systems/DisCatSharp/blob/main/DisCatSharp.Logos/android-chrome-192x192.png?raw=true) ---- [![Build](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/dotnet.yml/badge.svg)](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/dotnet.yml) [![Documentation](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/docs.yml/badge.svg)](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/docs.yml) [![Typos](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/typos.yml/badge.svg)](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/typos.yml) [![CodeQL](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Aiko-IT-Systems/DisCatSharp/actions/workflows/codeql.yml) ![Wakatime](https://wakatime.com/badge/github/Aiko-IT-Systems/DisCatSharp.svg) [![AppVeyor](https://img.shields.io/appveyor/build/AITSYS/DisCatSharp?label=Appveyor&logo=appveyor&style=flat-square)](https://ci.appveyor.com/project/AITSYS/discatsharp) [![GitHub last commit](https://img.shields.io/github/last-commit/Aiko-IT-Systems/DisCatSharp?label=Last%20Commit&style=flat-square&logo=github)](https://aitsys.dev/source/DisCatSharp/history/) [![GitHub commit activity](https://img.shields.io/github/commit-activity/w/Aiko-IT-Systems/DisCatSharp?label=Commit%20Activity&style=flat-square&logo=github)](https://github.com/Aiko-IT-Systems/DisCatSharp/commits/main) [![GitHub pull requests](https://img.shields.io/github/issues-pr/Aiko-IT-Systems/DisCatSharp?label=PRs&style=flat-square&logo=github&logo=gitub)](https://github.com/Aiko-IT-Systems/DisCatSharp/pulls) ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/Aiko-IT-Systems/DisCatSharp?label=Size&style=flat-square&logo=github) ---- +# News -## **NEW!** +## New in DisCatSharp 10.1.0 - Support for application commands (guild and global) in shards - Translation template export based on your own code. +## Upcoming +- We're building a translation generator tool for the template export function introduced in 10.1.0. + +# About + ## Why DisCatSharp? If you: - want a library where you get kind and efficient help - would like to have and use the most recent features of the Discord API - are ready to build great things Then this is the right place for you! ## Installing -You can install the library from following source: [NuGet](https://www.nuget.org/profiles/DisCatSharp). +You can install the library from the following sources: +- [NuGet](https://www.nuget.org/profiles/DisCatSharp) +- [GitHub](https://github.com/orgs/Aiko-IT-Systems/packages?tab=packages&q=DisCatSharp) ## Documentation - - -The documentation of the nightly versions is available at [docs.dcs.aitsys.dev](https://docs.discatsharp.tech). +The documentation of the nightly versions is available at [docs.discatsharp.tech](https://docs.discatsharp.tech). -Fallback docs are available at [docs-alt.dcs.aitsys.dev](https://docs-alt.dcs.aitsys.dev). +Alternative hosts for our docs are: +- Backup Host [docs-alt.dcs.aitsys.dev](https://docs-alt.dcs.aitsys.dev) +- Cloudflare [fallback-docs.dcs.aitsys.dev](https://fallback-docs.dcs.aitsys.dev) or [discatsharp-docs.pages.dev](https://discatsharp-docs.pages.dev) -##### Note: DocFx is broken right now, waiting for fix from upstream. So the documentation is outdated. ## Bugs or Feature requests? Either join our official support guild at https://discord.gg/Uk7sggRBTm Or write us an mail at [bugs@aitsys.dev](mailto:bugs@aitsys.dev). -All requests are tracked at [aitsys.dev](https://aitsys.dev). +All requests are tracked at [aitsys.dev](https://aitsys.dev/project/view/1/). ## Tutorials * [Howto](https://docs.discatsharp.tech/articles/basics/bot_account.html) * [Examples](https://examples.dcs.aitsys.dev) ## Snippets [Snippets for Visual Studio](https://github.com/Aiko-IT-Systems/DisCatSharp.Snippets) ---- ## NuGet Packages ### Main | Package | Stable | Nightly | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | DisCatSharp | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | | DisCatSharp.ApplicationCommands | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.ApplicationCommands.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.ApplicationCommands.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | | DisCatSharp.CommandsNext | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.CommandsNext.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.CommandsNext.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | | DisCatSharp.Interactivity | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Interactivity.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Interactivity.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | ### Voice | Package | Stable | Nightly | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | DisCatSharp.Lavalink | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Lavalink.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Lavalink.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | | DisCatSharp.VoiceNext | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.VoiceNext.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.VoiceNext.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | | DisCatSharp.VoiceNext.Natives | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.VoiceNext.Natives.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.VoiceNext.Natives.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | ### Hosting | Package | Stable | Nightly | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | DisCatSharp.Configuration | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Configuration.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Configuration.svg?label=&logo=nuget&color=%23ff1493&style=flat-square) | | DisCatSharp.Hosting | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Hosting.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Hosting.svg?label=&logo=nuget&color=%23ff1493&style=flat-square) | | DisCatSharp.Hosting.DependencyInjection | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Hosting.DependencyInjection.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Hosting.DependencyInjection.svg?label=&logo=nuget&color=%23ff1493&style=flat-square) | ### Templates | Package | Stable | Nightly | | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | DisCatSharp.ProjectTemplates | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.ProjectTemplates.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.ProjectTemplates.svg?label=&logo=nuget&color=%23ff1493&style=flat-square) | ### Development / Commons | Package | Stable | Nightly | | ------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | DisCatSharp.Common | ![NuGet](https://img.shields.io/nuget/v/DisCatSharp.Common.svg?label=&logo=nuget&style=flat-square) | ![NuGet](https://img.shields.io/nuget/vpre/DisCatSharp.Common.svg?label=&logo=nuget&style=flat-square&color=%23ff1493) | ---- ## Sponsors [![Sponsors](https://img.shields.io/github/sponsors/Aiko-IT-Systems?label=&style=flat-square&logo=github)](https://github.com/sponsors/Aiko-IT-Systems) / [![Sponsors](https://img.shields.io/github/sponsors/Lulalaby?label=&style=flat-square&logo=github)](https://github.com/sponsors/Lulalaby) - [Deividas Kazakevicius](https://github.com/DeividasKaza) - [Will](https://github.com/villChurch) ## Thanks -Big thanks goes to the following people who helped us ♥️ +Big thanks goes to the following people who helped us without being part of the core team ♥️ - [Auros Nexus](https://github.com/Auros) - [Lunar Starstrum](https://github.com/OoLunar) -- [Johannes](https://github.com/JMLutra) - [Geferon](https://github.com/geferon) - [Alice](https://github.com/QuantuChi) - [Will](https://github.com/villChurch) -- [Mira](https://github.com/TheXorog) ## Special Thanks -The special thanks goes to Nagisa. Make sure to check out her [instagram](https://www.instagram.com/nagisaarts_/) ♥️♥️ +The special thanks goes to Nagisa. Make sure to check out her [Instagram](https://www.instagram.com/nagisaarts_/) ♥️♥️