From 25ed4aee630555db9ca7d4a01c328f866b3ea2d0 Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Fri, 15 Feb 2019 17:46:04 +0800 Subject: [PATCH] Revise "Your First Bot" article * Merge some paragraphs to avoid clutter while keeping readability * Reword the use of command framework + Add additional warning/note about environment variable --- docs/guides/getting_started/first-bot.md | 54 ++++++++++++++---------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/docs/guides/getting_started/first-bot.md b/docs/guides/getting_started/first-bot.md index a33e72aff..6f71a605b 100644 --- a/docs/guides/getting_started/first-bot.md +++ b/docs/guides/getting_started/first-bot.md @@ -128,12 +128,10 @@ Finally, we can create a new connection to Discord. Since we are writing a bot, we will be using a [DiscordSocketClient] along with socket entities. See @Guides.GettingStarted.Terminology -if you are unsure of the differences. - -To establish a new connection, we will create an instance of -[DiscordSocketClient] in the new async main. You may pass in an -optional @Discord.WebSocket.DiscordSocketConfig if necessary. For most -users, the default will work fine. +if you are unsure of the differences. To establish a new connection, +we will create an instance of [DiscordSocketClient] in the new async +main. You may pass in an optional @Discord.WebSocket.DiscordSocketConfig +if necessary. For most users, the default will work fine. Before connecting, we should hook the client's `Log` event to the log handler that we had just created. Events in Discord.Net work @@ -142,22 +140,33 @@ similarly to any other events in C#. Next, you will need to "log in to Discord" with the [LoginAsync] method with the application's "token." +![Token](images/intro-token.png) + > [!NOTE] > Pay attention to what you are copying from the developer portal! > A token is not the same as the application's "client secret." -![Token](images/intro-token.png) - > [!IMPORTANT] > Your bot's token can be used to gain total access to your bot, so -> **do __NOT__ share this token with anyone else!** It may behoove you -> to store this token in an external source if you plan on distributing +> **do not** share this token with anyone else! You should store this +> token in an external source if you plan on distributing > the source code for your bot. +> +> In the following example, we retrieve the token from the environment +> variable `DiscordToken`. Please note that this is *not* designed to +> be used in a production environment, as the secrets are stored in +> plain-text. +> +> For information on how to set an environment variable, please see +> instructions below, +> +> * Windows: [How to Create Environment Variables Shortcut in Windows](https://www.tenforums.com/tutorials/121742-create-environment-variables-shortcut-windows.html) +> * Linux: [How To Read and Set Environmental and Shell Variables on a Linux VPS](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps) +> * macOS: [How do I set environment variables on OS X?](https://apple.stackexchange.com/questions/106778/how-do-i-set-environment-variables-on-os-x) We may now invoke the client's [StartAsync] method, which will start connection/reconnection logic. It is important to note that **this method will return as soon as connection logic has been started!** - Any methods that rely on the client's state should go in an event handler. This means that you should **not** directly be interacting with the client before it is fully ready. @@ -194,27 +203,26 @@ online in Discord. > [!WARNING] > Please note that this is *not* a proper way to create a command. -> Use the `CommandService` provided by the library instead, as explained -> in the [Command Guide](xref:Guides.Commands.Intro) section. +> +> Consider using a command framework instead. One is provided to you +> in `Discord.Net.Commands`; see @Guides.Commands.Intro for more +> information. Now that we have learned to open a connection to Discord, we can -begin handling messages that the users are sending. To start out, our -bot will listen for any message whose content is equal to `!ping` and -will respond back with "Pong!". +begin handling messages that the users are sending. -Since we want to listen for new messages, the event to hook into -is [MessageReceived]. +To start out, our bot will listen for any message whose content +is equal to `!ping` and will respond back with "Pong!". Since we want +to listen for new messages, the event to hook into is [MessageReceived]. In your program, add a method that matches the signature of the `MessageReceived` event - it must be a method (`Func`) that returns the type `Task` and takes a single parameter, a [SocketMessage]. Also, since we will be sending data to Discord in this method, we will flag it as `async`. - -In this method, we will add an `if` block to determine if the message -content fits the rules of our scenario - recall that it must be equal -to `!ping`. - +In this method, we will add an `if` block to +determine if the message content fits the rules of our scenario - +recall that it must be equal to `!ping`. Inside the branch of this condition, we will want to send a message, `Pong!`, back to the channel from which the message comes from. To find the channel, look for the `Channel` property on the message