DiscSharp 0.1.4

DiscSharp

DiscSharp is a production-oriented Discord SDK for .NET 10 applications. It provides typed Discord REST clients, Gateway lifecycle orchestration, interaction modules, Components V2 payload support, rate-limit coordination seams, and voice/DAVE infrastructure groundwork.

Install the package:

dotnet add package DiscSharp

Included surface

DiscSharp is an SDK. It does not ship consumer feature packs such as music players, raid planners, moderation dashboards, or bot studio UI projects. Build those in your bot host or in separate packages on top of DiscSharp.

Architecture boundary

The package is organized as a Clean Architecture SDK. DiscSharp.Domain and DiscSharp.Application are the inner rings. DiscSharp.Infrastructure is the single outer adapter assembly and package root. Its folders keep REST, Gateway, Voice, composition, and facade code organized while the public namespaces remain usage-oriented (DiscSharp.Rest, DiscSharp.Gateway, DiscSharp.Voice). The NuGet package ID is DiscSharp; there is no extra facade assembly, and the layer assemblies are bundled instead of emitted as DiscSharp.* package dependencies.

Production posture

DiscSharp is designed for real bot hosts:

• Explicit configuration and dependency injection.
• Token-bearing values stay in secrets, environment variables, or a vault.
• REST calls go through a shared executor instead of endpoint-specific retry logic.
• Rate-limit state is coordinated through Discord route and bucket transitions.
• Interaction PING/PONG behavior is handled explicitly.
• Gateway handlers are typed, ordered, isolated, and observable through orchestration results.
• Gateway session-start coordination supports single-process and file-backed distributed host shapes.
• The package is validated by unzipping the built .nupkg and .snupkg, checking assemblies, README metadata, dependency shape, symbols, and native assets.

Voice includes gateway v8 handshake primitives, UDP discovery, RTP packetization, transport encryption modes, reconnect policy, and DAVE/native seams. Use the opt-in live smoke scripts against a controlled guild before production voice deployment.

Target platform

• .NET 10
• C# 14
• Discord API v10
• Autofac composition
• Nullable enabled
• XML documentation generated
• Native DAVE assets included for:
  • runtimes/win-x64/native/libdave.dll
  • runtimes/linux-x64/native/libdave.so

Minimal host

using Autofac;
using DiscSharp;
using DiscSharp.Rest.Endpoints;
using DiscSharp.Domain.Primitives;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .Build();

using var discSharp = new DiscSharpClientBuilder(configuration)
    .ConfigureDiscordApi(options =>
    {
        options.ApiVersion = 10;
        options.UserAgent = "DiscordBot (https://github.com/your-org/your-bot, 1.0.0)";
        options.EnableRateLimitCoordination = true;
    })
    .ConfigureDiscordBotApi(options =>
    {
        options.BotToken = configuration["DISCORD_BOT_TOKEN"] ?? string.Empty;
    })
    .ConfigureContainer(RegisterApplicationServices)
    .Build();

var users = discSharp.Resolve<IDiscordUsersRestClient>();
var currentUser = await users.GetCurrentUserAsync();
Console.WriteLine($"Connected as {currentUser.Username}");

var channels = discSharp.Resolve<IDiscordChannelsRestClient>();
var channelId = (DiscordSnowflake)(configuration["DISCORD_CHANNEL_ID"]
    ?? throw new InvalidOperationException("Missing channel id."));

await channels.CreateMessageAsync(
    channelId,
    new DiscordCreateMessageRequest
    {
        Content = "DiscSharp is online."
    });

static void RegisterApplicationServices(ContainerBuilder builder)
{
    // Register interaction modules, Gateway handlers, persistence, telemetry, and app services here.
}

Configuration shape

{
  "DiscSharp": {
    "Rest": {
      "Api": {
        "ApiVersion": 10,
        "UserAgent": "DiscordBot (https://github.com/your-org/your-bot, 1.0.0)",
        "EnableRateLimitCoordination": true,
        "MaxRateLimitRetryAttempts": 2,
        "MaxTransientRetryAttempts": 2
      },
      "Bot": {
        "BotToken": "load-from-user-secrets-environment-or-vault"
      }
    },
    "Gateway": {
      "Socket": {
        "BotToken": "load-from-user-secrets-environment-or-vault",
        "Intents": 513,
        "ShardId": 0,
        "ShardCount": 1,
        "EnableDistributedSessionStartCoordination": true,
        "SessionStartStateDirectory": "./data/gateway-session-start"
      },
      "DispatchOrchestration": {
        "ExecutionMode": "Sequential",
        "LogUnhandledDispatches": true
      }
    }
  }
}

REST example: send a message

using DiscSharp.Rest.Endpoints;
using DiscSharp.Domain.Primitives;

var channels = discSharp.Resolve<IDiscordChannelsRestClient>();
var channelId = (DiscordSnowflake)configuration["DISCORD_CHANNEL_ID"]!;

await channels.CreateMessageAsync(
    channelId,
    new DiscordCreateMessageRequest
    {
        Content = "Deployment complete."
    });

Interaction module example

using DiscSharp.Application.Interactions;

public sealed class PingInteractionModule : IDiscordInteractionModule
{
    public string ModuleName => "ping";
    public int Order => 0;

    public bool CanHandle(DiscordInteractionEnvelope interaction) =>
        interaction.Kind == DiscordInteractionKind.ApplicationCommand &&
        string.Equals(interaction.CommandName, "ping", StringComparison.OrdinalIgnoreCase);

    public ValueTask<InteractionModuleResult> HandleAsync(
        DiscordInteractionEnvelope interaction,
        CancellationToken cancellationToken)
    {
        return ValueTask.FromResult(
            InteractionModuleResult.HandledWith(
                InteractionResponsePlan.Message("Pong.", ephemeral: true)));
    }
}

Autofac registration:

builder.RegisterType<PingInteractionModule>()
    .As<IDiscordInteractionModule>()
    .SingleInstance();

Gateway handler example

using DiscSharp.Gateway.Dispatch.Orchestration;
using DiscSharp.Gateway.Sockets;

public sealed class ReadyHandler : DiscordGatewayDispatchHandler<DiscordGatewayReadyEvent>
{
    public override string EventName => "READY";

    protected override ValueTask<GatewayHandlerExecutionResult> HandleAsync(
        DiscordGatewayReadyEvent payload,
        GatewayDispatchEnvelope envelope,
        CancellationToken cancellationToken)
    {
        Console.WriteLine($"Gateway READY session {payload.SessionId}");
        return ValueTask.FromResult(GatewayHandlerExecutionResult.Succeeded());
    }
}

Autofac registration:

builder.RegisterType<ReadyHandler>()
    .As<IDiscordGatewayDispatchHandler>()
    .SingleInstance();

Operating guidance

For production hosts:

• Use a real Discord-compliant User-Agent.
• Load tokens from user secrets, environment variables, or a vault.
• Keep bot behavior in interaction modules and Gateway handlers.
• Keep REST usage behind typed clients or your own application services.
• Provide a real distributed IDiscordRestRateLimitStateStore if you horizontally scale REST callers.
• Use file-backed Gateway session-start coordination only when it matches your deployment topology; otherwise provide your own backing store.
• Run unit tests, package-layout validation, clean package install smoke, and live Discord smoke tests before publishing or deploying.
• Never log token-bearing callback URLs, interaction tokens, webhook tokens, bot tokens, or raw Authorization headers.

Repository documentation covers architecture, API guides, examples, validation, package layout, Discord smoke testing, and distributed Gateway session-start coordination.

Project repository: https://github.com/haxxornulled/DiscSharp

Voice and DAVE opt-in

Voice is intentionally explicit. A consuming host should build voice connection options from Discord Voice State Update and Voice Server Update data, then opt into DAVE only when the deployment has validated native assets and protocol behavior against a controlled guild.

using DiscSharp.Voice;

var voice = new DiscordVoiceConnectionOptions
{
    GuildId = guildId.ToString(),
    ChannelId = channelId.ToString(),
    SessionId = voiceSessionId,
    UserId = botUserId.ToString(),
    Token = voiceToken,
    VoiceEndpoint = new Uri($"wss://{voiceEndpoint}"),
    VoiceGatewayVersion = 8,
    MaxDaveProtocolVersion = 1,
    RequireDaveProtocol = true
};

var voiceGatewayUri = voice.BuildVoiceGatewayUri();

DAVE native assets ship in the package for win-x64 and linux-x64. Run the opt-in voice smoke script before treating a host/runtime pair as production-ready.