Discord.Addons.Hosting
6.1.0
dotnet add package Discord.Addons.Hosting --version 6.1.0
NuGet\Install-Package Discord.Addons.Hosting -Version 6.1.0
<PackageReference Include="Discord.Addons.Hosting" Version="6.1.0" />
paket add Discord.Addons.Hosting --version 6.1.0
#r "nuget: Discord.Addons.Hosting, 6.1.0"
// Install Discord.Addons.Hosting as a Cake Addin #addin nuget:?package=Discord.Addons.Hosting&version=6.1.0 // Install Discord.Addons.Hosting as a Cake Tool #tool nuget:?package=Discord.Addons.Hosting&version=6.1.0
Discord.Addons.Hosting
Discord.NET hosting with Microsoft.Extensions.Hosting.
This package provides extensions that will run a Discord.NET socket/sharded client as an IHostedService
, featuring:
✅ Simplified, best practice bot creation with a reduction in boilerplate.
✅ Instant wire-up of Logging and Dependency Injection support.
✅ Extensions to easily run startup & background tasks involving the Discord Client.
✅ Easy integration with other generic host consumers, such as ASP.NET Core.
.NET 6.0+ is required.
// CreateApplicationBuilder configures a lot of stuff for us automatically
// See: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host
var builder = Host.CreateApplicationBuilder(args);
// Configure Discord.NET
builder.Services.AddDiscordHost((config, _) =>
{
config.SocketConfig = new DiscordSocketConfig
{
LogLevel = LogSeverity.Verbose,
AlwaysDownloadUsers = true,
MessageCacheSize = 200,
GatewayIntents = GatewayIntents.All
};
config.Token = builder.Configuration["Token"]!;
});
// Optionally wire up the command service
builder.Services.AddCommandService((config, _) =>
{
config.DefaultRunMode = RunMode.Async;
config.CaseSensitiveCommands = false;
});
// Optionally wire up the interaction service
builder.Services.AddInteractionService((config, _) =>
{
config.LogLevel = LogSeverity.Info;
config.UseCompiledLambda = true;
});
// Add any other services here
builder.Services.AddHostedService<CommandHandler>();
builder.Services.AddHostedService<InteractionHandler>();
builder.Services.AddHostedService<BotStatusService>();
builder.Services.AddHostedService<LongRunningService>();
var host = builder.Build();
await host.RunAsync();
Getting Started
- Create a .NET 8 Worker Service using Visual Studio or via the dotnet cli (
dotnet new worker -o MyWorkerService
) - Add
Discord.Addons.Hosting
to your project. - Set your bot token via the dotnet secrets manager:
dotnet user-secrets set "token" "your-token-here"
- Add your bot prefix to
appsettings.json
- Configure your Discord client with
builder.Services.AddDiscordHost
. - Enable the
CommandService
and/or theInteractionService
withbuilder.Services.AddCommandService
andbuilder.Services.AddInteractionService
- Register the relevant InteractionHandler and/or CommandHandler
- Create and start your application using a HostBuilder as shown above and in the examples linked below.
Examples
Fully working examples are available here
Sharded Client
To use the sharded client instead of the socket client, simply replace ConfigureDiscordHost
with ConfigureDiscordShardedHost
:
.AddDiscordShardedHost((config, _) =>
{
config.SocketConfig = new DiscordSocketConfig
{
// Manually set the required shards, or leave empty for the recommended count
TotalShards = 4
};
config.Token = context.Configuration["token"];
})
Serilog
Microsoft's default logging has an unfortunate default output format, so I highly recommend using Serilog instead of the standard Microsoft logging.
Serilog should be added to the host with Serilog.Extensions.Hosting
.
See the Serilog example for usage.
Discord Client Services
This section assumes some prior knowledge of Dependency Injection within the .NET ecosystem. Take a read of this if you have no idea what any of this means.
During bot development, it's highly like you'll require the ability to execute code immediately after startup, such as setting the bot's status, reaching out to a web server, registering an event, or kicking off the continuous execution of code in the background. Given we're using the generic host and have its IHostedService
& BackgroundService
capabilities in our toolbelt, this is easily achievable in a clean and concise way.
This package ships with the DiscordClientService
and DiscordShardedClientService
base classes for the socket client and sharded client respectively. For convenience, both of them expose the Client
and Logger
. Simply inherit from the given type, implement the required constructor, place your execution requirements within ExecuteAsync
and register the service with your service collection via services.AddHostedService
.
public class CommandHandler : DiscordClientService
{
private readonly IServiceProvider _provider;
private readonly CommandService _commandService;
private readonly IConfiguration _config;
public CommandHandler(DiscordSocketClient client, ILogger<CommandHandler> logger, IServiceProvider provider, CommandService commandService, IConfiguration config) : base(client, logger)
{
_provider = provider;
_commandService = commandService;
_config = config;
}
// This'll be executed during startup.
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
Client.MessageReceived += HandleMessage;
_commandService.CommandExecuted += CommandExecutedAsync;
await _commandService.AddModulesAsync(Assembly.GetEntryAssembly(), _provider);
}
//.....
}
builder.Services.AddHostedService<CommandHandler>();
The WaitForReadyAsync
extension method is also available for both client types to await execution of your service until the client has reached a Ready state:
public class BotStatusService : DiscordClientService
{
public BotStatusService(DiscordSocketClient client, ILogger<DiscordClientService> logger) : base(client, logger)
{
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// Wait for the client to be ready before setting the status
await Client.WaitForReadyAsync(stoppingToken);
Logger.LogInformation("Client is ready!");
await Client.SetActivityAsync(new Game("Set my status!"));
}
}
Additional notes:
Services that do not require access to the Discord Client should use an implementation of BackgroundService.
Services with complex startup & shutdown activities should implement
IHostedService
directly.
Shutdown
When shutdown is requested, the host will wait a maximum of 5 seconds for services to stop before timing out.
If you're finding that this isn't enough time, you can modify the shutdown timeout via the ShutdownTimeout host setting.
IOptions
This package uses Microsoft.Extensions.Options
internally, so both the DiscordHostConfiguration
and CommandServiceConfig
can be configured within the services registration instead of within the HostBuilder
extensions if it better suits your scenario.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. 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. |
-
net6.0
- Discord.Net.Commands (>= 3.15.0)
- Discord.Net.Interactions (>= 3.15.0)
- Discord.Net.WebSocket (>= 3.15.0)
- Microsoft.Extensions.Hosting (>= 6.0.1)
-
net8.0
- Discord.Net.Commands (>= 3.15.0)
- Discord.Net.Interactions (>= 3.15.0)
- Discord.Net.WebSocket (>= 3.15.0)
- Microsoft.Extensions.Hosting (>= 8.0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Discord.Addons.Hosting:
Package | Downloads |
---|---|
Discord.Addons.ChainHandlers
Simple Discord.Net chain handler implementation |
|
FoundryBot
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated | |
---|---|---|---|
6.1.0 | 1,559 | 6/10/2024 | |
6.0.0 | 2,876 | 1/14/2024 | |
5.2.0 | 7,457 | 11/6/2022 | |
5.1.0 | 5,850 | 1/30/2022 | |
5.1.0-labs | 760 | 1/30/2022 | |
5.0.0 | 1,732 | 12/19/2021 | |
4.0.3-labs | 766 | 11/16/2021 | |
4.0.2 | 4,584 | 6/19/2021 | |
4.0.2-labs | 1,059 | 8/3/2021 | |
4.0.1 | 1,331 | 6/14/2021 | |
3.1.1 | 4,195 | 11/20/2020 | |
3.1.0 | 1,505 | 11/15/2020 | |
3.0.0 | 3,551 | 6/14/2020 | |
2.1.0 | 1,805 | 11/14/2019 | |
2.0.0 | 1,458 | 10/10/2019 | |
1.3.0 | 1,641 | 2/10/2019 | |
1.2.1 | 1,552 | 1/6/2019 | |
1.1.2 | 1,604 | 11/25/2018 | |
1.1.1 | 1,618 | 11/16/2018 | |
1.1.0 | 1,545 | 11/10/2018 | |
1.0.2 | 1,659 | 10/15/2018 | |
1.0.1 | 1,569 | 10/14/2018 |