TypedSignalR.Client
3.0.4
See the version list below for details.
dotnet add package TypedSignalR.Client --version 3.0.4
NuGet\Install-Package TypedSignalR.Client -Version 3.0.4
<PackageReference Include="TypedSignalR.Client" Version="3.0.4"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add TypedSignalR.Client --version 3.0.4
#r "nuget: TypedSignalR.Client, 3.0.4"
// Install TypedSignalR.Client as a Cake Addin #addin nuget:?package=TypedSignalR.Client&version=3.0.4 // Install TypedSignalR.Client as a Cake Tool #tool nuget:?package=TypedSignalR.Client&version=3.0.4
TypedSignalR.Client
C# Source Generator to create strongly typed SignalR client.
Table of Contents
- Install
- Why TypedSignalR.Client?
- API
- Usage
- Recommendation
- Compile-Time Error Support
- Generated Source Code
Install
NuGet: TypedSignalR.Client
dotnet add package Microsoft.AspNetCore.SignalR.Client
dotnet add package TypedSignalR.Client
Why TypedSignalR.Client?
The pure C# SignalR client is untyped. To call a Hub (server-side) function, we must specify the function defined in Hub using a string. We also have to determine the return type manually. Moreover, registering a client function called from the server also requires a string, and we must set the parameter types manually.
// Pure SignalR Client
// Specify the hub method to invoke using string.
await connection.InvokeAsync("HubMethod1");
// Manually determine the return type.
// The parameter is cast to object type.
var guid = await connection.InvokeAsync<Guid>("HubMethod2", "message", 99);
// Registering a client function requires a string,
// and the parameter types must be set manually.
var subscription = connection.On<string, DateTime>("ClientMethod", (message, dateTime) => {});
Therefore, if we change the code on the server-side, the modification on the client-side becomes very troublesome. The leading cause is that it is not strongly typed.
TypedSignalR.Client aims to generate a strongly typed SignalR client by sharing interfaces in which the server and client functions are defined. Defining interfaces are helpful not only for the client-side but also for the server-side. See Usage section for details.
// TypedSignalR.Client
// First, create a hub proxy.
IHub hubProxy = connection.CreateHubProxy<IHub>();
// Invoke a hub method through hub proxy.
// We no longer need to specify the function using a string.
await hubProxy.HubMethod1();
// Both parameters and return types are strongly typed.
var guid = await hubProxy.HubMethod2("message", 99);
// The client's function registration is also strongly typed, so it's safe and easy.
var subscription = connection.Register<IReceiver>(new Receiver());
// Defining interfaces are useful not only for the client-side but also for the server-side.
// See Usage in this README.md for details.
interface IHub
{
Task HubMethod1();
Task<Guid> HubMethod2(string message, int value);
}
interface IReceiver
{
Task ClientMethod(string message, DateTime dateTime);
}
class Receiver : IReceiver
{
...
}
API
This Source Generator provides two extension methods and one interface.
static class HubConnectionExtensions
{
THub CreateHubProxy<THub>(this HubConnection connection, CancellationToken cancellationToken = default){...}
IDisposable Register<TReceiver>(this HubConnection connection, TReceiver receiver){...}
}
// An interface for observing SignalR events.
interface IHubConnectionObserver
{
Task OnClosed(Exception? exception);
Task OnReconnected(string? connectionId);
Task OnReconnecting(Exception? exception);
}
Use it as follows.
HubConnection connection = ...;
IHub hub = connection.CreateHubProxy<IHub>();
IDisposable subscription = connection.Register<IReceiver>(new Receiver());
Usage
For example, we have the following interface defined.
public class UserDefinedType
{
public Guid Id { get; set; }
public DateTime Datetime { get; set; }
}
// The return type of methods on the client-side must be Task.
public interface IClientContract
{
// Of course, user defined type is OK.
Task ClientMethod1(string user, string message, UserDefinedType userDefine);
Task ClientMethod2();
}
// The return type of methods on the hub-side must be Task or Task<T>.
public interface IHubContract
{
Task<string> HubMethod1(string user, string message);
Task HubMethod2();
}
class Receiver1 : IClientContract
{
// implementation
}
class Receiver2 : IClientContract, IHubConnectionObserver
{
// implementation
}
Client
It's very easy to use.
HubConnection connection = ...;
var hub = connection.CreateHubProxy<IHubContract>();
var subscription1 = connection.Register<IClientContract>(new Receiver1());
// When an instance of a class that implements IHubConnectionObserver is registered (Receiver2 in this case),
// the method defined in IHubConnectionObserver is automatically registered regardless of the type argument.
var subscription2 = connection.Register<IClientContract>(new Receiver2());
// Invoke hub methods
hub.HubMethod1("user", "message");
// Unregister the receiver
subscription.Dispose();
Cancellation
In pure SignalR, CancellationToken
is passed for each invoke.
On the other hand, in TypedSignalR.Client, CancellationToken
is passed only once when creating hub proxy.
The passed CancelationToken
will be used for each invoke internally.
var cts = new CancellationTokenSource();
// The following two are equivalent.
// 1: Pure SignalR
var ret = await connection.InvokeAsync<string>("HubMethod1", "user", "message", cts.Token);
await connection.InvokeAsync("HubMethod2", cts.Token);
// 2: TypedSignalR.Client
var hubProxy = connection.CreateHubProxy<IHubContract>(cts.Token);
var ret = await hubProxy.HubMethod1("user", "message");
await hubProxy.HubMethod2();
Server
Using the interface definitions, we can write as follows on the server-side (ASP.NET Core). TypedSignalR.Client is not nessesary.
using Microsoft.AspNetCore.SignalR;
public class SomeHub : Hub<IClientContract>, IHubContract
{
public async Task<string> HubMethod1(string user, string message)
{
var instance = new UserDefinedType()
{
Id = Guid.NewGuid(),
DateTime = DateTime.Now,
};
// broadcast
await this.Clients.All.ClientMethod1(user, message, instance);
return "OK!";
}
public async Task HubMethod2()
{
await this.Clients.Caller.ClientMethod2();
}
}
Recommendation
Sharing a Project
I recommend that these interfaces be shared between the client-side and server-side project, for example, by project references.
server.csproj --> shared.csproj <-- client.csproj
Client Code Format
It is easier to handle if we write the client code in the following format.
class Client : IReceiver, IHubConnectionObserver, IDisposable
{
private readonly IHub _hubProxy;
private readonly IDisposable _subscription;
private readonly CancellationTokenSource _cancellationTokenSource = new();
public Client(HubConnection connection)
{
_hubProxy = connection.CreateHubProxy<IHub>(_cancellationTokenSource.Token);
_subscription = connection.Register<IReceiver>(this);
}
// implementation
}
Compile-Time Error Support
This library has some restrictions, including those that come from server-side implementations.
- Type argument of the
CreateHubProxy/Register
method must be an interface. - Only method definitions are allowed in the interface used for
CreateHubProxy/Register
.- It is forbidden to define properties and events.
- The return type of the method in the interface used for
CreateHubProxy
must beTask
orTask<T>
. - The return type of the method in the interface used for
Register
must beTask
.
It is complicated for humans to comply with these restrictions properly. So, this library looks for parts that do not follow the restriction and report detailed errors at compile-time. Therefore, no run-time error occurs.
Generated Source Code
TypedSignalR.Client checks the type argument of a methods CreateHubProxy
and Register
and generates source code.
Generated source code can be seen in Visual Studio.
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on TypedSignalR.Client:
Repository | Stars |
---|---|
nenoNaninu/TypedSignalR.Client
C# Source Generator to Create Strongly Typed SignalR Clients.
|
Version | Downloads | Last updated |
---|---|---|
3.6.0 | 4,251 | 9/25/2024 |
3.5.2 | 23,499 | 4/3/2024 |
3.5.1 | 256 | 4/2/2024 |
3.5.0 | 358 | 3/31/2024 |
3.4.4 | 182 | 3/31/2024 |
3.4.3 | 11,261 | 12/5/2023 |
3.4.2 | 2,376 | 11/27/2023 |
3.4.1 | 537 | 11/25/2023 |
3.4.0 | 11,070 | 4/28/2023 |
3.3.0 | 1,135 | 2/7/2023 |
3.2.1 | 3,821 | 11/27/2022 |
3.1.1 | 7,473 | 8/14/2022 |
3.0.7 | 679 | 6/2/2022 |
3.0.6 | 534 | 5/8/2022 |
3.0.4 | 502 | 4/22/2022 |
3.0.3 | 451 | 4/15/2022 |
3.0.2 | 524 | 3/6/2022 |
3.0.1 | 451 | 2/21/2022 |
2.1.0 | 365 | 12/26/2021 |
2.0.1 | 2,087 | 6/16/2021 |
2.0.0 | 364 | 6/10/2021 |
1.1.0 | 369 | 5/13/2021 |
1.0.2 | 344 | 5/12/2021 |
1.0.1 | 315 | 5/11/2021 |
1.0.0 | 344 | 5/11/2021 |
0.0.1 | 541 | 5/11/2021 |