Skip to content

Latest commit

 

History

History
209 lines (150 loc) · 11.7 KB

management-sdk-guide.md

File metadata and controls

209 lines (150 loc) · 11.7 KB
Raw

Azure SignalR Service Management SDK

This SDK is for ASP.NET Core SignalR. For differences between ASP.NET SignalR and ASP.NET Core SignalR, see here.

Build Status

Windows Ubuntu OSX

Nuget Packages

Package Name Target Framework NuGet MyGet
Microsoft.Azure.SignalR.Management .NET Standard 2.0
.NET Core App 3.0
.NET 5.0		 NuGet MyGet

Getting Started

Azure SignalR Service Management SDK helps you to manage SignalR clients through Azure SignalR Service directly such as broadcast messages. Therefore, this SDK can be but not limited to be used in serverless environments. You can use this SDK to manage SignalR clients connected to your Azure SignalR Service in any environment, such as in a console app, in an Azure function or in a web server.

To see guides for SDK version 1.9.x and before, go to Azure SignalR Service Management SDK (Legacy). You might also want to read Migration guidance.

Features

Transient Persistent
Broadcast ✔️ ✔️
Broadcast except some clients ✔️ ✔️
Send to a client ✔️ ✔️
Send to clients ✔️ ✔️
Send to a user ✔️ ✔️
Send to users ✔️ ✔️
Send to a group ✔️ ✔️
Send to groups ✔️ ✔️
Send to a group except some clients ✔️ ✔️
Add a user to a group ✔️ ✔️
Remove a user from a group ✔️ ✔️
Check if a user in a group ✔️ ✔️
Multiple SignalR service instances support ❌ ✔️
MessagePack clients support since v1.21.0 since v1.20.0

Features only come with new API

Transient Persistent
Check if a connection exists ✔️ Since v1.11
Check if a group exists ✔️ Since v1.11
Check if a user exists ✔️ Since v1.11
Close a client connection ✔️ Since v1.11

More details about different modes can be found here.

For a full sample on management SDK, please go here.

Create Service Manager

Build your instance of ServiceManager from a ServiceManagerBuilder

var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

You can use ServiceManager to check the Azure SignalR endpoint health and create service hub context. The following section provides details about creating service hub context.

To check the Azure SignalR endpoint health, you can use ServiceManager.IsServiceHealthy method. Note that if you have multiple Azure SignalR endpoints, only the first endpoint will be checked.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Create Service Hub Context

Create your instance of ServiceHubContext from a ServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Negotiation

In server mode, an endpoint /<Your Hub Name>/negotiate is exposed for negotiation by Azure SignalR Service SDK. SignalR clients will reach this endpoint and then redirect to Azure SignalR Service later.

Unlike server scenario, there is no web server accepts SignalR clients in serverless scenario. To protect your connection string, you need to redirect SignalR clients from the negotiation endpoint to Azure SignalR Service instead of giving your connection string to all the SignalR clients.

The best practice is to host a negotiation endpoint and then you can use SignalR clients to connect your hub: /<Your Hub Name>.

Read more details about the redirection at SignalR's Negotiation Protocol.

Both of endpoint and access token are useful when you want to redirect SignalR clients to your Azure SignalR Service.

You can use the instance of ServiceHubContext to generate the endpoint url and corresponding access token for SignalR clients to connect to your Azure SignalR Service.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Suppose your hub endpoint is http://<Your Host Name>/<Your Hub Name>, then your negotiation endpoint will be http://<Your Host Name>/<Your Hub Name>/negotiate. Once you host the negotiation endpoint, you can use the SignalR clients to connect to your hub like this:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

The sample on how to use Management SDK to redirect SignalR clients to Azure SignalR Service can be found here.

Send Messages and Manage Groups

The ServiceHubContext we build from ServiceHubContextBuilder is a class that implements and extends IServiceHubContext. You can use it to send messages to your clients as well as managing your groups.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Strongly typed hub

A strongly typed hub is a programming model that you can extract your client methods into an interface, so that avoid errors like misspelling the method name or passing the wrong parameter types.

Let's say we have a client method called ReceivedMessage with two string parameters. Without strongly typed hubs, you broadcast to clients through hubContext.Clients.All.SendAsync("ReceivedMessage", user, message). With strongly typed hubs, you first define an interface like this:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

And then you create a strongly typed hub context which implements IHubContext<Hub<T>, T>, T is your client method interface:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Finally, you could directly invoke the method:

await Clients.All.ReceiveMessage(user, message);

Except for the difference of sending messages, you could negotiate or manage groups with ServiceHubContext<T> just like ServiceHubContext.

To read more on strongly typed hubs in the ASP.NET Core docs, go here.

Transport Type

This SDK can communicates to Azure SignalR Service with two transport types:

  • Transient: Create a Http request Azure SignalR Service for each message sent. The SDK simply wrap up Azure SignalR Service REST API in Transient mode. It is useful when you are unable to establish a WebSockets connection.
  • Persistent: Create a WebSockets connection first and then send all messages in this connection. It is useful when you send large amount of messages.

Summary of Serialization behaviors of the Arguments in Messages

Transient Persistent
Default JSON library Newtonsoft.Json The same as Asp.Net Core SignalR:
Newtonsoft.Json for .NET Standard 2.0;
System.Text.Json for .NET Core App 3.1 and above
MessaegPack clients support since v1.21.0 since v1.20.0

Json serialization

See Customizing Json Serialization in Management SDK

Message Pack serialization

  1. You need to install Microsoft.AspNetCore.SignalR.Protocols.MessagePack package.
  2. To add a MessagePack protocol side-by-side with the default JSON protocol: 
    var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());
  3. To fully control the hub protocols, you can use 
        var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());
    WithHubProtocols first clears the existing protocols, and then adds the new protocols. You can also use this method to remove the JSON protocol and use MessagePack only.

For transient mode, by default the service side converts JSON payload to MessagePack payload and it's the legacy way to support MessagePack. However, we recommend you to add a MessagePack hub protocol explicitly as the legacy way might not work as you expect.