DEV Community: Bizzycola

Setup Banjo-Kazooie Decomp in WSL with VS Code

Bizzycola — Thu, 26 Sep 2024 23:32:57 +0000

Prerequisites

Before you install WSL, you will need to have virtualisation enabled on your PC. The steps from this vary depending on your hardware, as you’ll likely need to enable it in your BIOS if it is not enabled. Easiest way to find out is to just google your motherboard model (or laptop/prebuilt PC model) along with “enabling virtualization”.

WSL Setup

Command Prompt

There’s some commands here to run so first step is to open an Administrator command prompt. You can just right-click your start menu (the Windows icon) and click either “Terminal (Admin)” or “Command Prompt (Admin)” depending on which you see.

Automatic WSL installation (preferred)

Setting up WSL in Windows 11 and later versions of Windows 10 after enabling virtualization should be as simple as just opening an Administrator command prompt and typing wsl –install.

This doesn’t always work as intended and there are some manual steps that can be used instead.

Manual WSL installation (only if auto fails)

First, run this command to enable the feature:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

This will install the first version of WSL (this is a built-in Windows command for managing OS and features).
Now, run this command to enable the Virtual Machine feature in Windows:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

If you get any errors stating the operation couldn't be started, you may also need to run this (and reboot after) to enable Hyper-V

DISM /Online /Enable-Feature /All /FeatureName:Microsoft-Hyper-V

Then try the above commands again.

Next you will need to download and install the WSL2 kernal from Microsoft: https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

Close and re-open your command prompt and run this command: wsl --set-default-version 2 - this will set WSL to use version 2.

OS Install

After installing WSL, you now need to install a linux distribution into it. We’ll just use Ubuntu 22.04 in this case, you can follow this link to find it or search for “Ubuntu” in the Windows Store app: https://www.microsoft.com/store/apps/9PN20MSR04DW

Once installed, you can open the Ubuntu terminal by searching for it on your PC (click the search bar in your taskbar or open the Start menu and just start typing Ubuntu):

The first time it opens it will prompt you to setup a username and password – do this and remember the credentials, you will need them later. Your username must be lowercase and alphanumeric, or you will receive a Regular Expression error.

NOTE If you don't setup a user, you will be pushed to use the root user which is not recommended and will differ from these instructions.

If you run into issues, see the troubleshooting steps from Microsoft: https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#installation-issues or check their official manual installation guide here: https://learn.microsoft.com/en-us/windows/wsl/install-manual

Visual Studio Code

Next, lets setup the code editor we’ll be using. First, lets install it. Head here: https://code.visualstudio.com/Download and download the Windows installer for VS Code. Once downloaded, run the installer and set it up.
Once done, open VS Code, click the Extensions icon in the sidebar:

Now search for and install the WSL extension:

Now, click the Remote tab:

Make sure you have WSL selected:

You should see your Ubuntu in the list. Click the arrow to connect.

Once connected, click the file explorer in the sidebar and click Open Folder:

The box that pops up should default to your home directory, click OK.

Now, in the top menu bar open a new terminal:

This’ll open a terminal in your WSL instance:

Cloning Decomp

Cloning git repository

Now we’ll pull down the BK repository to work on.

In that terminal, paste the following command (you can right-click to paste, don’t use ctrl+v):

git clone https://gitlab.com/banjo.decomp/banjo-kazooie.git

This will pull down a copy of the BK decomp repository into the banjo-kazooie directory.

Now, type cd banjo-kazooie.

Setup BK dependencies

Working on the repository requires some dependencies to be installed and some submodules to be pulled down. So now we’re in the banjo-kazooie directory lets run all the commands.

Before continuing, make sure you're in the banjo-kazooie directory we cloned into, or the commands may not work correctly:

cd ~/banjo-kazooie/

You should be able to see "banjo-kazooie" in your terminal prompt:

Now lets install our dependencies.

First, run this to install system dependencies:

sudo apt-get update && sudo apt-get install -y $(cat packages.txt)

Note, this command will ask you for a password. You need to enter the password you used when you installed Ubuntu earlier. You won't see the characters in the terminal as you type, this is normal.

Once done, run this to install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Press 1 for default installation and hit enter.

Then run this to pull down the child git repositories needed:

git submodule update --init --recursive

And this to install the Python dependencies:

python3 -m pip install -r requirements.txt

Note If you get an error regarding an externally managed environment, you can force the installation:

python3 -m pip install -r requirements.txt --break-system-packages

Or if you're a little skilled with Python commands, you can create a virtual environment to work in.

Before we continue, we need to run a command to get rust into our PATH:

source ~/.profile

VS Code

Before we continue, it's worth opening the Banjo-Kazooie folder in VS Code.

(Note in WSL you should also be able to type code . into the terminal and hit enter when you are CD'd into the banjo-kazooie directory to launch VS Code there, but the following instructions will show you how to use the UI to get there)

Go File -> Open Folder:

Add banjo-kazooie onto the path as seen below and click Okay. This will open banjo-kazooie as the root folder in VS Code.

Rom

This part is trickier. I can’t provide a Banjo-Kazooie US 1.0 rom for you nor tell you how to get one. You need to supply this yourself.

Once you have the rom (ending in .z64), rename it to baserom.us.v10.z64. Bring up your Visual Studio Code instance and drag baserom.us.v10.z64 from your PC to the file explorer. Be sure to drop it on the area with files per the highlighted screenshot below, do NOT drop it into any of the directories at the top:

(You can see I have the baserom.us.v10.z64 in my list there, you should see it there in yours once it finishes copying).

In your terminal, run the following command:

sha1sum baserom.us.v10.z64

Per the BK decomp instructions, the hash returned from this should match the following: 1fe1632098865f639e22c11b9a81ee8f29c75d7a

If it doesn’t, you likely have an incorrect rom and need to find another one.

Building

Now all this is done you can try typing make into your terminal and you should get a BK rom built into the build folder:

Note the first time you build the terminal will likely end with baserom.us.v10.z64 OK, once you have made changes to the code it will end with baserom.us.v10.z64 differs. This is normal.

So, now your rom is built, how do you get it out? You can actually browse your Ubuntu files directly from the Windows file explorer, with the Linux option in the sidebar of an explorer window:

Browse to Linux -> Ubuntu -> Home -> YOURUSERNAME -> banjo-kazooie -> build, grab your rom and load it up in an emulator to see how you did!

Your first mod

Let's create a simple mod that takes you straight to the file select when you open the game. In your VS code, browse to core1 -> code_0.c.
At the bottom of this file we have a function called setBootMap. We're going to change the gBootMap value to MAP_91_FILE_SELECT. Your function should now look like this:

void setBootMap(enum map_e map_id){
    gBootMap = MAP_91_FILE_SELECT;
}

Now run make in your terminal, find the rom, launch the game and you should be in the file select with no intro!

Thanks

Thanks to giantjigglypuff3 for helping me get this setup.

Authenticating WebSocket connections in GraphQL with JWT, Asp.Net Core & HotChocolate

Bizzycola — Fri, 19 Mar 2021 17:14:25 +0000

UPDATE

The latest versions of HotChocolate change how the socket session override classes work. Here is a quick example of some code that is working for 13.8.1.

JWT auth code is the same, follow the rest of the guide for more information and use this code as a base for your DefaultSocketSessionInterceptor implementation.

public class SocketConnectPayload
{
    public string Authorization { get; set; }
}

public class SubscriptionAuthMiddleware : DefaultSocketSessionInterceptor
{
    public override async ValueTask<ConnectionStatus> OnConnectAsync(ISocketSession connection, IOperationMessagePayload message, CancellationToken cancellationToken)
    {
        try
        {
            using var scope = connection.Connection.HttpContext.RequestServices.CreateScope();
            var payload = message.As<SocketConnectPayload>();
            var jwtHeader = payload.Authorization;

            if (!jwtHeader.StartsWith("Bearer "))
                return ConnectionStatus.Reject("Unauthorized");

            var token = jwtHeader.Replace("Bearer ", "");

            var opts = scope.ServiceProvider.GetRequiredService<JwtBearerOptions>();

            var claims = new JwtBearerBacker(opts).IsJwtValid(token);
            if (claims == null)
                return ConnectionStatus.Reject("Unauthoized(invalid token)");

            var userId = claims.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "";
            connection.Connection.HttpContext.Items["userId"] = userId;

            // Find the user
            using var ctx = scope.ServiceProvider.GetRequiredService<IDbContextFactory<DataContext>>().CreateDbContext();
            var user = await ctx.Users.FirstOrDefaultAsync(p => p.UserId == userId);
            if (user == null) return ConnectionStatus.Reject("Profile not created");

            connection.Connection.HttpContext.Items["userObj"] = user;

            return ConnectionStatus.Accept();
        }
        catch (Exception ex)
        {
            return ConnectionStatus.Reject(ex.Message);
        }
    }
}

Also, as mentioned by @marcinjaniak in the comments, this code does not handle JWT expirations on already established websocket connections (see their comment for an example on handling this).

The Problem

Whilst building a deployment tool for our backend services, I spent quite some time trying to work out how to correctly authenticate GraphQL Subscription(websocket) connections in HotChocolate.

My first thought was headers, but after quite some research I found that I cannot inject an authorization header into a websocket as the spec doesn't allow for headers and web browser just don't support it.

But after quite a bit of digging and figuring out how we'd managed this in node projects in the past, I found that the authorization header actually is still sent when the subscription websocket is connected, but rather than a header, it is sent with a payload that arrives on the initial connected state.

The Solution

So, now that I worked out how the authorization header can be sent, the next step was figuring out how to get this payload in HotChocolate.

After some digging, I found there is an extension method to services.AddGraphQLServer() entitled .AddSocketSessionInterceptor<T>().

Some additional digging found that T should be a class that extends from ISocketSessionInterceptor, a class with 3 methods for handling websocket events: OnCloseAsync, OnRequestAsync and OnConnectAsync. In this case, OnConnectAsync was the method I needed to parse our connection payload.

Building SubscriptionAuthMiddleware

So first off, we should setup our class, extend from ISocketSessionInterceptor and add our extension methods. Here is a skeleton class to start:

public class SubscriptionAuthMiddleware : ISocketSessionInterceptor 
{
    public async ValueTask OnCloseAsync(ISocketConnection connection, CancellationToken cancellationToken) { }
    public async ValueTask OnRequestAsync(ISocketConnection connection, IQueryRequestBuilder requestBuilder, CancellationToken cancellationToken) { }

    /* We don't need the above two methods, just this one */
    public async ValueTask<ConnectionStatus> OnConnectAsync(ISocketConnection connection, InitializeConnectionMessage message, CancellationToken cancellationToken) 
    {
        try 
        {

        }
        catch(Exception ex)
        {
            // If we catch any exceptions, reject the connection.
            // This is probably not ideal, there is likely a way to return a message
            // but I didn't look that far into it.
            return ConnectionStatus.Reject(ex.Message);
        }
    }
}

So now we have our class ready, we can start adding to OnConnectAsync. The payload we recieve can be found under message.Payload.
So lets grab our JWT, and fail if the JWT is not present. Add this code inside our try statement:

var jwtHeader = message.Payload["Authorization"] as string;

if (string.IsNullOrEmpty(jwtHeader) || !jwtHeader.StartsWith("Bearer "))
    return ConnectionStatus.Reject("Unauthorized");

var token = jwtHeader.Replace("Bearer ", "");

This will grab "Authorization" from payload if it exists, then check it contains the 'Bearer' part of the header. If it doesn't, reject the connection.
After that, we parse out the "Bearer " from the header and are left with our JWT.

JWT Config Shenanigans

Before we continue, we're going to have to take a brief adventure over to our JWT setup in Startup.cs as we need to add our JWT config to the service provider.
Simply put, we're going to extract the JWT Config out of .AddJwtBearer, give it its own variable and add it to our service provider. I won't provide much details on how to do this as it's fairly simple. This is what I have afterwards:

var opts = new JwtBearerOptions()
{
    Authority = Configuration["Auth:Authority"],
    TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidIssuer = Configuration["Auth:Authority"],
        ValidateAudience = true,
        ValidAudience = Configuration["Auth:Audience"],
        ValidateLifetime = true
    }
};
services.AddSingleton(opts);

services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = opts.Authority;
        options.TokenValidationParameters = opts.TokenValidationParameters;
    });

This should get us by, we'll come back to why we did that later when we get to configuring our JWT validation.

Building our JWT Validator

Before we can parse our JWT, we are going to need to build a class to validate it outside the usual ASP.Net Core Authentication pipeline.
Before we continue, I'd like to give credit to Christopher J. where I got the JWTBearerBacker that I built off of.

Lets start by creating a skeleton class:

public class JwtBearerBacker
{
    public JwtBearerOptions Options { get; private set; }

    public JwtBearerBacker(JwtBearerOptions options)
    {
        this.Options = options;
    }

    public ClaimsPrincipal IsJwtValid(string token)
    {

    }
}

Here we have a simple class that accepts the JWTBearerOptions we added to our ServiceProvider earlier. This class will be built within our OnConnectAsync method later.
Now, I use Firebase for authentication and I ran into an issue with the original code from Christopher J.. It did not work with Google's JWT signing keys, so I had to add some code to get it to pull that information from our Firebase project.

In our IsJwtValid method, start by adding this code, and if you're using Firebase, replace 'MYPROJECTID' with your project ID. Otherwise, replace the entire URL with your link to openid-configuration. You may be able to use the code from Christopher J. directly, but it will depend on your Auth provider.

var configManager = new ConfigurationManager<OpenIdConnectConfiguration>(
    $"https://securetoken.google.com/MYPROJECTID/.well-known/openid-configuration",
    new OpenIdConnectConfigurationRetriever()
);

var openidconfig = configManager.GetConfigurationAsync().Result;

This code will initialise a ConfigurationManager that will load our openID config and keys from Firebase for us!
Next, we will recreate our TokenValidationParamaters with some additional values included(such as our signing keys):

Options.TokenValidationParameters = new TokenValidationParameters()
{
    ValidateIssuer = true,
    ValidIssuer = "https://securetoken.google.com/MYPROJECTID",
    ValidateAudience = true,
    ValidAudience = "MYPROJECTID",
    ValidateLifetime = true,

    ValidateIssuerSigningKey = true,
    IssuerSigningKeys = openidconfig.SigningKeys,
};

You may want to find a way to inject the configuration into your JWTBearerBacker class if you wish to use config for your Firebase credentials.
Next on our list is a for-loop! This one is from the original code mostly, it loops through the JWT validators and attempts to validate our token with them. If an exception is caught due to key errors, it may attempt to refresh the configuration for up-to-date keys.

Add this code after the above code in your IsJwtValid method:

List<Exception> validationFailures = null;
SecurityToken validatedToken;
foreach (var validator in Options.SecurityTokenValidators)
{
    // Ensure we can even read the token at all
    if (validator.CanReadToken(token))
    {
        try
        {
            // Try to return a ClaimsPrincipal if we can
            // Otherwise an exception is thrown, caught and we continue on.
            return validator
                .ValidateToken(token, Options.TokenValidationParameters, out validatedToken);
        }
        catch (Exception ex)
        {
            // If the keys are invalid, refresh config
            if (Options.RefreshOnIssuerKeyNotFound && Options.ConfigurationManager != null
                && ex is SecurityTokenSignatureKeyNotFoundException)
            {
                Options.ConfigurationManager.RequestRefresh();
            }

            // Add to our list of failures. This was from the OG code
            // Not sure what we need it for.
            if (validationFailures == null)
                validationFailures = new List<Exception>(1);

            validationFailures.Add(ex);
            continue;
        }
    }
}

// No user could be found
return null;

There we have it, a complete JWT validation class that'll automatically pull the JWT keys as needed!
Now, back to our websocket code..

Returning to SubscriptionAuthMiddleware

Next thing we need to do is pull our JWT config from the ServiceProvider, which we can get from our socket context,
then attempt to validate the JWT we got from the payload with our JWT class:

var opts = connection.HttpContext.RequestServices.GetRequiredService<JwtBearerOptions>();

var claims = new JwtBearerBacker(opts).IsJwtValid(token);
    if (claims == null)
        return ConnectionStatus.Reject("Unauthoized(invalid token)");

If the could not be found, that means the JWT couldn't be validated, so we reject the connection.

Last thing we need to do is grab the User ID an add it to our HttpContext so we can access it later in our Subscription handlers!

// Grab our User ID
var userId = claims.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "";

// Add it to our HttpContext
connection.HttpContext.Items["userId"] = userId;

// Accept the websocket connection
return ConnectionStatus.Accept();

Woo-hoo! We built an authorization handler for Subscriptions! Now, lets head back to Startup and add it to our GraphQl setup.
In Startup.cs, under ConfigureServices, find services.AddGraphQLServer() and add the end of all your methods(ensure you have .AddAuthorization in there),
add the following line:

.AddSocketSessionInterceptor<SubscriptionAuthMiddleware>();

This will tell HotChocolate to proxy our subscription requests through our middleware class.

Setting up a subscription

Before you can access the HttpContext in your subscription, you'll have to head back to ConfigureServices and add this line:

services.AddHttpContextAccessor();

I'll assume you know how to add your subscription class to HotChocolate and set it up.
Once you have one, you can inject the accessor into your subscription handler method and access the UserID like so:

[Subscribe]
[Topic("MyTopic")]
public async Task<MyReturnType> OnMyTopic([EventMessage] MyType e, [Service] IHttpContextAccessor hctx)
{
    var userId = hctx.HttpContext.Items["userId"] as string;
    if (userId == null)
        throw new Exception("Unauthorized");

    // ...
    return myReturnType;
}

And that's it, you can now authorize your Subscription requests!

Extra: How to add the header to URQL in Typescript

You can initialise your URQL subscription like so to inject the Authorize header(Credit to my friend Wheatley for this code):

const subscriptionClient = new SubscriptionClient("WEBSOCKETURL", {
  reconnect: true,
  connectionParams: async() => {
    const token = ...;
    return {
        Authorization: `Bearer ${token}`,
    }    
  },
})

The End!

Well that's it! For reference, here are our completed code:

SubscriptionAuthMiddleware

public class SubscriptionAuthMiddleware : ISocketSessionInterceptor 
{
    public async ValueTask OnCloseAsync(ISocketConnection connection, CancellationToken cancellationToken) { }
    public async ValueTask OnRequestAsync(ISocketConnection connection, IQueryRequestBuilder requestBuilder, CancellationToken cancellationToken) { }

    /* We don't need the above two methods, just this one */
    public async ValueTask<ConnectionStatus> OnConnectAsync(ISocketConnection connection, InitializeConnectionMessage message, CancellationToken cancellationToken) 
    {
        try 
        {
            var jwtHeader = message.Payload["Authorization"] as string;

            if (string.IsNullOrEmpty(jwtHeader) || !jwtHeader.StartsWith("Bearer "))
                return ConnectionStatus.Reject("Unauthorized");

            var token = jwtHeader.Replace("Bearer ", "");
            var opts = connection.HttpContext.RequestServices.GetRequiredService<JwtBearerOptions>();

            var claims = new JwtBearerBacker(opts).IsJwtValid(token);
                if (claims == null)
                    return ConnectionStatus.Reject("Unauthoized(invalid token)");

            // Grab our User ID
            var userId = claims.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "";

            // Add it to our HttpContext
            connection.HttpContext.Items["userId"] = userId;

            // Accept the websocket connection
            return ConnectionStatus.Accept();
        }
        catch(Exception ex)
        {
            // If we catch any exceptions, reject the connection.
            // This is probably not ideal, there is likely a way to return a message
            // but I didn't look that far into it.
            return ConnectionStatus.Reject(ex.Message);
        }
    }
}

JwtBearerBacker

public class JwtBearerBacker
{
    public JwtBearerOptions Options { get; private set; }

    public JwtBearerBacker(JwtBearerOptions options)
    {
        this.Options = options;
    }

    public ClaimsPrincipal IsJwtValid(string token)
    {
        var configManager = new ConfigurationManager<OpenIdConnectConfiguration>(
            $"https://securetoken.google.com/MYPROJECTID/.well-known/openid-configuration",
            new OpenIdConnectConfigurationRetriever()
        );

        var openidconfig = configManager.GetConfigurationAsync().Result;
        Options.TokenValidationParameters = new TokenValidationParameters()
        {
            ValidateIssuer = true,
            ValidIssuer = "https://securetoken.google.com/MYPROJECTID",
            ValidateAudience = true,
            ValidAudience = "MYPROJECTID",
            ValidateLifetime = true,

            ValidateIssuerSigningKey = true,
            IssuerSigningKeys = openidconfig.SigningKeys,
        };

        List<Exception> validationFailures = null;
        SecurityToken validatedToken;
        foreach (var validator in Options.SecurityTokenValidators)
        {
            // Ensure we can even read the token at all
            if (validator.CanReadToken(token))
            {
                try
                {
                    // Try to return a ClaimsPrincipal if we can
                    // Otherwise an exception is thrown, caught and we continue on.
                    return validator
                        .ValidateToken(token, Options.TokenValidationParameters, out validatedToken);
                }
                catch (Exception ex)
                {
                    // If the keys are invalid, refresh config
                    if (Options.RefreshOnIssuerKeyNotFound && Options.ConfigurationManager != null
                        && ex is SecurityTokenSignatureKeyNotFoundException)
                    {
                        Options.ConfigurationManager.RequestRefresh();
                    }

                    // Add to our list of failures. This was from the OG code
                    // Not sure what we need it for.
                    if (validationFailures == null)
                        validationFailures = new List<Exception>(1);

                    validationFailures.Add(ex);
                    continue;
                }
            }
        }

        // No user could be found
        return null;
    }
}

Creating a Discord bot with C#/.Net Core and DSharpPlus

Bizzycola — Mon, 22 Jul 2019 14:03:34 +0000

Introduction

Today I'll be showing you how to setup a basic Discord bot using C#, .net core and DSharpPlus. We'll be using reflection to automatically load module classes with your commands in them.

So, first off, for those who have built discord bots with C# before, you might ask why I didn't elect to use Discord.Net (the more popular discord library). Discord.Net is a great library and it has its own pros and cons in comparison.

The reason I like DSharpPlus is the interactive library allowing you to easily await input and reactions from users, as well as (and this is not really important, just something I like) the ease of sending a "Typing.." message before the actual content. This is useful when you have a command that might take a little while, because the "Typing..." indicator shows the users that your bot has received the command and is processing the result.

Note this post is also on my blog.

Creating the discord application

So, to use create a bot, we must first head over to the Discord developer portal and create an app.

Click the New Application button and give your app a name(you'll be able to set your bots nickname and avatar image later, for now just name it what you'd like and hit Create).

You'll now be presented with a page where you can edit your applications name and description. Feel free to do this, then on the left-hand menu, click the "Bot" link.

You'll now have a mostly blank page that has the option to add a bot to this application. Hit Add Bot and hit yes when it asks you to confirm. Here you can set your bots username and profile picture. Keep this page around, you'll need the Token from the bot page as well as the client ID and token from the General Information page a little later.

Okay, now, to add the bot to your discord server(you must have the Manage Server permission to add a bot), change the CLIENTIDHERE in the following url then visit it in your browser whilst logged into discord. Select your server and add the bot: https://discordapp.com/api/oauth2/authorize?client_id=CLIENTIDHERE&scope=bot&permissions=3072

Creating the Project

I'm going to assume that if you're following this tutorial you have an editor(such as VS or VS Code, etc) and have the latest stable version of .net core installed(at this time I believe it's 2.2).

Start off by CDing to the directory in which you wish to create your project and type dotnet new console. At this point, if you wish, you can ensure it works by also running dotnet restore, dotnet build and dotnet run.

Before we get to coding, we're also going to install the DSharpPlus dependancies. In this guide, I'll be showing you how to use both the CommandsNext and Interactive modules of DSharpPlus so we'll go ahead and add those as well with the following commands:

dotnet add package DSharpPlus
dotnet add package DSharpPlus.CommandsNext
dotnet add package DSharpPlus.Interactivity

Now, we're also going to add Microsoft's configuration libraries as well to ease loading a JSON config file in which we'll store our Discord connection details. Add the packages like so:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json

At this point you may also run dotnet restore again but dotnet should probably do that for you when you add the packages.

Getting to the Code

Okay, so both DSharpPlus and Discord.Net both use asynchronous code. Newer versions of C# allow you to make your main method async nowadays so this shouldn't be too much of an issue.

Lets start with Program.cs. Feel free to rename this file/the class to something else before continuing if you wish.

using System;
using System.Linq;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using DSharpPlus;
using DSharpPlus.CommandsNext;
using DSharpPlus.Interactivity;
using Microsoft.Extensions.Configuration;

internal class Program
{
    /* This is the cancellation token we'll use to end the bot if needed(used for most async stuff). */
    private CancellationTokenSource _cts { get; set; }

    /* We'll load the app config into this when we create it a little later. */
    private IConfigurationRoot _config;

    /* These are the discord library's main classes */
    private DiscordClient _discord;
    private CommandsNextModule _commands;
    private InteractivityModule _interactivity;

    /* Use the async main to create an instance of the class and await it(async main is only available in C# 7.1 onwards). */
    static async Task Main(string[] args) => await new Program().InitBot(args);

    async Task InitBot(string[] args)
    {
        try
        {
            Console.WriteLine("[info] Welcome to my bot!");
            _cts = new CancellationTokenSource(); 

            // Load the config file(we'll create this shortly)
            Console.WriteLine("[info] Loading config file..");
            _config = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())
                .AddJsonFile("config.json", optional: false, reloadOnChange: true)
                .Build();

            // Create the DSharpPlus client
            Console.WriteLine("[info] Creating discord client..");
            _discord = new DiscordClient(new DiscordConfiguration
            {
                Token = _config.GetValue<string>("discord:token"),
                TokenType = TokenType.Bot
            });

            // Create the interactivity module(I'll show you how to use this later on)
            _interactivity = _discord.UseInteractivity(new InteractivityConfiguration()
            {
                PaginationBehaviour = TimeoutBehaviour.Delete, // What to do when a pagination request times out
                PaginationTimeout = TimeSpan.FromSeconds(30), // How long to wait before timing out
                Timeout = TimeSpan.FromSeconds(30) // Default time to wait for interactive commands like waiting for a message or a reaction
            });

            // Build dependancies and then create the commands module.
            var deps = BuildDeps();
            _commands = _discord.UseCommandsNext(new CommandsNextConfiguration
            {
                StringPrefix = _config.GetValue<string>("discord:CommandPrefix"), // Load the command prefix(what comes before the command, eg "!" or "/") from our config file
                Dependencies = deps // Pass the dependancies
            });

            // TODO: Add command loading!

            RunAsync(args).Wait();
        }
        catch(Exception ex)
        {
            // This will catch any exceptions that occur during the operation/setup of your bot.

            // Feel free to replace this with what ever logging solution you'd like to use.
            // I may do a guide later on the basic logger I implemented in my most recent bot.
            Console.Error.WriteLine(ex.ToString());
        }
    }

     async Task RunAsync(string[] args)
    {
        // Connect to discord's service
        Console.WriteLine("Connecting..");
        await _discord.ConnectAsync();
        Console.WriteLine("Connected!");

        // Keep the bot running until the cancellation token requests we stop
        while (!_cts.IsCancellationRequested)
            await Task.Delay(TimeSpan.FromMinutes(1));
    }

    /* 
     DSharpPlus has dependancy injection for commands, this builds a list of dependancies. 
     We can then access these in our command modules.
    */
    private DependencyCollection BuildDeps()
        {
            using var deps = new DependencyCollectionBuilder();

            deps.AddInstance(_interactivity) // Add interactivity
                .AddInstance(_cts) // Add the cancellation token
                .AddInstance(_config) // Add our config
                .AddInstance(_discord); // Add the discord client

            return deps.Build();
        }
}

Wow, that's a lot of code! I've added comments to help you understand whats going on (If you get confused at any point in this guide, let me know in the comments and I can update it with more information if needed).

Adding the Config File

Okay, now if you ran the bot you'd find a few issues. First off, we don't have a config file yet so lets create one.

In your project directory, create a file entitled config.json.
Now, place the following code into the file and replace the values with those you found on the Discord developer portal(except for the command prefix, set that to the character you want before your commands. Perhaps "!", "$" or "/" will do):

{
  "discord": {
    "token": "BOT TOKEN HERE",
    "appId": "CLIENT ID HERE",
    "appSecret": "CLIENT SECRET HERE",
    "CommandPrefix":  "/" 
  }
}

Now, we need this config file to be copied to our output directory when we build the project. Open the .csproj file in an editor of your choice and add the following ItemGroup inside the tags:

<ItemGroup>
  <None Update="config.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

You may also set "CopyToOutputDirectory" to "Always" if you don't want it to only copy when the file is updated.

Adding Commands

Okay, now we have our config and our bot would likely launch, but now we need a way to interact with it.

Create a new directory in your project titled "Commands"(or modules).
In that directory, create a file named "IModule.cs". This is the interface our commands will extend from so we can load them via reflection code. Just create a an empty interface titled "IModule" like so:

public interface IModule {}

Now, create another file in the Commands directory and call it BasicCommands.Module.cs
In that module, add the following code:

using DSharpPlus.CommandsNext;
using DSharpPlus.CommandsNext.Attributes;
using DSharpPlus.Entities;
using DSharpPlus.Interactivity;
using System;
using System.Threading.Tasks;

/* Create our class and extend from IModule */
public class BasicCommandsModule : IModule
{
    /* Commands in DSharpPlus.CommandsNext are identified by supplying a Command attribute to a method in any class you've loaded into it. */
    /* The description is just a string supplied when you use the help command included in CommandsNext. */
    [Command("alive")]
    [Description("Simple command to test if the bot is running!")]
    public async Task Alive(CommandContext ctx)
    {
        /* Trigger the Typing... in discord */
        await ctx.TriggerTypingAsync();

        /* Send the message "I'm Alive!" to the channel the message was recieved from */
        await ctx.RespondAsync("I'm alive!");
    }
}

Now head back to Program.cs and we'll add in some fancy reflection code to load in anything that extends from our IModule interface.

In the InitBot method, add the following code just above RunAsync(args).wait();:

Console.WriteLine("[info] Loading command modules..");

var type = typeof(IModule); // Get the type of our interface
var types = AppDomain.CurrentDomain.GetAssemblies() // Get the assemblies associated with our project
    .SelectMany(s => s.GetTypes()) // Get all the types
    .Where(p => type.IsAssignableFrom(p) && !p.IsInterface); // Filter to find any type that can be assigned to an IModule

var typeList = types as Type[] ?? types.ToArray(); // Convert to an array
foreach (var t in typeList)
    _commands.RegisterCommands(t); // Loop through the list and register each command module with CommandsNext

Console.WriteLine($"[info] Loaded {typeList.Count()} modules.");

Okay, now run dotnet build and dotnet run. Your bot should come online and and if you type your command prefix and then alive you should see some output(example with /: /alive)!

Interactivity

So, as I mentioned earlier, I like the ability in DSharpPlus to wait for input from a user after a command has been executed. I'm going to show you a basic example for how to wait for a message from a user and read it.

Head back over to your BasicCommands module and add this new method:

[Command("interact")]
[Description("Simple command to test interaction!")]
public async Task Interact(CommandContext ctx)
{
    /* Trigger the Typing... in discord */
    await ctx.TriggerTypingAsync();

    /* Send the message "I'm Alive!" to the channel the message was recieved from */
    await ctx.RespondAsync("How are you today?");

    var intr = ctx.Client.GetInteractivityModule(); // Grab the interactivity module
    var reminderContent = await intr.WaitForMessageAsync(
        c => c.Author.Id == ctx.Message.Author.Id, // Make sure the response is from the same person who sent the command
        TimeSpan.FromSeconds(60) // Wait 60 seconds for a response instead of the default 30 we set earlier!
    );
    // You can also check for a specific message by doing something like
    // c => c.Content == "something"

    // Null if the user didn't respond before the timeout
    if(reminderContent == null)
    {
        await ctx.RespondAsync("Sorry, I didn't get a response!");
        return;
    }

    // Homework: have this change depending on if they say "good" or "bad", etc.
    await ctx.RespondAsync("Thank you for telling me how you are!");
}

If you want to accept arguments from commands, you can add parameters after the CommandContext(EG:

Interact(CommandContext ctx, int age, [remainder]string fullName);

[remainder] just says use take all the rest of the arguments and place them in the string).

Okay, so now if you go run the bot and type /interact it'll ask you how you are and wait a whole minute for a response!

Conclusion

So now you've got this down, feel free to check out the DSharpPlus Documentation on how to use some other features and build yourself a fancy bot!

Let me know what you thought of this. In my bots I've implemented background scheduled tasks, a logger that supports multiple outputs and a reminder command that uses those scheduled tasks to alert the user when a reminder is due.

I've also built game bots with scoring systems, games, leaderboards, etc. So, if you want a guide on how to do anything like those, feel free to let me know in the comments and I might write one up.

Hope you enjoyed, be sure to let me know what awesome bots you create! And if you have feedback on the article that'd be great too, it's my first dev.to article!