klod68/gen-signalr-hub

---

name: gen-signalr-hub description: "Use when adding real-time push communication to an ASP.NET Core application. Generates a strongly-typed SignalR hub with a client interface, group management, DI registration, and authorization attributes. Also invoke when the user mentions: SignalR hub, real-time hub, WebSocket hub, push notifications, Hub class. Domain: Code Generation, Real-Time. Level: Intermediate."

Generate a SignalR hub for ${1:Feature}.

Context

• Namespace root: ${2:MyApp}
• Hub purpose: ${3:Brief description of real-time feature}
• Auth required: ${4:yes | no}

---

Required output — generate ALL of the following:

1. Client interface

${2}.Hubs.I${1}HubClient.cs

/// <summary>
/// Defines methods the server can invoke on connected <see cref="${1}Hub"/> clients.
/// </summary>
public interface I${1}HubClient
{
    /// <summary>Notifies the client of a new event.</summary>
    Task Receive${1}Update(${1}UpdateDto update);

    /// <summary>Notifies the client that a user joined the group.</summary>
    Task UserJoined(string userId);

    /// <summary>Notifies the client that a user left the group.</summary>
    Task UserLeft(string userId);
}

2. Hub class

${2}.Hubs.${1}Hub.cs

/// <summary>
/// Real-time hub for ${3:description}.
/// </summary>
[Authorize] // Remove if ${4} is "no"
internal sealed class ${1}Hub : Hub<I${1}HubClient>
{
    private readonly ILogger<${1}Hub> _logger;

    public ${1}Hub(ILogger<${1}Hub> logger)
    {
        ArgumentNullException.ThrowIfNull(logger);
        _logger = logger;
    }

    public override async Task OnConnectedAsync()
    {
        var userId = Context.UserIdentifier
            ?? throw new InvalidOperationException("User identity not available.");

        _logger.LogDebug("User {UserId} connected to {Hub}",
            userId, nameof(${1}Hub));

        await base.OnConnectedAsync();
    }

    public override async Task OnDisconnectedAsync(Exception? exception)
    {
        var userId = Context.UserIdentifier ?? "unknown";

        _logger.LogDebug("User {UserId} disconnected from {Hub}",
            userId, nameof(${1}Hub));

        await base.OnDisconnectedAsync(exception);
    }

    /// <summary>
    /// Joins the caller to a named group for targeted broadcasting.
    /// </summary>
    public async Task JoinGroup(string groupName)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(groupName);

        await Groups.AddToGroupAsync(Context.ConnectionId, groupName);

        var userId = Context.UserIdentifier ?? "anonymous";
        await Clients.OthersInGroup(groupName).UserJoined(userId);

        _logger.LogDebug("User {UserId} joined group {Group}",
            userId, groupName);
    }

    /// <summary>
    /// Removes the caller from a named group.
    /// </summary>
    public async Task LeaveGroup(string groupName)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(groupName);

        var userId = Context.UserIdentifier ?? "anonymous";
        await Clients.OthersInGroup(groupName).UserLeft(userId);

        await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);

        _logger.LogDebug("User {UserId} left group {Group}",
            userId, groupName);
    }
}

3. Update DTO

${2}.Hubs.${1}UpdateDto.cs

/// <summary>
/// Data sent to clients when a ${1} update occurs.
/// </summary>
public sealed record ${1}UpdateDto
{
    public required string Id { get; init; }
    public required string Message { get; init; }
    public required DateTime OccurredAtUtc { get; init; }
}

4. DI registration and endpoint mapping

${2}.Extensions.${1}HubExtensions.cs

/// <summary>
/// Registers and maps the <see cref="${1}Hub"/>.
/// </summary>
public static class ${1}HubExtensions
{
    public static IServiceCollection Add${1}Hub(this IServiceCollection services)
    {
        ArgumentNullException.ThrowIfNull(services);
        services.AddSignalR();
        return services;
    }

    public static IEndpointRouteBuilder Map${1}Hub(this IEndpointRouteBuilder endpoints)
    {
        ArgumentNullException.ThrowIfNull(endpoints);
        endpoints.MapHub<${1}Hub>("/hubs/${1:kebab}");
        return endpoints;
    }
}

5. Sending from outside the hub (example service)

// Inject IHubContext<${1}Hub, I${1}HubClient> in any service:
internal sealed class ${1}NotificationService
{
    private readonly IHubContext<${1}Hub, I${1}HubClient> _hubContext;

    public ${1}NotificationService(IHubContext<${1}Hub, I${1}HubClient> hubContext)
    {
        ArgumentNullException.ThrowIfNull(hubContext);
        _hubContext = hubContext;
    }

    public async Task NotifyGroupAsync(string groupName, ${1}UpdateDto update, CancellationToken ct)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(groupName);
        ArgumentNullException.ThrowIfNull(update);

        await _hubContext.Clients.Group(groupName).Receive${1}Update(update);
    }
}

---

Rules

• Hub class is internal sealed inheriting Hub<TClient> — always strongly-typed
• Client interface is public (may live in shared contracts project)
• Hub methods validate all parameters with guard clauses
• Access user identity via Context.UserIdentifier — never parse tokens
• Use IHubContext<THub, TClient> to send from outside the hub — never store hub references
• Group names derive from business identifiers — never connection IDs
• Authorization is explicit: [Authorize] on the hub class or individual methods

---

Constraints

• Follow all rules in the workspace root instruction file and the signalr rule file
• No business logic in hub methods — delegate to Application layer services
• No static connection tracking — use groups or distributed cache