SignalRGen 2.0.0

SignalRGen

A source generator for SignalR that eliminates boilerplate and provides strongly-typed clients

What is SignalRGen?

SignalRGen transforms the SignalR experience by using source generation to:

• ✅ Eliminate boilerplate connection management code
• ✅ Provide strongly-typed method calls and event handlers
• ✅ Enable seamless dependency injection integration
• ✅ Allow easy distribution of clients as NuGet packages

Installation

dotnet add package SignalRGen

YOLO development builds are also available in this GitHub repository.

Quick Start

1. Define your Hub interface

using SignalRGen.Abstractions;
using SignalRGen.Abstractions.Attributes;

[HubClient(HubUri = "chat")]
public interface IChatHubContract : IBidirectionalHub<IChatHubServerToClient, IChatHubClientToServer>
{
}

// This interface describes the flow of data from the server to the client.
public interface IChatHubServerToClient
{
    Task MessageReceived(string user, string message);
}

// This interface describes the flow of data from the client to the server.
public interface IChatHubClientToServer
{
    Task SendMessage(string message);
}

2. Register on the server

var app = builder.Build();

app.MapHub<ChatHub>($"{ChatHubContractClient.HubUri}");

3. Register in the client

builder.Services
    .AddSignalRHubs(c => c.HubBaseUri = new Uri("http://localhost:5155"))
    .WithChatHubContractClient();

4. Use the generated client

public class ChatService
{
    private readonly ChatHubContractClient _hubClient;
    
    public ExampleComponent(ChatHubContractClient hubClient)
    {
        _hubClient = hubClient;
        _hubClient.MessageReceived += HandleMessageReceived;
    }
    
    public async Task Initialize()
    {
        // Connection handling is done automatically
        await _hubClient.StartAsync();
        
        // Strongly-typed method invocation
        await _hubClient.InvokeSendMessageAsync("Hello from SignalRGen!");
    }
    
    private async Task HandleMessageReceived(string user, string message)
    {
        Console.WriteLine($"New message from {user}: {message}");
        return Task.CompletedTask;
    }
}

How It Works

SignalRGen uses C# source generators to analyze your SignalR hub interfaces and automatically generate:

1. Strongly-typed hub clients - No more string-based method names
2. Connection management - Automatic reconnection and state handling
3. DI extensions - Simple registration with your IoC container
4. Event handlers - Type-safe callbacks for server notifications

Example Blazor Component

@page "/Chat"
@using SignalRGen.Example.Contracts

@* We inject the generated client. *@
@* Notice that we use the actual type, not the interface we defined. *@
@inject ChatHubContractClient ChatHubClient;

<h3>Chat</h3>

<p>This is a really crude example of a chat that uses SignalR generated by SignalRGen to communicate.</p>
<p>It is kept simple to better showcase the generated SignalR code. This is not how a real chat app would look like.</p>
<p>To get the example working it is best to duplicate this tab a couple of times and open them in different browser tabs.
    After that enter a username in each tab and join the chat room. You should be able to see the sent message on all tabs.</p>
@if (!_joined)
{
    <div class="username-section">
        <input type="text" @bind="_username" placeholder="Enter username"/>
        <button @onclick="Join" disabled="@(!string.IsNullOrEmpty(_confirmedUsername))">Join</button>
    </div>
}
else
{
    <div class="chatting-as-section">
        <p>Chatting as: <span>@_confirmedUsername</span></p>
    </div>
    <div class="message-section">
        <input type="text" @bind="_message" placeholder="Enter message"/>
        <button @onclick="SendMessage">Send</button>
        <div class="messages">
            @foreach (var message in _messages)
            {
                <div>@message</div>
            }
        </div>
    </div>
}

@code {
    private string _username = string.Empty;
    private string _confirmedUsername = string.Empty;
    private bool _joined = false;
    private string _message = string.Empty;
    private List<string> _messages = new();

    private async Task Join()
    {
        if (!string.IsNullOrWhiteSpace(_username))
        {
            _confirmedUsername = _username;
            _username = string.Empty;
            _joined = true;

            // We subscribe to the `OnUserJoined` event to get notified whenever a new user joined.
            ChatHubClient.OnUserJoined += async user =>
            {
                _messages.Add($"~~ User '{user}' joined ~~");
                await InvokeAsync(StateHasChanged);
            };
            
            // We subscribe to the `OnUserLeft` event to get notified whenever a user left.
            ChatHubClient.OnUserLeft += async user =>
            {
                _messages.Add($"~~ User '{user}' left ~~");
                await InvokeAsync(StateHasChanged);
            };
            
            // We subscribe to the `OnMessageReceived` event to get notified whenever a new message
            // was sent by other users.
            ChatHubClient.OnMessageReceived += async (user, message) =>
            {
                _messages.Add($"{user}: {message}");
                await InvokeAsync(StateHasChanged);
            };
            
            // We use the headers in this stripped-down example as a means to send the username along.
            // In a real chat app this would be dealt with differently, but it is a nice showcase
            // on how to pass along runtime-based headers.
            var headers = new Dictionary<string, string>()
            {
                { "username", _confirmedUsername }
            };
            
            // We start the Hub, which will internally build up the connection to the server.
            await ChatHubClient.StartAsync(headers: headers);
        }
    }

    private async Task SendMessage()
    {
        // We are invoking the `InvokeSendMessageAsync` method to send the message to the server,
        // which will propagate it to the other users.
        await ChatHubClient.InvokeSendMessageAsync(_message);
        _messages.Add($"{_confirmedUsername}: {_message}");
        await InvokeAsync(StateHasChanged);
        _message = string.Empty;
    }

}

Advanced Configuration

SignalRGen allows full customization of your hub connections:

builder.Services
    .AddExampleHubs(c => c.HubBaseUri = new Uri("http://localhost:5155"))
    .WithChatHubContractClient(config =>
    {
        config.HubClientLifetime = ServiceLifetime.Scoped;
        config.HttpConnectionOptionsConfiguration = options =>
        {
            options.Headers.Add("custom-header", "foo");
        };
        config.HubConnectionBuilderConfiguration = connectionBuilder =>
        {
            connectionBuilder.WithKeepAliveInterval(TimeSpan.FromMinutes(1));
        };
    });

Documentation

For complete documentation, samples, and API reference, visit our documentation site.

Acknowledgements

This library wouldn't be possible without the following people:

• Andrew Lock
• Anton Wieslander (aka RawCoding)
• Jeffrey T. Fritz (aka csharpfritz)
• BissauCam