Nefarius.DSharpPlus.Interactivity.Extensions.Hosting 5.3.0

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Nefarius.DSharpPlus.Interactivity.Extensions.Hosting --version 5.3.0                
NuGet\Install-Package Nefarius.DSharpPlus.Interactivity.Extensions.Hosting -Version 5.3.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Nefarius.DSharpPlus.Interactivity.Extensions.Hosting" Version="5.3.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Nefarius.DSharpPlus.Interactivity.Extensions.Hosting --version 5.3.0                
#r "nuget: Nefarius.DSharpPlus.Interactivity.Extensions.Hosting, 5.3.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Nefarius.DSharpPlus.Interactivity.Extensions.Hosting as a Cake Addin
#addin nuget:?package=Nefarius.DSharpPlus.Interactivity.Extensions.Hosting&version=5.3.0

// Install Nefarius.DSharpPlus.Interactivity.Extensions.Hosting as a Cake Tool
#tool nuget:?package=Nefarius.DSharpPlus.Interactivity.Extensions.Hosting&version=5.3.0                

<img src="assets/NSS-128x128.png" align="right" />

DSharpPlus hosting extensions

An extension for DSharpPlus to make hosting a Discord bot in .NET Core Worker Services easier.

.NET GitHub Nuget Discord

About


This is not an official DSharpPlus extension, use it at your own risk!


This set of libraries abstracts away a lot of the plumbing code required to get DSharpPlus up and running in a .NET Core Worker Service (or simply a plain old Console Application) and provides Dependency-Injection-friendly integration.

It also offers a new feature/concept on top: event subscribers! Changes happening in the Discord universe are represented in DSharpPlus by a (rather large) number of events that can be subscribed to. The library offers an interface for every event of the Discord Client your "event subscriber" class can implement. These interface methods will be called when the corresponding event occurs. But there's a convenience extra: within the callback method you will have access to scoped services, like database contexts!

And if that wasn't enough, here's another one: intents will be automatically registered if you're using an interface/event that requires them! Yay automation!

Branches

  • master - follows the stable releases of DSharpPlus.
  • develop - follows the pre-releases ("nightlies") of DSharpPlus.

To-Do

  • More documentation 😇
  • Support the sharded client

Package overview

I try my best to publish stable releases with every major DSharpPlus update. I try to stick to their Major.Minor version prefixes, but the Build is out of sync as it increments every time I trigger a CI build. Overall the library is considered stable and production-ready. Even in pre-releases I try to not introduce critical bugs or API-breaking changes unless documented otherwise.

Nefarius.DSharpPlus.Extensions.Hosting

NuGet

The core library for DSharpPlus, required to set up a Discord client as a hosted service.

Nefarius.DSharpPlus.CommandsNext.Extensions.Hosting

NuGet

Optional. Adds support for DSharpPlus.CommandsNext extension.

Nefarius.DSharpPlus.Interactivity.Extensions.Hosting

NuGet

Optional. Adds support for DSharpPlus.Interactivity extension.

Nefarius.DSharpPlus.VoiceNext.Extensions.Hosting

NuGet

Optional. Adds support for DSharpPlus.VoiceNext extension.

Nefarius.DSharpPlus.SlashCommands.Extensions.Hosting

NuGet

Optional. Adds support for DSharpPlus.SlashCommands extension.

Documentation

If you're already familiar with .NET Core Workers or ASP.NET Core you'll have your bot up and running in seconds 👌

You can also take a look at the reference example of this repository.

Setup

Create a new .NET Core Worker project either via Visual Studio templates or using the command dotnet new worker in a fresh directory.

The current version of the library depends on the DSharpPlus nightly version. If you're using the stable nuget version, update to the nightly version.

Add the core hosting package (and optional extensions, if you need them) via NuGet package manager.

Implementation

Most of the heavy lifting is done in the ConfigureServices method, so we will focus on that. To get a bare basic Discord bot running, all you need to do is register the client service and the hosted background service:

//
// Adds DiscordClient singleton service you can use everywhere
// 
services.AddDiscord(options =>
{
 //
 // Minimum required configuration
 // 
 options.Token = "recommended to read bot token from configuration file";
});

//
// Automatically host service and connect to gateway on boot
// 
services.AddDiscordHostedService();

That's pretty much it! When you launch your worker with a valid bot token you should see your bot come online in an instant, congratulations! ✨

Handling Discord Events

Now to the actual convenience feature of this library! Creating one (or more) class(es) that handle events, like when a guild came online or a message got created. Let's wire one up that gets general guild and member change events:

// this does the same as calling
//   services.AddDiscordGuildAvailableEventSubscriber<BotModuleForGuildAndMemberEvents>();
[DiscordGuildAvailableEventSubscriber]
// this does the same as calling
//   services.AddDiscordGuildMemberAddedEventSubscriber<BotModuleForGuildAndMemberEvents>();
[DiscordGuildMemberAddedEventSubscriber]
internal class BotModuleForGuildAndMemberEvents :
    // you can implement one or many interfaces for event handlers in one class 
    // or split it however you like. Your choice!
    IDiscordGuildAvailableEventSubscriber,
    IDiscordGuildMemberAddedEventSubscriber
{
    private readonly ILogger<BotModuleForGuildAndMemberEvents> _logger;

    /// <summary>
    ///     Optional constructor for Dependency Injection.
    ///     Parameters get populated automatically with your services.
    /// </summary>
    /// <param name="logger">The logger service instance.</param>
    /// <param name="tracer">The tracer service instance.</param>
    public BotModuleForGuildAndMemberEvents(
        ILogger<BotModuleForGuildAndMemberEvents> logger
    )
    {
        //
        // Do whatever you like with these. It's recommended to not do heavy tasks in 
        // constructors, just store your service references for later use!
        // 
        // You can inject scoped services like database contexts as well!
        // 
        _logger = logger;
    }

    public Task DiscordOnGuildAvailable(DiscordClient sender, GuildCreateEventArgs args)
    {
        //
        // To see some action, output the guild name
        // 
        Console.WriteLine(args.Guild.Name);

        //
        // Usage of injected logger service
        // 
        _logger.LogInformation("Guild {Guild} came online", args.Guild);

        //
        // Return successful execution
        // 
        return Task.CompletedTask;
    }

    public Task DiscordOnGuildMemberAdded(DiscordClient sender, GuildMemberAddEventArgs args)
    {
        //
        // Fired when a new member has joined, exciting!
        // 
        _logger.LogInformation("New member {Member} joined!", args.Member);

        //
        // Return successful execution
        // 
        return Task.CompletedTask;
    }
}

Now let's dissect what is happening here. The class gets decorated by the attributes DiscordGuildAvailableEventSubscriber and DiscordGuildMemberAddedEventSubscriber (hint: you can use only one attribute for the event group you're interested in, you can use many more on the same class, doesn't matter, your choice) which causes it to get automatically registered as subscribers for these events.

An alternative approach to registration is manually calling the extension methods, like

services.AddDiscordGuildAvailableEventSubscriber<BotModuleForGuildAndMemberEvents>();
services.AddDiscordGuildMemberAddedEventSubscriber<BotModuleForGuildAndMemberEvents>();

from within ConfigureServices. Using the attributes instead ensures you don't forget to register your subscribers while coding vigorously!

Implementing the interfaces IDiscordGuildAvailableEventSubscriber and IDiscordGuildMemberEventsSubscriber ensures your subscriber class is actually callable by the Discord Client Service. You must complete every event callback you're not interested in with return Task.CompletedTask; as demonstrated or it will result in errors. In the example above we are only interested in DiscordOnGuildAvailable and print the guild name to the console. I'm sure you can think of more exciting tasks!

And last but not least; your subscriber classes are fully dependency injection aware! You can access services via classic constructor injection:

private readonly ILogger<BotModuleForGuildAndMemberEvents> _logger;

public BotModuleForGuildAndMemberEvents(
 ILogger<BotModuleForGuildAndMemberEvents> logger
)
{
 _logger = logger;
}

You can even inject scoped services, the subscriber objects get invoked in their own scope by default. This allows for easy access for e.g. database contexts within each subscriber. Neat!

Intents

The library tries to assume the required intents from the event subscribers used, but not all intents can be derived with that method. For example, if you need to read user message contents within a slash command module, you need to manually set the required intents on Discord initialization like so:

serviceCollection.AddDiscord(discordConfiguration =>
{
    discordConfiguration.Intents = DiscordIntents.GuildMessages |
                                   DiscordIntents.DirectMessages |
                                   DiscordIntents.MessageContents;
});

Otherwise your code "might" work but you'll experience weird side effects like empty message contents. If you do assign intents like demonstrated, they will be merged with your subscribers intents automatically, so you do not need to specify them manually again!

Accessing DiscordClient

Inject IDiscordClientService, there you can access the Client property.

Registering Slash Commands

Let's assume you have one or more slash command classes like the following:

[SlashCommandGroup("apply", "Apply for server membership.")]
[SuppressMessage("ReSharper", "UnusedMember.Global")]
[SuppressMessage("ReSharper", "ClassNeverInstantiated.Global")]
public sealed class OnBoardingApplicationCommands : ApplicationCommandModule
{
    [SlashRequirePermissions(Permissions.SendMessages)]
    [SlashCommand("member", "Apply for regular membership.")]
    public async Task Member(
        InteractionContext ctx
    )
    {
        ...

You'd simply register it like so:

    serviceCollection.AddDiscordSlashCommands(extension: extension =>
    {
        extension.RegisterCommands<OnBoardingApplicationCommands>();
    });
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.3.1-nightly.2 76 5/18/2024
5.3.1-nightly.1 58 2/26/2024
5.3.0 137 2/15/2024
5.2.0 96 2/1/2024
5.1.0 228 12/1/2023
4.4.800 160 11/18/2023
4.4.718 315 7/5/2023
4.4.710 165 6/19/2023
4.4.693 194 5/29/2023
4.4.674 202 4/25/2023
2.2.653-pre 152 3/27/2023
2.2.633-pre 289 3/21/2023
2.2.612-pre 140 3/21/2023
2.2.590-pre 129 3/16/2023
2.2.538-pre 136 3/9/2023
2.1.519 403 1/2/2023
2.1.517 316 1/1/2023
2.1.499 303 12/19/2022
2.1.496 362 12/18/2022
2.1.494 300 12/15/2022
2.1.458 325 11/28/2022
2.1.447 331 11/26/2022
2.1.412 356 11/3/2022
2.1.378 359 10/6/2022
2.1.292 441 8/1/2022
2.1.279 424 8/1/2022
2.1.261 409 7/22/2022
2.1.200 424 6/14/2022
2.1.184 433 6/7/2022
2.1.168 418 5/23/2022
2.1.158 426 5/23/2022
2.1.114 444 5/15/2022
2.0.99-beta 175 4/13/2022
2.0.97-beta 176 4/2/2022
2.0.94-beta 173 3/9/2022
2.0.92-beta 177 2/21/2022
1.0.67-beta 173 2/19/2022
1.0.63-beta 179 1/31/2022
1.0.58-beta 180 1/11/2022
1.0.56-beta 192 11/27/2021
1.0.55-beta 168 11/27/2021
1.0.49-beta 223 10/16/2021
1.0.46-beta 259 9/8/2021
1.0.44-beta 185 8/31/2021
1.0.40-beta 182 8/30/2021
1.0.38-beta 194 8/30/2021
1.0.36-beta 210 8/29/2021