Claude Skill

dotnet-signalr

Implement or review SignalR hubs, streaming, reconnection, transport, and real-time delivery patterns in ASP.NET Core applications.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download postpartum-genushyacinthus29-dotnet-skills-skills_dotnet-signalr-bfa4ebd.zip · 15 KB

Install

skills CLI npx skills add https://github.com/Postpartum-genushyacinthus29/dotnet-skills/tree/main/skills/dotnet-signalr
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install postpartum-genushyacinthus29-dotnet-skills@llmmart
Git git clone https://github.com/Postpartum-genushyacinthus29/dotnet-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole postpartum-genushyacinthus29/dotnet-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

SignalR

Trigger On

  • building chat, notification, collaboration, or live-update features
  • debugging hub lifetime, connection state, or transport issues
  • deciding whether SignalR or another transport better fits the scenario
  • implementing real-time broadcasting to groups of connected clients
  • scaling SignalR across multiple servers

Documentation

References

  • patterns.md - Detailed hub patterns, streaming, groups, presence, and advanced messaging techniques
  • anti-patterns.md - Common SignalR mistakes and how to avoid them

Workflow

  1. Use SignalR for broadcast-style or connection-oriented real-time features; do not force gRPC into hub-style fan-out scenarios.
  2. Model hub contracts intentionally and keep hub methods thin, delegating durable work elsewhere.
  3. Plan for reconnection, backpressure, auth, and fan-out costs instead of treating real-time messaging as stateless request/response.
  4. Use groups, presence, and connection metadata deliberately so scale-out behavior is understandable.
  5. If Native AOT or trimming is in play, validate supported protocols and serialization choices explicitly.
  6. Test connection behavior and failure modes, not just happy-path message delivery.

Hub Patterns

Strongly-Typed Hub (Recommended)

// Define the client interface
public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
    Task UserJoined(string user);
    Task UserLeft(string user);
}

// Implement the strongly-typed hub
public class ChatHub : Hub<IChatClient>
{
    public async Task SendMessage(string user, string message)
    {
        // Compiler checks client method calls
        await Clients.All.ReceiveMessage(user, message);
    }

    public override async Task OnConnectedAsync()
    {
        await Clients.Others.UserJoined(Context.User?.Identity?.Name ?? "Anonymous");
        await base.OnConnectedAsync();
    }

    public override async Task OnDisconnectedAsync(Exception? exception)
    {
        await Clients.Others.UserLeft(Context.User?.Identity?.Name ?? "Anonymous");
        await base.OnDisconnectedAsync(exception);
    }
}

Using Groups for Targeted Messaging

public class NotificationHub : Hub<INotificationClient>
{
    public async Task JoinGroup(string groupName)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, groupName);
        await Clients.Group(groupName).UserJoined(Context.User?.Identity?.Name);
    }

    public async Task LeaveGroup(string groupName)
    {
        await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);
    }

    public async Task SendToGroup(string groupName, string message)
    {
        await Clients.Group(groupName).ReceiveNotification(message);
    }
}

Hub Method with Custom Object Parameters (API Versioning)

// Use custom objects to avoid breaking changes
public class SendMessageRequest
{
    public string Message { get; set; } = string.Empty;
    public string? Recipient { get; set; }  // Added later without breaking clients
    public int? Priority { get; set; }       // Added later without breaking clients
}

public class ChatHub : Hub<IChatClient>
{
    public async Task SendMessage(SendMessageRequest request)
    {
        // Handle both old and new clients
        if (request.Recipient != null)
        {
            await Clients.User(request.Recipient).ReceiveMessage(request.Message);
        }
        else
        {
            await Clients.All.ReceiveMessage(request.Message);
        }
    }
}

Client Patterns

JavaScript Client with Automatic Reconnection

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chatHub")
    .withAutomaticReconnect([0, 2000, 5000, 10000, 30000]) // Retry delays
    .configureLogging(signalR.LogLevel.Information)
    .build();

// Handle reconnection events
connection.onreconnecting(error => {
    console.log("Reconnecting...", error);
    updateUIForReconnecting();
});

connection.onreconnected(connectionId => {
    console.log("Reconnected with ID:", connectionId);
    // Rejoin groups - reconnection does not restore group membership
    rejoinGroups();
    updateUIForConnected();
});

connection.onclose(error => {
    console.log("Connection closed", error);
    updateUIForDisconnected();
});

async function start() {
    try {
        await connection.start();
        console.log("SignalR Connected");
    } catch (err) {
        console.log(err);
        setTimeout(start, 5000);
    }
}

start();

.NET Client with Reconnection

var connection = new HubConnectionBuilder()
    .WithUrl("https://localhost:5001/chatHub", options =>
    {
        options.AccessTokenProvider = () => Task.FromResult(GetAccessToken());
    })
    .WithAutomaticReconnect()
    .Build();

connection.Reconnecting += error =>
{
    _logger.LogWarning("Connection lost. Reconnecting: {Error}", error?.Message);
    return Task.CompletedTask;
};

connection.Reconnected += connectionId =>
{
    _logger.LogInformation("Reconnected with ID: {ConnectionId}", connectionId);
    // Rejoin groups after reconnection
    return RejoinGroupsAsync();
};

connection.Closed += async error =>
{
    _logger.LogError("Connection closed: {Error}", error?.Message);
    await Task.Delay(Random.Shared.Next(0, 5) * 1000);
    await connection.StartAsync();
};

await connection.StartAsync();

Server Configuration

Hub Registration with Authentication

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR(options =>
{
    options.EnableDetailedErrors = builder.Environment.IsDevelopment();
    options.MaximumReceiveMessageSize = 64 * 1024; // 64 KB
    options.StreamBufferCapacity = 10;
    options.KeepAliveInterval = TimeSpan.FromSeconds(15);
    options.ClientTimeoutInterval = TimeSpan.FromSeconds(30);
})
.AddMessagePackProtocol(); // Binary protocol for performance

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = context =>
            {
                // Read token from query string for WebSocket connections
                var accessToken = context.Request.Query["access_token"];
                var path = context.HttpContext.Request.Path;
                if (!string.IsNullOrEmpty(accessToken) && path.StartsWithSegments("/hubs"))
                {
                    context.Token = accessToken;
                }
                return Task.CompletedTask;
            }
        };
    });

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapHub<ChatHub>("/hubs/chat");

Sending Messages from Outside a Hub

public class NotificationService
{
    private readonly IHubContext<NotificationHub, INotificationClient> _hubContext;

    public NotificationService(IHubContext<NotificationHub, INotificationClient> hubContext)
    {
        _hubContext = hubContext;
    }

    public async Task NotifyAllAsync(string message)
    {
        await _hubContext.Clients.All.ReceiveNotification(message);
    }

    public async Task NotifyUserAsync(string userId, string message)
    {
        await _hubContext.Clients.User(userId).ReceiveNotification(message);
    }

    public async Task NotifyGroupAsync(string groupName, string message)
    {
        await _hubContext.Clients.Group(groupName).ReceiveNotification(message);
    }
}

Scaling with Redis Backplane

builder.Services.AddSignalR()
    .AddStackExchangeRedis(connectionString, options =>
    {
        options.Configuration.ChannelPrefix = RedisChannel.Literal("MyApp");
    });

Anti-Patterns to Avoid

Anti-Pattern Why It's Bad Better Approach
Storing state in Hub properties Hub instances are created per method call Use IMemoryCache, database, or external store
Instantiating Hub directly Bypasses SignalR infrastructure Use IHubContext<THub> for external messaging
Not awaiting SendAsync calls Messages may not be sent before hub method completes Always await async hub calls
Adding method parameters without versioning Breaking change for existing clients Use custom object parameters
Ignoring reconnection group loss Clients lose group membership on reconnect Re-add to groups in OnConnectedAsync or client reconnect handler
Large payloads over SignalR Memory pressure, bandwidth issues Use REST/gRPC for bulk data, SignalR for notifications
Missing backplane in multi-server Messages only reach clients on same server Use Redis backplane or Azure SignalR Service
Exposing ORM entities directly May serialize sensitive data Use DTOs with explicit properties
Not validating incoming messages Security risk after initial auth Validate every hub method input

Best Practices

Connection Management

  1. Enable automatic reconnection with exponential backoff delays
  2. Handle group rejoining explicitly after reconnection (connection ID changes)
  3. Implement heartbeat monitoring on the client to detect stale connections
  4. Use sticky sessions when scaling across multiple servers (unless using Azure SignalR Service)

Performance

  1. Use MessagePack protocol for smaller message sizes and faster serialization
  2. Throttle high-frequency events like typing indicators or mouse movements
  3. Batch messages when possible instead of many small sends
  4. Set appropriate buffer sizes based on expected message throughput

Security

  1. Authenticate at connection time using JWT tokens via query string
  2. Authorize hub methods using [Authorize] attribute
  3. Validate all incoming messages even after authentication
  4. Use HTTPS for all SignalR connections

API Design

  1. Use strongly-typed hubs to catch client method name typos at compile time
  2. Use custom object parameters to enable backward-compatible API evolution
  3. Version hub names (e.g., ChatHubV2) for breaking changes
  4. Keep hub methods thin and delegate business logic to services

Observability

  1. Log connection events (connect, disconnect, reconnect)
  2. Track transport type used by each connection
  3. Monitor message delivery latency and failure rates
  4. Integrate with Application Insights or other APM tools

Deliver

  • clear hub contracts and connection behavior
  • real-time delivery that matches the product scenario
  • validation for reconnection and authorization flows
  • appropriate scale-out strategy for multi-server deployments

Validate

  • SignalR is the correct transport for the use case
  • hub methods remain orchestration-oriented
  • group and auth behavior are explicit and tested
  • reconnection and group membership are handled correctly
  • backplane is configured for multi-server scenarios
  • message validation is implemented in hub methods
Files (dotnet-skills)
  • references
    • anti-patterns.md 19.5 KB
      Loading…
    • patterns.md 20.1 KB
      Loading…
  • SKILL.md 11.7 KB
    ---
    name: dotnet-signalr
    version: "1.0.0"
    category: "Web"
    description: "Implement or review SignalR hubs, streaming, reconnection, transport, and real-time delivery patterns in ASP.NET Core applications."
    compatibility: "Requires ASP.NET Core SignalR server or client code."
    ---
    
    # SignalR
    
    ## Trigger On
    
    - building chat, notification, collaboration, or live-update features
    - debugging hub lifetime, connection state, or transport issues
    - deciding whether SignalR or another transport better fits the scenario
    - implementing real-time broadcasting to groups of connected clients
    - scaling SignalR across multiple servers
    
    ## Documentation
    
    - [ASP.NET Core SignalR Overview](https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction?view=aspnetcore-10.0)
    - [SignalR Hubs](https://learn.microsoft.com/en-us/aspnet/core/signalr/hubs?view=aspnetcore-10.0)
    - [SignalR API Design Considerations](https://learn.microsoft.com/en-us/aspnet/core/signalr/api-design?view=aspnetcore-10.0)
    - [SignalR Production Hosting and Scaling](https://learn.microsoft.com/en-us/aspnet/core/signalr/scale?view=aspnetcore-10.0)
    - [SignalR Configuration](https://learn.microsoft.com/en-us/aspnet/core/signalr/configuration?view=aspnetcore-10.0)
    
    ### References
    
    - [patterns.md](references/patterns.md) - Detailed hub patterns, streaming, groups, presence, and advanced messaging techniques
    - [anti-patterns.md](references/anti-patterns.md) - Common SignalR mistakes and how to avoid them
    
    ## Workflow
    
    1. Use SignalR for broadcast-style or connection-oriented real-time features; do not force gRPC into hub-style fan-out scenarios.
    2. Model hub contracts intentionally and keep hub methods thin, delegating durable work elsewhere.
    3. Plan for reconnection, backpressure, auth, and fan-out costs instead of treating real-time messaging as stateless request/response.
    4. Use groups, presence, and connection metadata deliberately so scale-out behavior is understandable.
    5. If Native AOT or trimming is in play, validate supported protocols and serialization choices explicitly.
    6. Test connection behavior and failure modes, not just happy-path message delivery.
    
    ## Hub Patterns
    
    ### Strongly-Typed Hub (Recommended)
    ```csharp
    // Define the client interface
    public interface IChatClient
    {
        Task ReceiveMessage(string user, string message);
        Task UserJoined(string user);
        Task UserLeft(string user);
    }
    
    // Implement the strongly-typed hub
    public class ChatHub : Hub<IChatClient>
    {
        public async Task SendMessage(string user, string message)
        {
            // Compiler checks client method calls
            await Clients.All.ReceiveMessage(user, message);
        }
    
        public override async Task OnConnectedAsync()
        {
            await Clients.Others.UserJoined(Context.User?.Identity?.Name ?? "Anonymous");
            await base.OnConnectedAsync();
        }
    
        public override async Task OnDisconnectedAsync(Exception? exception)
        {
            await Clients.Others.UserLeft(Context.User?.Identity?.Name ?? "Anonymous");
            await base.OnDisconnectedAsync(exception);
        }
    }
    ```
    
    ### Using Groups for Targeted Messaging
    ```csharp
    public class NotificationHub : Hub<INotificationClient>
    {
        public async Task JoinGroup(string groupName)
        {
            await Groups.AddToGroupAsync(Context.ConnectionId, groupName);
            await Clients.Group(groupName).UserJoined(Context.User?.Identity?.Name);
        }
    
        public async Task LeaveGroup(string groupName)
        {
            await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);
        }
    
        public async Task SendToGroup(string groupName, string message)
        {
            await Clients.Group(groupName).ReceiveNotification(message);
        }
    }
    ```
    
    ### Hub Method with Custom Object Parameters (API Versioning)
    ```csharp
    // Use custom objects to avoid breaking changes
    public class SendMessageRequest
    {
        public string Message { get; set; } = string.Empty;
        public string? Recipient { get; set; }  // Added later without breaking clients
        public int? Priority { get; set; }       // Added later without breaking clients
    }
    
    public class ChatHub : Hub<IChatClient>
    {
        public async Task SendMessage(SendMessageRequest request)
        {
            // Handle both old and new clients
            if (request.Recipient != null)
            {
                await Clients.User(request.Recipient).ReceiveMessage(request.Message);
            }
            else
            {
                await Clients.All.ReceiveMessage(request.Message);
            }
        }
    }
    ```
    
    ## Client Patterns
    
    ### JavaScript Client with Automatic Reconnection
    ```javascript
    const connection = new signalR.HubConnectionBuilder()
        .withUrl("/chatHub")
        .withAutomaticReconnect([0, 2000, 5000, 10000, 30000]) // Retry delays
        .configureLogging(signalR.LogLevel.Information)
        .build();
    
    // Handle reconnection events
    connection.onreconnecting(error => {
        console.log("Reconnecting...", error);
        updateUIForReconnecting();
    });
    
    connection.onreconnected(connectionId => {
        console.log("Reconnected with ID:", connectionId);
        // Rejoin groups - reconnection does not restore group membership
        rejoinGroups();
        updateUIForConnected();
    });
    
    connection.onclose(error => {
        console.log("Connection closed", error);
        updateUIForDisconnected();
    });
    
    async function start() {
        try {
            await connection.start();
            console.log("SignalR Connected");
        } catch (err) {
            console.log(err);
            setTimeout(start, 5000);
        }
    }
    
    start();
    ```
    
    ### .NET Client with Reconnection
    ```csharp
    var connection = new HubConnectionBuilder()
        .WithUrl("https://localhost:5001/chatHub", options =>
        {
            options.AccessTokenProvider = () => Task.FromResult(GetAccessToken());
        })
        .WithAutomaticReconnect()
        .Build();
    
    connection.Reconnecting += error =>
    {
        _logger.LogWarning("Connection lost. Reconnecting: {Error}", error?.Message);
        return Task.CompletedTask;
    };
    
    connection.Reconnected += connectionId =>
    {
        _logger.LogInformation("Reconnected with ID: {ConnectionId}", connectionId);
        // Rejoin groups after reconnection
        return RejoinGroupsAsync();
    };
    
    connection.Closed += async error =>
    {
        _logger.LogError("Connection closed: {Error}", error?.Message);
        await Task.Delay(Random.Shared.Next(0, 5) * 1000);
        await connection.StartAsync();
    };
    
    await connection.StartAsync();
    ```
    
    ## Server Configuration
    
    ### Hub Registration with Authentication
    ```csharp
    var builder = WebApplication.CreateBuilder(args);
    
    builder.Services.AddSignalR(options =>
    {
        options.EnableDetailedErrors = builder.Environment.IsDevelopment();
        options.MaximumReceiveMessageSize = 64 * 1024; // 64 KB
        options.StreamBufferCapacity = 10;
        options.KeepAliveInterval = TimeSpan.FromSeconds(15);
        options.ClientTimeoutInterval = TimeSpan.FromSeconds(30);
    })
    .AddMessagePackProtocol(); // Binary protocol for performance
    
    builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.Events = new JwtBearerEvents
            {
                OnMessageReceived = context =>
                {
                    // Read token from query string for WebSocket connections
                    var accessToken = context.Request.Query["access_token"];
                    var path = context.HttpContext.Request.Path;
                    if (!string.IsNullOrEmpty(accessToken) && path.StartsWithSegments("/hubs"))
                    {
                        context.Token = accessToken;
                    }
                    return Task.CompletedTask;
                }
            };
        });
    
    var app = builder.Build();
    
    app.UseAuthentication();
    app.UseAuthorization();
    
    app.MapHub<ChatHub>("/hubs/chat");
    ```
    
    ### Sending Messages from Outside a Hub
    ```csharp
    public class NotificationService
    {
        private readonly IHubContext<NotificationHub, INotificationClient> _hubContext;
    
        public NotificationService(IHubContext<NotificationHub, INotificationClient> hubContext)
        {
            _hubContext = hubContext;
        }
    
        public async Task NotifyAllAsync(string message)
        {
            await _hubContext.Clients.All.ReceiveNotification(message);
        }
    
        public async Task NotifyUserAsync(string userId, string message)
        {
            await _hubContext.Clients.User(userId).ReceiveNotification(message);
        }
    
        public async Task NotifyGroupAsync(string groupName, string message)
        {
            await _hubContext.Clients.Group(groupName).ReceiveNotification(message);
        }
    }
    ```
    
    ## Scaling with Redis Backplane
    
    ```csharp
    builder.Services.AddSignalR()
        .AddStackExchangeRedis(connectionString, options =>
        {
            options.Configuration.ChannelPrefix = RedisChannel.Literal("MyApp");
        });
    ```
    
    ## Anti-Patterns to Avoid
    
    | Anti-Pattern | Why It's Bad | Better Approach |
    |--------------|--------------|-----------------|
    | Storing state in Hub properties | Hub instances are created per method call | Use `IMemoryCache`, database, or external store |
    | Instantiating Hub directly | Bypasses SignalR infrastructure | Use `IHubContext<THub>` for external messaging |
    | Not awaiting `SendAsync` calls | Messages may not be sent before hub method completes | Always `await` async hub calls |
    | Adding method parameters without versioning | Breaking change for existing clients | Use custom object parameters |
    | Ignoring reconnection group loss | Clients lose group membership on reconnect | Re-add to groups in `OnConnectedAsync` or client reconnect handler |
    | Large payloads over SignalR | Memory pressure, bandwidth issues | Use REST/gRPC for bulk data, SignalR for notifications |
    | Missing backplane in multi-server | Messages only reach clients on same server | Use Redis backplane or Azure SignalR Service |
    | Exposing ORM entities directly | May serialize sensitive data | Use DTOs with explicit properties |
    | Not validating incoming messages | Security risk after initial auth | Validate every hub method input |
    
    ## Best Practices
    
    ### Connection Management
    1. **Enable automatic reconnection** with exponential backoff delays
    2. **Handle group rejoining** explicitly after reconnection (connection ID changes)
    3. **Implement heartbeat monitoring** on the client to detect stale connections
    4. **Use sticky sessions** when scaling across multiple servers (unless using Azure SignalR Service)
    
    ### Performance
    1. **Use MessagePack protocol** for smaller message sizes and faster serialization
    2. **Throttle high-frequency events** like typing indicators or mouse movements
    3. **Batch messages** when possible instead of many small sends
    4. **Set appropriate buffer sizes** based on expected message throughput
    
    ### Security
    1. **Authenticate at connection time** using JWT tokens via query string
    2. **Authorize hub methods** using `[Authorize]` attribute
    3. **Validate all incoming messages** even after authentication
    4. **Use HTTPS** for all SignalR connections
    
    ### API Design
    1. **Use strongly-typed hubs** to catch client method name typos at compile time
    2. **Use custom object parameters** to enable backward-compatible API evolution
    3. **Version hub names** (e.g., `ChatHubV2`) for breaking changes
    4. **Keep hub methods thin** and delegate business logic to services
    
    ### Observability
    1. **Log connection events** (connect, disconnect, reconnect)
    2. **Track transport type** used by each connection
    3. **Monitor message delivery** latency and failure rates
    4. **Integrate with Application Insights** or other APM tools
    
    ## Deliver
    
    - clear hub contracts and connection behavior
    - real-time delivery that matches the product scenario
    - validation for reconnection and authorization flows
    - appropriate scale-out strategy for multi-server deployments
    
    ## Validate
    
    - SignalR is the correct transport for the use case
    - hub methods remain orchestration-oriented
    - group and auth behavior are explicit and tested
    - reconnection and group membership are handled correctly
    - backplane is configured for multi-server scenarios
    - message validation is implemented in hub methods
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.