HelperLib 1.3.0

HelperLib

HelperLib is a small utility library for Discord bots built with Discord.NET. It provides convenience helpers for mentions, embeds, guild lookups, role checks, command preconditions, and basic reconnect handling.

Current version: 1.3.0

Target framework: .NET 10

Versioning

Starting with 1.3.0, this project follows semantic versioning:

• MAJOR changes for breaking public API or runtime requirements.
• MINOR changes for backward-compatible features, behavior fixes, and new helpers.
• PATCH changes for backward-compatible bug fixes, documentation, or test-only changes.

Breaking changes must be listed in the changelog below.

Changelog

1.3.0

Released: in progress

Changes:

• Updated the library target framework to .NET 10.
• Updated Discord.NET packages to 3.19.1.
• Added an xUnit test project with coverage collection.
• Added tests for mention parsing/formatting, embed send helpers, IonicHelper, ReliabilityService, RequireRoleAttribute, and GuildUsersResult.
• Improved IonicHelper testability with internal seams for reconnect timing and lookup logic. Public initialization APIs are unchanged.
• Improved ReliabilityService testability with internal injectable timing/restart/termination seams. Public constructor behavior is preserved.
• Fixed IonicHelper.HasRolesAll so it now checks that the user has every requested role.
• Fixed reconnect timeout cancellation handling so stale disconnect checks do not continue after reconnect.
• Added GetGuildUserAsync for cache-first guild user lookup with REST fallback.

Breaking changes:

• Runtime requirement changed from .NET 9 to .NET 10. Consumers must target a compatible framework.

Non-breaking public API notes:

• Bot initialization through IonicHelper did not change:

var helper = new IonicHelper(token, defaultGuildId);
await helper.RunAsync(config, logger);

• The public IonicHelper(string token, ulong? defaultGuildId = null) constructor is still available.
• The public RunAsync(DiscordSocketConfig config, Func<LogMessage, Task> logger) method is still available.
• Existing static lookup helpers such as GetGuild, GetTextChannel, GetRole, GetGuildAdmins, and role-check helpers remain available.

Behavior changes:

• HasRolesAll(user, roleIds) now means "the user has all requested role ids." Previously it could return true when all of the user's roles were inside the requested set, even if the user was missing some requested roles.

Features

• IonicHelper: Common helpers for a running DiscordSocketClient, including guild/channel/role lookups, guild user enumeration, role checks, cancellation token access, and simple reconnect handling.
• Services.ReliabilityService: Reconnect/reset strategy for DiscordSocketClient.
• Util.MentionUtils: Create and parse Discord mentions for users, channels, and roles.
• Util.Extensions: Extension helpers for sending Embed/EmbedBuilder and sending images from URLs.
• Preconditions.RequireRoleAttribute: Discord.Commands precondition attribute that restricts usage to a role id.
• Models.GuildUsersResult: Lightweight result type for guild user enumeration.

Quick Start

Add the project or compiled DLL to your bot solution.

Simple start using IonicHelper:

var token = "YOUR_BOT_TOKEN";
var defaultGuildId = 123456789012345678UL;

var helper = new IonicHelper(token, defaultGuildId);

await helper.RunAsync(
    new DiscordSocketConfig(),
    message =>
    {
        Console.WriteLine(message);
        return Task.CompletedTask;
    });

The IonicHelper static helpers expect RunAsync to have initialized the static DiscordSocketClient.

Examples

Parse a user mention:

if (MentionUtils.TryParseUser("<@!123456>", out var userId))
{
    // use userId
}

Send an embed:

await textChannel.SendEmbedAsync(
    new EmbedBuilder()
        .WithTitle("Hello")
        .Build());

Require a role on a command:

[RequireRole(123456789012345678)]
public async Task MyCommand()
{
    // command body
}

Check roles:

if (IonicHelper.HasRolesAll(guildUser, moderatorRoleId, trustedRoleId))
{
    // user has both roles
}

Fetch a guild user with REST fallback:

var user = await IonicHelper.GetGuildUserAsync(defaultGuildId, userId);

Notes

• HelperLib is a convenience layer over Discord.NET.
• IonicHelper stores a static DiscordSocketClient, so static lookup helpers require the client to be initialized.
• Reconnect handling is intentionally simple. If reset attempts fail or time out, the process can exit so an external host can restart the bot.

Testing

Run the test suite:

dotnet test HelperLib.Tests\HelperLib.Tests.csproj --no-restore -v q

Run tests with coverage:

dotnet test HelperLib.Tests\HelperLib.Tests.csproj --no-restore --collect:"XPlat Code Coverage" -v q

Contributing

Keep changes focused and add tests for behavior changes.

License

Add the project license here.