Your First Bot

Note

This article assumes the following:

• You have created a bot account and have a bot token.
• You have Visual Studio 2019 installed on your computer.

Create a Project

Open up Visual Studio and click on Create a new project towards the bottom right.

Select Console App (.NET Core) then click on the Next button.

Next, you'll give your project a name. For this example, we'll name it MyFirstBot. If you'd like, you can also change the directory that your project will be created in.

Enter your desired project name, then click on the Create button.

Voilà! Your project has been created!

Install Package

Now that you have a project created, you'll want to get DSharpPlus installed. Locate the solution explorer on the right side, then right click on Dependencies and select Manage NuGet Packages from the context menu.

You'll then be greeted by the NuGet package manager.

Select the Browse tab towards the top left, then type DSharpPlus into the search text box.

The first results should be the six DSharpPlus packages.

Package	Description
DSharpPlus	Main package; Discord API client.
DSharpPlus.CommandsNext	Add-on which provides a command framework.
DSharpPlus.SlashCommands	Add-on which provides an application command framework.
DSharpPlus.Interactivity	Add-on which allows for interactive commands.
DSharpPlus.Lavalink	Client implementation for Lavalink. Useful for music bots.
DSharpPlus.VoiceNext	Add-on which enables connectivity to Discord voice channels.
DSharpPlus.Rest	REST-only Discord client.

We'll only need the DSharpPlus package for the basic bot we'll be writing in this article. Select it from the list then click the Install button to the right (after verifing that you will be installing the latest version).

You're now ready to write some code!

First Lines of Code

DSharpPlus implements Task-based Asynchronous Pattern. Because of this, the majority of DSharpPlus methods must be executed in a method marked as async so they can be properly awaited.

Due to the way the compiler generates the underlying IL code, marking our Main method as async has the potential to cause problems. As a result, we must pass the program execution to an async method.

Head back to your Program.cs tab and empty the Main method by deleting line 9.

Now, create a new static method named MainAsync beneath your Main method. Have it return type Task and mark it as async. After that, add MainAsync().GetAwaiter().GetResult(); to your Main method.

static void Main(string[] args)
{
    MainAsync().GetAwaiter().GetResult();
}

static async Task MainAsync()
{

}   

If you typed this in by hand, Intellisense should have generated the required using directive for you. However, if you copy-pasted the snippet above, VS will complain about being unable to find the Task type.

Hover over Task with your mouse and click on Show potential fixes from the tooltip.

Then apply the recommended solution.

We'll now create a new DiscordClient instance in our brand new asynchronous method.

Create a new variable in MainAsync and assign it a new DiscordClient instance, then pass an instance of DiscordConfiguration to its constructor. Create an object initializer for DiscordConfiguration and populate the Token property with your bot token then set the TokenType property to Bot. Next add the Intents property and populated it with the AllUnprivileged value. These Intents are required for certain Events to be fired. Please visit this article for more information.

var discord = new DiscordClient(new DiscordConfiguration()
{
    Token = "My First Token",
    TokenType = TokenType.Bot,
    Intents = DiscordIntents.AllUnprivileged     
});

Warning

We hard-code the token in the above snippet to keep things simple and easy to understand.

Hard-coding your token is not a smart idea, especially if you plan on distributing your source code. Instead you should store your token in an external medium, such as a configuration file or environment variable, and read that into your program to be used with DSharpPlus.

Follow that up with ConnectAsync to connect and login to Discord, and await Task.Delay(-1); at the end of the method to prevent the console window from closing prematurely.

var discord = new DiscordClient();

await discord.ConnectAsync();
await Task.Delay(-1);

As before, Intellisense will have auto generated the needed using directive for you if you typed this in by hand. If you've copied the snippet, be sure to apply the recommended suggestion to insert the required directive.

If you hit F5 on your keyboard to compile and run your program, you'll be greeted by a happy little console with a single log message from DSharpPlus. Woo hoo!

Spicing Up Your Bot

Right now our bot doesn't do a whole lot. Let's bring it to life by having it respond to a message!

Hook the MessageCreated event fired by DiscordClient with a lambda. Mark it as async and give it two parameters: s and e.

discord.MessageCreated += async (s, e) =>
{

};

Then, add an if statement into the body of your event lambda that will check if Content starts with your desired trigger word and respond with a message using RespondAsync if it does. For this example, we'll have the bot to respond with pong! for each message that starts with ping.

discord.MessageCreated += async (s, e) =>
{
    if (e.Message.Content.ToLower().StartsWith("ping")) 
        await e.Message.RespondAsync("pong!");
};

The Finished Product

Your entire program should now look like this:

using System;
using System.Threading.Tasks;
using DSharpPlus;

namespace MyFirstBot
{
    class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        static async Task MainAsync()
        {
            var discord = new DiscordClient(new DiscordConfiguration()
            {
                Token = "My First Token",
                TokenType = TokenType.Bot
            });

            discord.MessageCreated += async (s, e) =>
            {
                if (e.Message.Content.ToLower().StartsWith("ping")) 
                    await e.Message.RespondAsync("pong!");

            };

            await discord.ConnectAsync();
            await Task.Delay(-1);
        }
    }
}

Hit F5 to run your bot, then send ping in any channel your bot account has access to. Your bot should respond with pong! for each ping you send.

Congrats, your bot now does something!

Further Reading

Now that you have a basic bot up and running, you should take a look at the following:

• Events
• CommandsNext