SimpleDiscordDotNet 1.4.4

SimpleDiscordDotNet

A lightweight, dependency-free Discord bot SDK for .NET 10 that provides direct access to Discord API v10 (REST + Gateway).

Purpose

SimpleDiscordDotNet is designed for developers who want:

• Zero dependencies - BCL only, no external packages
• Performance - Memory-optimized with Span<T> and modern .NET 10 APIs for 30-50% less GC pressure
• Simplicity - Clean, approachable API with builder patterns
• Modern C# - Built for .NET 10 with C# 14 features and span-based APIs
• Production-ready - Advanced rate limiting, comprehensive error handling, and extensive API coverage

Key Features

• ✅ Slash commands, components, and modals with attribute-based handlers
• ✅ Source generator for zero-reflection command/component discovery
• ✅ Ambient context for accessing cached guilds, channels, members, roles
• ✅ Comprehensive gateway events for all entity changes
• ✅ Advanced rate limiting with bucket management and monitoring
• ✅ Full Discord API v10 support (messages, reactions, permissions, roles, channels, threads, etc.)
• ✅ Native AOT and trimming compatible
• ✅ Memory-optimized with Span<T>, Memory<T>, and zero-allocation APIs
• ✅ Horizontal sharding - 3 modes: single process, multi-shard, or distributed coordinator/worker

Quick Example

using SimpleDiscordNet;
using SimpleDiscordNet.Commands;
using SimpleDiscordNet.Primitives;

public sealed class AppCommands
{
    [SlashCommand("hello", "Say hello")]
    public async Task HelloAsync(InteractionContext ctx)
    {
        var embed = new EmbedBuilder()
            .WithTitle("Hello!")
            .WithDescription("Welcome to SimpleDiscordDotNet")
            .WithColor(0x00FF00);

        await ctx.RespondAsync(embed: embed);
    }

    [SlashCommand("userinfo", "Get user information")]
    public async Task UserInfoAsync(InteractionContext ctx)
    {
        var user = ctx.User;
        var member = ctx.Member;

        await ctx.RespondAsync($"Hello {user?.Username}! You joined this server on {member?.Joined_At}");
    }
}

var bot = DiscordBot.NewBuilder()
    .WithToken(Environment.GetEnvironmentVariable("DISCORD_TOKEN")!)
    .WithIntents(DiscordIntents.Guilds | DiscordIntents.GuildMessages)
    .Build();

await bot.StartAsync();
await Task.Delay(Timeout.Infinite);

Documentation

📖 Full documentation is available in the Wiki

• Installation - Get started with NuGet or source reference
• Getting Started - Your first bot in minutes
• Beginner's Guide - NEW! Step-by-step guide for Discord bot beginners
• Configuration - Builder patterns, DI, intents
• Commands - Slash commands, components, modals
• Working with Entities - NEW! Channels, guilds, members, messages, and roles
• Events - Gateway events and logging
• Sharding - Horizontal scaling with distributed sharding
• API Reference - Complete API documentation
• Rate Limit Monitoring - Advanced monitoring and analytics
• FAQ - Common questions and troubleshooting

Installation

Install from NuGet:

dotnet add package SimpleDiscordDotNet

Or via Package Manager:

Install-Package SimpleDiscordDotNet

Requirements

• .NET SDK 10.0 or newer
• A Discord bot token from the Discord Developer Portal
• Gateway intents configured as needed

Contributing

Issues and pull requests are welcome! Please keep the code dependency-free and aligned with the existing style.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE for details.

Ready to build your Discord bot? Head to the Wiki to get started!

Version History

v1.4.3 - Channel Permissions & Source Generator Fixes (2025-12-20)

• ✅ Channel permission management - Add, remove, deny, and modify permissions for roles and members
  • channel.AddPermissionAsync(roleId, PermissionFlags.AttachFiles)
  • role.AddChannelPermissionAsync(channel, permission)
  • member.AddChannelPermissionAsync(channel, permission)
• ✅ Source generator fixes - [CommandOption] attribute now optional for backward compatibility
• ✅ Added ulong parameter support - Commands can now use ulong parameters (Discord snowflake IDs)
• ✅ Fixed mixed static/instance class handling - Classes with both static and instance methods now generate correctly
• 🔧 Type compatibility - Fixed IReadOnlyList<InteractionOption> handling

v1.4.1 - Entity-First Architecture & Rich API (2025-12-20)

• ✅ Removed WithGuild wrappers - All entities (Channel, Member, Role, User) now have direct Guild/Guilds properties
• ✅ Rich entity methods - Entities can perform operations on themselves (channel.SendMessageAsync, member.AddRoleAsync, message.PinAsync)
• ✅ Enhanced channel management - SetTopicAsync, SetNameAsync, SetNsfwAsync, SetBitrateAsync, SetUserLimitAsync, SetSlowmodeAsync
• ✅ Message operations return entities - All SendMessageAsync/SendDMAsync methods return DiscordMessage for chaining
• ✅ Guild channel creation - CreateChannelAsync and CreateCategoryAsync directly on DiscordGuild
• ✅ DM channel caching - DM channels are now cached in EntityCache for performance
• ✅ Type consistency - Author.Id changed from string to ulong, InteractionContext.User now returns DiscordUser
• ✅ Optional parameters - RespondAsync content parameter defaults to empty string for embed-only responses
• 📖 Comprehensive documentation - New Beginners-Guide.md and Entities.md wiki pages with detailed examples

v1.4.0 - Enhanced InteractionContext & Security (2025-12-19)

• ✅ Member and Guild objects in InteractionContext - Direct access to member/guild without cache lookups
• ✅ HTTPS-only ShardCoordinator - Secure TLS communication for distributed sharding (upgraded from HTTP)
• ✅ 100% Zero Reflection - All anonymous objects replaced with strongly-typed classes for full AoT compatibility
• ✅ Enhanced type safety - MessagePayload, BulkDeleteMessagesRequest, BanMemberRequest, HttpErrorResponse
• ✅ Code quality improvements - Removed redundant type specifications and method overload warnings
• 🔒 Security hardened - TLS 1.3+ for shard coordination endpoints

v1.3.0 - Sharding Support (2025-12-19)

• ✅ Added 3-mode sharding system: single process, multi-shard, distributed
• ✅ Distributed coordinator/worker architecture with auto-discovery
• ✅ Health monitoring, load balancing, coordinator succession
• ✅ Cross-shard entity cache queries
• ✅ Shard-aware InteractionContext for commands
• ✅ Full AoT compliance with source-generated JSON serialization
• ✅ Zero reflection usage, ready for native compilation
• 📖 See SHARDING_IMPLEMENTATION.md and SHARDING_INTEGRATION_GUIDE.md