Quickstart: Broadcast real-time messages from console app

Azure SignalR Service provides REST API to support server to client communication scenarios, such as broadcasting. You can choose any programming language that can make REST API call. You can post messages to all connected clients, a specific client by name, or a group of clients.

In this quickstart, you will learn how to send messages from a command-line app to connected client apps in C#.

Prerequisites

This quickstart can be run on macOS, Windows, or Linux.

If you don't have an Azure subscription, create a free account before you begin.

Sign in to Azure

Sign in to the Azure portal at https://portal.azure.com/ with your Azure account.

Create an Azure SignalR Service instance

Your application will connect to a SignalR Service instance in Azure.

  1. Select the New button found on the upper left-hand corner of the Azure portal. In the New screen, type SignalR Service in the search box and press enter.

    Search for SignalR Service

  2. Select SignalR Service from the search results, then select Create.

  3. Enter the following settings.

    Setting Suggested value Description
    Resource name Globally unique name Name that identifies your new SignalR Service instance. Valid characters are a-z, 0-9, and -.
    Subscription Your subscription The subscription under which this new SignalR Service instance is created.
    Resource Group myResourceGroup Name for the new resource group in which to create your SignalR Service instance.
    Location West US Choose a region near you.
    Pricing tier Free Try Azure SignalR Service for free.
    Unit count Not applicable Unit count specifies how many connections your SignalR Service instance can accept. It is only configurable in the Standard tier.

    Create SignalR Service

  4. Select Create to start deploying the SignalR Service instance.

  5. After the instance is deployed, open it in the portal and locate its Settings page. Change the Service Mode setting to Serverless.

    SignalR Service Mode

Clone the sample application

While the service is deploying, let's switch to prepare the code. Clone the sample app from GitHub, set the SignalR Service connection string, and run the application locally.

  1. Open a git terminal window. Change to a folder where you want to clone the sample project.

  2. Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.

    git clone https://github.com/aspnet/AzureSignalR-samples.git
    

Build and run the sample

This sample is a console app showing the use of Azure SignalR Service. It provides two modes:

  • Server Mode: use simple commands to call Azure SignalR Service REST API.
  • Client Mode: connect to Azure SignalR Service and receive messages from server.

Also you can find how to generate an access token to authenticate with Azure SignalR Service.

Build the executable file

We use macOS osx.10.13-x64 as example. You can find reference on how to build on other platforms.

cd AzureSignalR-samples/samples/Serverless/

dotnet publish -c Release -r osx.10.13-x64

Start a client

cd bin/Release/netcoreapp2.1/osx.10.13-x64/

Serverless client <ClientName> -c "<ConnectionString>" -h <HubName>

Start a server

cd bin/Release/netcoreapp2.1/osx.10.13-x64/

Serverless server -c "<ConnectionString>" -h <HubName>

Run the sample without publishing

You can also run the command below to start a server or client

# Start a server
dotnet run -- server -c "<ConnectionString>" -h <HubName>

# Start a client
dotnet run -- client <ClientName> -c "<ConnectionString>" -h <HubName>

Use user-secrets to specify Connection String

You can run dotnet user-secrets set Azure:SignalR:ConnectionString "<ConnectionString>" in the root directory of the sample. After that, you don't need the option -c "<ConnectionString>" anymore.

Usage

After the server started, use the command to send message:

send user <User Id>
send users <User List>
send group <Group Name>
send groups <Group List>
broadcast

You can start multiple clients with different client names.

Integration with third-party services

The Azure SignalR service allows third-party services to integrate with the system.

Definition of technical specifications

The following table shows all the versions of the REST APIs supported to date. You can also find the definition file for each specific version

Version API State Door Specific
1.0-preview Available 5002 Swagger
1.0 Available Standard Swagger

The list of available APIs for each specific version is available in the following list.

API 1.0-preview 1.0
Broadcast to all
Broadcast to a group
Broadcast to some groups (Deprecated) N / A
Send to specific users
Send to some users (Deprecated) N / A
Adding a user to a group N / A
Removing a user from a group N / A

Broadcast to everyone

Version API HTTP Method Request URL Request body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name> Same as above

Broadcast to a group

Version API HTTP Method Request URL Request body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/group/<group-name> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name> Same as above

Sending to specific users

Version API HTTP Method Request URL Request body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/user/<user-id> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id> Same as above

Adding a user to a group

Version API HTTP Method Request URL
1.0 PUT https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<userid>

Removing a user from a group

Version API HTTP Method Request URL
1.0 DELETE https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<userid>

Clean up resources

If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. In the Azure portal, select Resource groups on the far left, and then select the resource group you created. Alternatively, you may use the search box to find the resource group by its name.

  2. In the window that opens, select the resource group, and then click Delete resource group.

  3. In the new window, type the name of the resource group to delete, and then click Delete.

Next steps

In this quickstart, you learned how to use REST API to broadcast real-time message from SignalR Service to clients. Next, learn more about how to develop and deploy Azure Functions with SignalR Service binding, which is built on top of REST API.