diff --git a/DisCatSharp.Docs/articles/audio/lavalink/configuration.md b/DisCatSharp.Docs/articles/audio/lavalink/configuration.md index 23edcbe60..437daaf65 100644 --- a/DisCatSharp.Docs/articles/audio/lavalink/configuration.md +++ b/DisCatSharp.Docs/articles/audio/lavalink/configuration.md @@ -1,112 +1,112 @@ --- uid: audio_lavalink_configuration title: Lavalink Configuration --- -# Setting up DSharpPlus.Lavalink +# Setting up DisCatSharp.Lavalink ## Configuring Your Client To begin using DisCatSharp's Lavalink client, you will need to add the `DisCatSharp.Lavalink` nuget package. Once installed, simply add these namespaces at the top of your bot file: ```csharp using DisCatSharp.Net; using DisCatSharp.Lavalink; ``` After that, we will need to create a configuration for our extension to use. This is where the special values from the server configuration are used. ```csharp var endpoint = new ConnectionEndpoint { Hostname = "127.0.0.1", // From your server configuration. Port = 2333 // From your server configuration }; var lavalinkConfig = new LavalinkConfiguration { Password = "youshallnotpass", // From your server configuration. RestEndpoint = endpoint, SocketEndpoint = endpoint }; ``` Finally, initialize the extension. ```csharp var lavalink = Discord.UseLavalink(); ``` ## Connecting with Lavalink We are now ready to connect to the server. Call the Lavalink extension's connect method and pass the configuration. Make sure to call this **after** your Discord client connects. This can be called either directly after your client's connect method or in your client's ready event. ```csharp LavalinkNode = await Lavalink.ConnectAsync(lavalinkConfig); ``` Your main bot file should now look like this: ```csharp using System.Threading.Tasks; using Microsoft.Extensions.Logging; using DisCatSharp; using DisCatSharp.Net; using DisCatSharp.Lavalink; namespace MyFirstMusicBot { class Program { public static DiscordClient Discord; static void Main(string[] args) { MainAsync(args).ConfigureAwait(false).GetAwaiter().GetResult(); } static async Task MainAsync(string[] args) { Discord = new DiscordClient(new DiscordConfiguration { Token = "", TokenType = TokenType.Bot, MinimumLogLevel = LogLevel.Debug }); var endpoint = new ConnectionEndpoint { Hostname = "127.0.0.1", // From your server configuration. Port = 2333 // From your server configuration }; var lavalinkConfig = new LavalinkConfiguration { Password = "youshallnotpass", // From your server configuration. RestEndpoint = endpoint, SocketEndpoint = endpoint }; var lavalink = Discord.UseLavalink(); await Discord.ConnectAsync(); await lavalink.ConnectAsync(lavalinkConfig); // Make sure this is after Discord.ConnectAsync(). await Task.Delay(-1); } } } ``` We are now ready to start the bot. If everything is configured properly, you should see a Lavalink connection appear in your DisCatSharp console: ``` [2020-10-10 17:56:07 -04:00] [403 /LavalinkConn] [Debug] Connection to Lavalink node established ``` And a client connection appear in your Lavalink console: ``` INFO 5180 --- [ XNIO-1 task-1] io.undertow.servlet : Initializing Spring DispatcherServlet 'dispatcherServlet' INFO 5180 --- [ XNIO-1 task-1] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet' INFO 5180 --- [ XNIO-1 task-1] o.s.web.servlet.DispatcherServlet : Completed initialization in 8 ms INFO 5180 --- [ XNIO-1 task-1] l.server.io.HandshakeInterceptorImpl : Incoming connection from /0:0:0:0:0:0:0:1:58238 INFO 5180 --- [ XNIO-1 task-1] lavalink.server.io.SocketServer : Connection successfully established from /0:0:0:0:0:0:0:1:58238 ``` We are now ready to set up some music commands! diff --git a/DisCatSharp.Docs/articles/audio/lavalink/setup.md b/DisCatSharp.Docs/articles/audio/lavalink/setup.md index d50b47f52..cff66251b 100644 --- a/DisCatSharp.Docs/articles/audio/lavalink/setup.md +++ b/DisCatSharp.Docs/articles/audio/lavalink/setup.md @@ -1,93 +1,93 @@ --- uid: audio_lavalink_setup title: Lavalink Setup --- # Lavalink - the newer, better way to do music [Lavalink](https://github.com/freyacodes/Lavalink) is a standalone program, written in Java. It's a lightweight solution for playing music from sources such as YouTube or Soundcloud. Unlike raw voice solutions, such as VoiceNext, Lavalink can handle hundreds of concurrent streams, and supports sharding. ## Configuring Java In order to run Lavalink, you must have Java 13 or greater installed. Certain Java versions may not be functional with Lavalink, so it is best to check the [requirements](https://github.com/freyacodes/Lavalink#requirements) before downloading. The latest releases can be found [here](https://www.oracle.com/technetwork/java/javase/downloads/index.html). Make sure the location of the newest JRE's bin folder is added to your system variable's path. This will make the `java` command run from the latest runtime. You can verify that you have the right version by entering `java -version` in your command prompt or terminal. ## Downloading Lavalink Next, head over to the [releases](https://github.com/freyacodes/Lavalink/releases) tab on the Lavalink GitHub page and download the Jar file from the latest version. Alternatively, stable builds with the latest changes can be found on their [CI Server](https://ci.fredboat.com/viewLog.html?buildId=lastSuccessful&buildTypeId=Lavalink_Build&tab=artifacts&guest=1). The program will not be ready to run yet, as you will need to create a configuration file first. To do so, create a new YAML file called `application.yml`, and use the [example file](https://github.com/freyacodes/Lavalink/blob/master/LavalinkServer/application.yml.example), or copy this text: ```yaml server: # REST and WS server port: 2333 address: 127.0.0.1 spring: main: banner-mode: log lavalink: server: password: "youshallnotpass" sources: youtube: true bandcamp: true soundcloud: true twitch: true vimeo: true mixer: true http: true local: false bufferDurationMs: 400 youtubePlaylistLoadLimit: 6 # Number of pages at 100 each youtubeSearchEnabled: true soundcloudSearchEnabled: true gc-warnings: true metrics: prometheus: enabled: false endpoint: /metrics sentry: dsn: "" # tags: # some_key: some_value # another_key: another_value logging: file: max-history: 30 max-size: 1GB path: ./logs/ level: root: INFO lavalink: INFO ``` YAML is whitespace-sensitive. Make sure you are using a text editor which properly handles this. There are a few values to keep in mind. `host` is the IP of the Lavalink host. This will be `0.0.0.0` by default, but it should be changed as it is a security risk. For this guide, set this to `127.0.0.1` as we will be running Lavalink locally. `port` is the allowed port for the Lavalink connection. `2333` is the default port, and is what will be used for this guide. `password` is the password that you will need to specify when connecting. This can be anything as long as it is a valid YAML string. Keep it as `youshallnotpass` for this guide. When you are finished configuring this, save the file in the same directory as your Lavalink executable. Keep note of your `port`, `address`, and `password` values, as you will need them later for connecting. ## Starting Lavalink Open your command prompt or terminal and navigate to the directory containing Lavalink. Once there, type `java -jar Lavalink.jar`. You should start seeing log output from Lavalink. If everything is configured properly, you should see this appear somewhere in the log output without any errors: ``` [ main] lavalink.server.Launcher : Started Launcher in 5.769 seconds (JVM running for 6.758) ``` -If it does, congratulations. We are now ready to interact with it using DSharpPlus. +If it does, congratulations. We are now ready to interact with it using DisCatSharp. diff --git a/DisCatSharp.Docs/articles/audio/voicenext/prerequisites.md b/DisCatSharp.Docs/articles/audio/voicenext/prerequisites.md index 9a9c82299..33ca6a10e 100644 --- a/DisCatSharp.Docs/articles/audio/voicenext/prerequisites.md +++ b/DisCatSharp.Docs/articles/audio/voicenext/prerequisites.md @@ -1,37 +1,37 @@ --- uid: voicenext_prerequisites title: VoiceNext Prerequisites --- ## Required Libraries VoiceNext depends on the [libsodium](https://github.com/jedisct1/libsodium) and [Opus](https://opus-codec.org/) libraries to decrypt and process audio packets.
Both *must* be available on your development and host machines otherwise VoiceNext will *not* work. ### Windows When installing VoiceNext though NuGet, an additional package containing the native Windows binaries will automatically be included with **no additional steps required**. -However, if you are using DSharpPlus from source or without a NuGet package manager, you must manually [download](xref:natives) the binaries and place them at the root of your working directory where your application is located. +However, if you are using DisCatSharp from source or without a NuGet package manager, you must manually [download](xref:natives) the binaries and place them at the root of your working directory where your application is located. ### MacOS Native libraries for Apple's macOS can be installed using the [Homebrew](https://brew.sh) package manager: ```console $ brew install opus libsodium ``` ### Linux #### Debian and Derivatives Opus package naming is consistent across Debian, Ubuntu, and Linux Mint. ```bash sudo apt-get install libopus0 libopus-dev ``` Package naming for *libsodium* will vary depending on your distro and version: Distributions|Terminal Command :---:|:---: Ubuntu 20.04, Ubuntu 18.04, Debian 10|`sudo apt-get install libsodium23 libsodium-dev` Linux Mint, Ubuntu 16.04, Debian 9 |`sudo apt-get install libsodium18 libsodium-dev` Debian 8|`sudo apt-get install libsodium13 libsodium-dev` \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/basics/bot_account.md b/DisCatSharp.Docs/articles/basics/bot_account.md index 069200c25..85fd0f51b 100644 --- a/DisCatSharp.Docs/articles/basics/bot_account.md +++ b/DisCatSharp.Docs/articles/basics/bot_account.md @@ -1,91 +1,91 @@ --- uid: basics_bot_account title: Creating a Bot Account --- # Creating a Bot Account ## Create an Application Before you're able to create a [bot account](https://discord.com/developers/docs/topics/oauth2#bots) to interact with the Discord API, you'll need to create a new OAuth2 application. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click `New Application` at the top right of the page. ![Discord Developer Portal](/images/basics_bot_account_01.png)
You'll then be prompted to enter a name for your application.
![Naming Application](/images/basics_bot_account_02.png "Naming Application") The name of your application will be the name displayed to users when they add your bot to their Discord server.
With that in mind, it would be a good idea for your application name to match the desired name of your bot. Enter your desired application name into the text box, then hit the `Create` button. After you hit `Create`, you'll be taken to the application page for your newly created application. ![Application Page](/images/basics_bot_account_03.png) That was easy, wasn't it? Before you move on, you may want to upload an icon for your application and provide a short description of what your bot will do. As with the name of your application, the application icon and description will be displayed to users when adding your bot. ## Add a Bot Account Now that you have an application created, you'll be able to add a brand new bot account to it. Head on over to the bot page of your application by clicking on `Bot` in the left panel.
From there, click on the `Add Bot` button at the top right of the page. ![Bot Page](/images/basics_bot_account_04.png) Then confirm the creation of the bot account. ![Creation Confirmation](/images/basics_bot_account_05.png) # Using Your Bot Account ## Invite Your Bot Now that you have a bot account, you'll probably want to invite it to a server! A bot account joins a server through a special invite link that'll take users through the OAuth2 flow; you'll probably be familiar with this if you've ever added a public Discord bot to a server. To get the invite link for your bot, head on over to the OAuth2 page of your application. ![OAuth2](/images/basics_bot_account_06.png)
We'll be using the *OAuth2 URL Generator* on this page.
Simply tick `bot` under the *scopes* panel; your bot invite link will be generated directly below. ![OAuth2 Scopes](/images/basics_bot_account_07.png)
By default, the generated link will not grant any permissions to your bot when it joins a new server.
If your bot requires specific permissions to function, you'd select them in the *bot permissions* panel. ![Permissions](/images/basics_bot_account_08.png "Permissions Panel") The invite link in the *scopes* panel will update each time you change the permissions.
Be sure to copy it again after any changes! ## Get Bot Token Instead of logging in to Discord with a username and password, bot accounts use a long string called a *token* to authenticate. -You'll want to retrieve the token for your bot account so you can use it with DSharpPlus. +You'll want to retrieve the token for your bot account so you can use it with DisCatSharp. Head back to the bot page and click on `Click to Reveal Token` just above the `Copy` and `Regenerate` buttons to take a peek at your token. ![Token Reveal](/images/basics_bot_account_09.png "Token Reveal") Go ahead and copy your bot token and save it somewhere. You'll be using it soon! >[!IMPORTANT] > Handle your bot token with care! Anyone who has your token will have access to your bot account. > Be sure to store it in a secure location and *never* give it to *anybody*. > > If you ever believe your token has been compromised, be sure to hit the `Regenerate` button (as seen above) to invalidate your old token and get a brand new token. ## Write Some Code You've got a bot account set up and a token ready for use.
Sounds like it's time for you to [write your first bot](xref:basics_first_bot)! \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/beyond_basics/events.md b/DisCatSharp.Docs/articles/beyond_basics/events.md index f4454f067..7710cd5b5 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/events.md +++ b/DisCatSharp.Docs/articles/beyond_basics/events.md @@ -1,81 +1,81 @@ --- uid: beyond_basics_events -title: DSharpPlus Events +title: DisCatSharp Events --- # Consuming Events -DSharpPlus makes use of *asynchronous events* which will execute each handler asynchronously in sequential order. +DisCatSharp makes use of *asynchronous events* which will execute each handler asynchronously in sequential order. This event system will require event handlers have a `Task` return type and take two parameters. The first parameter will contain an instance of the object which fired the event.
The second parameter will contain an arguments object for the specific event you're handling. Below is a snippet demonstrating this with a lambda expression. ```cs private async Task MainAsync() { var discord = new DiscordClient(); discord.MessageCreated += async (s, e) => { if (e.Message.Content.ToLower().Contains("spiderman")) await e.Message.RespondAsync("I want pictures of Spiderman!"); }; discord.GuildMemberAdded += (s, e) => { // Non asynchronous code here. return Task.CompletedTask; }; } ``` Alternatively, you can create a new method to consume an event. ```cs private async Task MainAsync() { var discord = new DiscordClient(); discord.MessageCreated += MessageCreatedHandler; discord.GuildMemberAdded += MemberAddedHandler; } private async Task MessageCreatedHandler(DiscordClient s, MessageCreateEventArgs e) { if (e.Guild?.Id == 379378609942560770 && e.Author.Id == 168548441939509248) await e.Message.DeleteAsync(); } private Task MemberAddedHandler(DiscordClient s, GuildMemberAddEventArgs e) { // Non asynchronous code here. return Task.CompletedTask; } ``` # Avoiding Deadlocks Despite the fact that your event handlers are executed asynchronously, they are also executed one at a time on the gateway thread for consistency. This means that each handler must complete its execution before others can be dispatched. Because of this, executing code in your event handlers that runs for an extended period of time may inadvertently create brief unresponsiveness or, even worse, cause a [deadlock](https://en.wikipedia.org/wiki/Deadlock). To prevent such issues, any event handler that has the potential to take more than 2 seconds to execute should have its logic offloaded to a `Task.Run`. ```cs discord.MessageCreated += (s, e) => { _ = Task.Run(async () => { // Pretend this takes many, many seconds to execute. var response = await QuerySlowWebServiceAsync(e.Message.Content); if (response.Status == HttpStatusCode.OK) { await e.Guild?.BanMemberAsync((DiscordMember)e.Author); } }); return Task.CompletedTask; }; ``` Doing this will allow the handler to complete its execution quicker, which will in turn allow other handlers to be executed and prevent the gateway thread from being blocked. \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/beyond_basics/intents.md b/DisCatSharp.Docs/articles/beyond_basics/intents.md index 716b832cf..84b9bd2d7 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/intents.md +++ b/DisCatSharp.Docs/articles/beyond_basics/intents.md @@ -1,62 +1,62 @@ --- uid: beyond_basics_intents title: Intents --- ## Intents Intents were added to Discord to help the service not have to push so many events to the bots that were not using them. If you are going to be needing to subscribe to any type of event, they are going to have to be defined **BOTH** within the [Discord Application under the Bot Page](https://discord.com/developers/applications) on Discords Site and also within the @DisCatSharp.DiscordConfiguration. ### Discord Application On the [Discord Application under the Bot Page](https://discord.com/developers/applications) you will have to specify if your bot requires Privileged Intents. We recommend having these all enabled at first to ensure the most stability when building your first bot, otherwise you may run into issues when retrieving entities from the library's cache. ![Bot Page](/images/Intents.png) >[!WARNING] > These privileged intents may not be available for you to toggle on immediately. > > Due to their nature of sensitive data, Discord requires you to go through a verification process once your bot is in a certain amount of servers. > Please read this [blog post](https://support.discord.com/hc/en-us/articles/360040720412-Bot-Verification-and-Data-Whitelisting) for more information and how to apply. ### Discord Configuration Within your `DiscordConfiguration` you will have to specify all the intents you will need. Here is a list of all the -[Intents](xref:DisCatSharp.DiscordIntents) DSharpPlus Supports. By default, the configuration will use `DiscordIntents.AllUnprivileged` as the default value. Like above however, we recommend having all intents enabled at first, so you should specify `DiscordIntents.All` in your configuration which will include the privleged intents you enabled in your application: +[Intents](xref:DisCatSharp.DiscordIntents) DisCatSharp Supports. By default, the configuration will use `DiscordIntents.AllUnprivileged` as the default value. Like above however, we recommend having all intents enabled at first, so you should specify `DiscordIntents.All` in your configuration which will include the privleged intents you enabled in your application: ```csharp var config = new DiscordConfiguration() { Intents = DiscordIntents.All }; ``` When you become more advanced, you can try experimenting with turning off intents you do not need in order to save resources. In your `DiscordConfiguration` you can specify one or many. Here is an example of just specifying one: ```csharp var config = new DiscordConfiguration() { Intents = DiscordIntents.GuildMessages }; ``` Here is an example of specifying many: ```csharp var config = new DiscordConfiguration() { Intents = DiscordIntents.DirectMessageReactions | DiscordIntents.DirectMessages | DiscordIntents.GuildBans | DiscordIntents.GuildEmojis | DiscordIntents.GuildInvites | DiscordIntents.GuildMembers | DiscordIntents.GuildMessages | DiscordIntents.Guilds | DiscordIntents.GuildVoiceStates | DiscordIntents.GuildWebhooks, }; ``` Please Note, if you specify a privileged intent within your `DiscordConfiguration` that you have not signed up for on the Discord Application page, an error will be thrown on the connection. diff --git a/DisCatSharp.Docs/articles/beyond_basics/logging/default.md b/DisCatSharp.Docs/articles/beyond_basics/logging/default.md index 1ffd0c9b5..4d2c09a92 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/logging/default.md +++ b/DisCatSharp.Docs/articles/beyond_basics/logging/default.md @@ -1,54 +1,54 @@ --- uid: beyond_basics_logging_default title: The Default Logger --- ## The Default Logger -DSharpPlus ships with a default logging implementation which is **enabled automatically** with **no setup required**. +DisCatSharp ships with a default logging implementation which is **enabled automatically** with **no setup required**. ![Info Level Logging](/images/beyond_basics_logging_default_01.png) This is a basic implementation that only sends log messages to the console. #### Minimum Logging Level You're able to adjust the verbosity of log messages via `DiscordConfiguration`. ```cs new DiscordConfiguration() { MinimumLogLevel = LogLevel.Debug }; ``` The example above will display level log messages that are higher than or equal to `Debug`. ![Debug Level Logging](/images/beyond_basics_logging_default_02.png) #### Timestamp Format You're also able to change the format of the log timestamp; this is also set through `DiscordConfiguration`. ```cs new DiscordConfiguration() { LogTimestampFormat = "MMM dd yyyy - hh:mm:ss tt" }; ``` ![The Real Timestamp Format](/images/beyond_basics_logging_default_03.png) For a list of all available format specifiers, check out the MSDN page for [custom date and time format strings](https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings#day-d-format-specifier). ## Log Levels Below is a table of all log levels and the kind of messages you can expect from each. Name|Position|Description :---:|:---:|:--- `Critical`|5|Fatal error which may require a restart. `Error`|4| A failure of an operation or request. `Warning`|3|Non-fatal errors and abnormalities. `Information`|2|Session startup and resume messages. `Debug`|1| Ratelimit buckets and related information. `Trace`|0| Websocket & REST traffic. >[!WARNING] > The `Trace` log level is *not* recommended for use in production. > - > It is intended for debugging DSharpPlus and may display tokens and other sensitive data. \ No newline at end of file + > It is intended for debugging DisCatSharp and may display tokens and other sensitive data. \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/beyond_basics/logging/third_party.md b/DisCatSharp.Docs/articles/beyond_basics/logging/third_party.md index 29c335780..5b68b2c56 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/logging/third_party.md +++ b/DisCatSharp.Docs/articles/beyond_basics/logging/third_party.md @@ -1,63 +1,63 @@ --- uid: beyond_basics_logging_third_party title: Third Party Logging --- # Using a Third Party Logger While the default logging implementation will meet the needs of most, some may desire to make use of a more robust implementation which provides more features. -Thankfully, DSharpPlus allows you to use any logging library which has an implementation for the [logging abstractions](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging) provided by Microsoft. +Thankfully, DisCatSharp allows you to use any logging library which has an implementation for the [logging abstractions](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging) provided by Microsoft. [Serilog](https://serilog.net/), one of the more popular logging libraries, will be used to demonstrate. This will simply be a brief demo, so we won't go into the configuration of Serilog. You'll want to head on over to their [wiki page](https://github.com/serilog/serilog/wiki/Configuration-Basics) to learn about that! We'll need to install both the `Serilog` and `Serilog.Extensions.Logging` packages from NuGet, along with at least one of the many available [sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks). Our example here will only use the `Serilog.Sinks.Console` sink.
Start off by creating a new `LoggerConfiguration` instance, slap `.WriteTo.Console().CreateLogger()` onto the end of it, then directly assign that to the static `Logger` property on the `Log` class. ```cs Log.Logger = new LoggerConfiguration() .WriteTo.Console() .CreateLogger(); ``` This will make a new Serilog logger instance which will write to the console sink.
Next, create a new variable and assign it a new `LoggerFactory` instance which calls `AddSerilog()`. ```cs var logFactory = new LoggerFactory().AddSerilog(); ``` Then assign that variable to the `LoggerFactory` property of your of `DiscordConfiguration`. ```cs new DiscordConfiguration() { LoggerFactory = logFactory } ```
Altogether, you'll have something similar to this: ```cs using Microsoft.Extensions.Logging; using Serilog; public async Task MainAsync() { Log.Logger = new LoggerConfiguration() .WriteTo.Console() .CreateLogger(); var logFactory = new LoggerFactory().AddSerilog(); var discord = new DiscordClient(new DiscordConfiguration() { LoggerFactory = logFactory }); } ``` -And that's it! If you now run your bot, you'll see DSharpPlus log messages formatted and displayed by Serilog. +And that's it! If you now run your bot, you'll see DisCatSharp log messages formatted and displayed by Serilog. ![Console](/images/beyond_basics_logging_third_party_01.png) \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/beyond_basics/messagebuilder.md b/DisCatSharp.Docs/articles/beyond_basics/messagebuilder.md index 27312547a..2b3c1d304 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/messagebuilder.md +++ b/DisCatSharp.Docs/articles/beyond_basics/messagebuilder.md @@ -1,60 +1,60 @@ --- uid: beyond_basics_messagebuilder title: Message Builder --- ## Background Before the message builder was put into place, we had one large method for sending messages along with 3 additional methods for sending files. This was becoming a major code smell and it was hard to maintain and add more parameters onto it. Now we support just sending a simple message, an embed, a simple message with an embed, or a message builder. ## Using the Message Builder -The API Documentation for the message builder can be found at @DSharpPlus.Entities.DiscordMessageBuilder but here we'll go over some of the concepts of using the -message builder: +The API Documentation for the message builder can be found [there](xref:DisCatSharp.Entities.DiscordMessageBuilder), +but here we'll go over some of the concepts of using the message builder: ### Adding a File: For sending files, you'll have to use the MessageBuilder to construct your message, see example below: ```cs using (var fs = new FileStream("ADumbFile.txt", FileMode.Open, FileAccess.Read)) { var msg = await new DiscordMessageBuilder() .WithContent("Here is a really dumb file that I am testing with.") .WithFiles(new Dictionary() { { "ADumbFile1.txt", fs } }) .SendAsync(ctx.Channel); } ``` ### Adding Mentions For sending mentions, you'll have to use the MessageBuilder to construct your message, see example below: ```cs var msg = await new DiscordMessageBuilder() .WithContent($"✔ UserMention(user): Hey, {user.Mention}! Listen!") .WithAllowedMentions(new IMention[] { new UserMention(user) }) .SendAsync(ctx.Channel); ``` ### Sending TTS Messages For sending a TTS message, you'll have to use the MessageBuilder to construct your message, see example below: ```cs var msg = await new DiscordMessageBuilder() .WithContent($"This is a dumb message") .HasTTS(true) .SendAsync(ctx.Channel); ``` ### Sending an Inline Reply For sending an inline reply, you'll have to use the MessageBuilder to construct your message, see example below: ```cs var msg = await new DiscordMessageBuilder() .WithContent($"I'm talking to *you*!") .WithReply(ctx.Message.Id) .SendAsync(ctx.Channel); ``` By default, replies do not mention. To make a reply mention, simply pass true as the second parameter: ```cs // ... .WithReply(ctx.Message.Id, true); // ... ``` diff --git a/DisCatSharp.Docs/articles/beyond_basics/sharding.md b/DisCatSharp.Docs/articles/beyond_basics/sharding.md index be6ccf237..2a39b9519 100644 --- a/DisCatSharp.Docs/articles/beyond_basics/sharding.md +++ b/DisCatSharp.Docs/articles/beyond_basics/sharding.md @@ -1,36 +1,36 @@ --- uid: beyond_basics_sharding title: Sharding --- # Sharding As your bot joins more guilds, your poor `DiscordClient` will be hit with an increasing number of events. Thankfully, Discord allows you to establish multiple connections to split the event workload; this is called *sharding* and each individual connection is referred to as a *shard*. Each shard handles a separate set of servers and will *only* receive events from those servers. However, all direct messages will be handled by your first shard. Sharding is recommended once you reach 1,000 servers, and is a *requirement* when you hit 2,500 servers. ## Automated Sharding -DSharpPlus provides a built-in sharding solution: `DiscordShardedClient`. +DisCatSharp provides a built-in sharding solution: `DiscordShardedClient`. This client will *automatically* spawn shards for you and manage their events. -Each DSharpPlus extension (e.g. CommandsNext, Interactivity) also supplies an extension method to register themselves automatically on each shard. +Each DisCatSharp extension (e.g. CommandsNext, Interactivity) also supplies an extension method to register themselves automatically on each shard. ```cs var discord = new DiscordShardedClient(new DiscordConfiguration { Token = "My First Token", TokenType = TokenType.Bot }); await discord.UseCommandsNextAsync(new CommandsNextConfiguration() { StringPrefixes = new[] { "!" } }); ``` ## Manual Sharding For most looking to shard, the built-in `DiscordShardedClient` will work well enough. However, those looking for more control over the sharding process may want to handle it manually. This would involve creating new `DiscordClient` instances, assigning each one an appropriate shard ID number, and handling the events from each instance. Considering the potential complexity imposed by this process, you should only do this if you have a valid reason to do so and *know what you are doing*. \ No newline at end of file diff --git a/DisCatSharp.Docs/articles/commands/argument_converters.md b/DisCatSharp.Docs/articles/commands/argument_converters.md index 38e620898..c2e7ed760 100644 --- a/DisCatSharp.Docs/articles/commands/argument_converters.md +++ b/DisCatSharp.Docs/articles/commands/argument_converters.md @@ -1,60 +1,60 @@ --- uid: commands_argument_converters title: Argument Converter --- ## Custom Argument Converter Writing your own argument converter will enable you to convert custom types and replace the functionality of existing converters. -Like many things in DSharpPlus, doing this is straightforward and simple. +Like many things in DisCatSharp, doing this is straightforward and simple. First, create a new class which implements `IArgumentConverter` and its method `ConvertAsync`. Our example will be a boolean converter, so we'll also pass `bool` as the type parameter for `IArgumentConverter`. ```cs public class CustomArgumentConverter : IArgumentConverter { public Task> ConvertAsync(string value, CommandContext ctx) { if (bool.TryParse(value, out var boolean)) { return Task.FromResult(Optional.FromValue(boolean)); } switch (value.ToLower()) { case "yes": case "y": case "t": return Task.FromResult(Optional.FromValue(true)); case "no": case "n": case "f": return Task.FromResult(Optional.FromValue(false)); default: return Task.FromResult(Optional.FromNoValue()); } } } ``` Then register the argument converter with CommandContext. ```cs var discord = new DiscordClient(); var commands = discord.UseCommandsNext(); commands.RegisterConverter(new CustomArgumentConverter()); ```
Once the argument converter is written and registered, we'll be able to use it: ```cs [Command("boolean")] public async Task BooleanCommand(CommandContext ctx, bool boolean) { await ctx.RespondAsync($"Converted to {boolean}"); } ``` ![true](/images/commands_argument_converters_01.png) diff --git a/DisCatSharp.Docs/articles/misc/reporting_issues.md b/DisCatSharp.Docs/articles/misc/reporting_issues.md index ea4bd1122..2fdb5c59d 100644 --- a/DisCatSharp.Docs/articles/misc/reporting_issues.md +++ b/DisCatSharp.Docs/articles/misc/reporting_issues.md @@ -1,35 +1,32 @@ --- uid: misc_reporting_issues title: Reporting Issues --- # I broke something, and I need it fixed! We always try to fix bugs, and make sure that when we release the next version of DSharpPlus-NextGen, everything is polished and -working. However, DSharpPlus-NextGen is a large codebase, and we can't always catch all the bugs, or notice all the regressions +working. However, DisCatSharp is a large codebase, and we can't always catch all the bugs, or notice all the regressions that happen while we fix bugs or implement new issues. -## GitHub issue tracker +## Issue tracker -If you find a bug, come up with a new idea, or just want to report something, you can open an issue on our -[GitHub Issue Tracker](https://github.com/Aiko-IT-Systems/DSharpPlus-NextGen/issues "DSharpPlus-NextGen issues on GitHub"). +If you find a bug, come up with a new idea, or just want to report something, you can open an ticket on our support [server](https://discord.gg/discatsharp). -When opening an issue, make sure to include as much detail as possible. If at all possible, please include: +[Issue Tracker](https://bugs.aitsys.dev/project/view/1/ "DisCatSharp issues"). + +When reporting an issue, make sure to include as much detail as possible. If at all possible, please include: * Steps to reproduce the issue * What were you trying to achieve * Expected/acutal result * Stack traces, exception types, messages * Attempted solutions -## Discord - -Some questions, most notably questions on using the library, are better asked on Discord. You can find the server links on the [preamble](xref:preamble). - ## Contributing Lastly, while we understand that not everyone is an expert programmer, we would appreciate it if you could fix any issues you find and submit a Pull Request on GitHub. This would reduce the amount of work we would have to do. When contributing, ensure your code matches the style of the rest of the library, and that you test the changes you make, and catch any possible regressions. diff --git a/DisCatSharp.Docs/images/beyond_basics_logging_third_party_01.png b/DisCatSharp.Docs/images/beyond_basics_logging_third_party_01.png index f101c8189..c18f651fd 100644 Binary files a/DisCatSharp.Docs/images/beyond_basics_logging_third_party_01.png and b/DisCatSharp.Docs/images/beyond_basics_logging_third_party_01.png differ