repository·main·Indexed 40 days ago
https://github.com/aiko-it-systems/discatsharpA C# library for .NET designed for building Discord applications, providing high-level abstractions to interact with the Discord API. It features a modular ecosystem including packages for application commands, voice and audio (Lavalink), .NET Generic Host integration, and ASP.NET Core ingress.
DisCatSharp is modularized into several specialized packages. Depending on your requirements (e.g., hosting, voice, or command handling), you should include the relevant package in your project.
The following major updates are planned for future versions:
DisCatSharp.VoiceNext designed for better performance, stability, and the ability to receive incoming audio.When navigating the DisCatSharp repository to find specific functionality, use the following mapping to identify the correct project or directory:
| Area | Typical location |
|---|---|
| Core clients, entities, REST, Gateway | DisCatSharp/ |
| Slash/context commands | DisCatSharp.ApplicationCommands/ |
| Prefix commands | DisCatSharp.CommandsNext/ |
| Shared primitives | DisCatSharp.Common/ |
| Configuration package | DisCatSharp.Configuration/ |
| Experimental APIs | DisCatSharp.Experimental/ |
| Hosting and DI | DisCatSharp.Hosting*/ |
| Interaction helpers | DisCatSharp.Interactivity/ |
| Lavalink | DisCatSharp.Lavalink/ |
| Voice and native packaging | DisCatSharp.Voice*/ |
| Shared targets and versions | DisCatSharp.Targets/ |
| Analyzers and repository tools | DisCatSharp.Tools/ |
| Tests | DisCatSharp.Tests/ and tool-specific test projects |
| DocFX source and template | DisCatSharp.Docs/ |
| Workflows and repository automation | .github/ |
Note: Always use repository search to verify if a path is current before assuming its location.
DisCatSharp provides three main types of templates to scaffold your application:
In standard mode, Lavalink handles both audio decoding and Discord voice transport (via the Koe library). This means the bot cannot receive voice while playing, and the DisCatSharp.Voice stack is bypassed.
Bridge Mode splits these responsibilities:
Use Bridge Mode if your bot needs to perform voice tasks (like receiving audio or mixing) while playing music, or if you want to leverage the full DisCatSharp.Voice transport stack.
Sharding is the process of splitting the event workload of a DiscordClient into multiple connections, called shards. Each shard handles a specific set of Discord servers (guilds) and only receives events from those servers.
Key behaviors:
When to shard:
DisCatSharp's OAuth2 implementation is split into two distinct layers to separate the Discord protocol logic from HTTP hosting concerns:
DiscordOAuth2Client (Protocol Client): Handles the core OAuth2 protocol logic. Use this for generating authorization URLs, validating state, exchanging codes, refreshing/revoking tokens, and calling Discord's OAuth-protected endpoints.DisCatSharp.Hosting.AspNetCore (HTTP Ingress & Hosting): Handles the web-facing infrastructure. Use this to receive OAuth callbacks, Discord interactions, or signed Discord webhook events within an ASP.NET Core environment.Note: DiscordOAuth2Client is not deprecated. The deprecated component is DisCatSharp.Extensions.OAuth2Web.
Starting with DisCatSharp 10.7.0, the DiscordConfiguration object uses a nested hierarchical layout. Instead of a flat list of properties, settings are grouped into specialized sub-objects (e.g., Api, Gateway, Rest, Cache, Logging). This structure helps organize the 40+ available settings into logical domains.
DiscordConfiguration
├── Token / TokenType / Intents / ServiceProvider / Proxy
├── Api → API protocol settings
├── Gateway → Connection, sharding, compression
│ └── Advanced → Dispatch mode, reconnect tuning
├── Rest → HTTP timeout, rate-limit strategy
│ └── Advanced → Queue limits, retries, circuit breaker
├── Cache → Message/presence cache, auto-fetch
├── Logging → Log level, timestamp format, logger factory
├── Diagnostics → Payload events, update checks
│ └── UpdateChecks → Version check mode and options
└── Telemetry → Sentry error reportingWhen your command structure uses nested SlashCommandGroup attributes, your translation JSON must be an array of [Command Group Objects]. Each object maps a name to its translations and contains a commands array for the subcommands within that group.
Key fields:
name: The internal name of the group.type: Must be 1 for slash command groups.name_translations: An object mapping locale codes (e.g., en-US, de) to the translated name.description_translations: An object mapping locale codes to the translated description.commands: An array of command objects belonging to this group.[
{
"name": "my_command",
"description": "This is description of the command group.",
"type": 1,
"name_translations": {
"en-US": "my_command",
"de": "mein_befehl"
},
"description_translations": {
"en-US": "This is description of the command group.",
"de": "Das ist die description der Befehl Gruppe."
},
"groups": [],
"commands": [
{
"name": "first",
"description": "First",
"name_translations": {
"en-US": "first",
"de": "erste"
},
"description_translations": {
"en-US": "This is description of the command.",
"de": "Das ist die Beschreibung des Befehls."
}
}
]
}
]