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 calls. You can post messages to all connected clients, a specific client by name, or a group of clients.
In this quickstart, you 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.
- .NET Core SDK
- A text editor or code editor of your choice.
If you don't have an Azure subscription, create an Azure free account before you begin.
Having issues? Try the troubleshooting guide or let us know.
Sign in to Azure
Sign in to the Azure portal using your Azure account.
Having issues? Try the troubleshooting guide or let us know.
In this section, you create a basic Azure SignalR instance to use for your app. The following steps use the Azure portal to create a new instance, but you can also use the Azure CLI. For more information, see the az signalr create command in the Azure SignalR Service CLI Reference.
- Sign in to the Azure portal.
- In the upper-left side of the page, select + Create a resource.
- On the Create a resource page, in the Search services and marketplace text box, enter signalr and then select SignalR Service from the list.
- On the SignalR Service page, select Create.
- On the Basics tab, you enter the essential information for your new SignalR Service instance. Enter the following values:
| Field | Suggested Value | Description |
|---|---|---|
| Subscription | Choose your subscription | Select the subscription you want to use to create a new SignalR Service instance. |
| Resource group | Create a resource group named SignalRTestResources | Select or create a resource group for your SignalR resource. It's useful to create a new resource group for this tutorial instead of using an existing resource group. To free resources after completing the tutorial, delete the resource group. Deleting a resource group also deletes all of the resources that belong to the group. This action can't be undone. Before you delete a resource group, make certain that it doesn't contain resources you want to keep. For more information, see Using resource groups to manage your Azure resources. |
| Resource name | testsignalr | Enter a unique resource name to use for the SignalR resource. If testsignalr is already taken in your region, add a digit or character until the name is unique. The name must be a string of 1 to 63 characters and contain only numbers, letters, and the hyphen ( -) character. The name can't start or end with the hyphen character, and consecutive hyphen characters aren't valid. |
| Region | Choose your region | Select the appropriate region for your new SignalR Service instance. Azure SignalR Service isn't currently available in all regions. For more information, see Azure SignalR Service region availability |
| Pricing tier | Select Change and then choose Free (Dev/Test Only). Choose Select to confirm your choice of pricing tier. | Azure SignalR Service has three pricing tiers: Free, Standard, and Premium. Tutorials use the Free tier, unless noted otherwise in the prerequisites. For more information about the functionality differences between tiers and pricing, see Azure SignalR Service pricing |
| Service mode | Choose the appropriate service mode | Use Default when you host the SignalR hub logic in your web apps and use SignalR service as a proxy. Use Serverless when you use Serverless technologies such as Azure Functions to host the SignalR hub logic. Classic mode is only for backward compatibility and isn't recommended to use. For more information, see Service mode in Azure SignalR Service. |
You don't need to change the settings on the Networking and Tags tabs for the SignalR tutorials.
- Select the Review + create button at the bottom of the Basics tab.
- On the Review + create tab, review the values and then select Create. It takes a few moments for deployment to complete.
- When the deployment is complete, select the Go to resource button.
- On the SignalR resource page, select Keys from the menu on the left, under Settings.
- Copy the Connection string for the primary key. You need this connection string to configure your app later in this tutorial.
Having issues? Try the troubleshooting guide or let us know.
Clone the sample application
While the service is being deployed, let's get the code ready. First, clone the sample app from GitHub. Next, set the SignalR Service connection string to the app. Finally, run the application locally.
Open a git terminal window. Change to a folder where you want to clone the sample project.
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
Having issues? Try the troubleshooting guide or let us know.
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.
You also learn 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>
Having issues? Try the troubleshooting guide or let us know.
Run the sample without publishing
You can also run the following command 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.
Having issues? Try the troubleshooting guide or let us know.
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.
Having issues? Try the troubleshooting guide or let us know.
Integration with non-Microsoft services
The Azure SignalR service allows non-Microsoft 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 a user | ✓ | ✓ |
| Send to some users | ✓ (Deprecated) | N / A |
| Adding a user to a group | N / A |
✓ |
| Removing a user from a group | N / A |
✓ |
| Check user existence | N / A |
✓ |
| Remove a user from all groups | N / A |
✓ |
| Send to a connection | N / A |
✓ |
| Add a connection to a group | N / A |
✓ |
| Remove a connection from a group | N / A |
✓ |
| Close a client connection | N / A |
✓ |
| Service Health | 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> |
{"target": "<method-name>", "arguments": [...]} |
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> |
{"target": "<method-name>", "arguments": [...]} |
Sending to a user
| 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> |
{"target": "<method-name>", "arguments": [...]} |
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/<user-id> |
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/<user-id> |
Check user existence in a group
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id>/groups/<group-name> |
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<user-id> |
| Response Status Code | Description |
|---|---|
200 |
User exists |
404 |
User not exists |
Remove a user from all groups
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id>/groups |
Send message to a connection
| API Version | API HTTP Method | Request URL | Request Body |
|---|---|---|---|
1.0 |
POST |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id> |
{ "target":"<method-name>", "arguments":[ ... ] } |
Add a connection to a group
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/connections/<connection-id> |
1.0 |
PUT |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>/groups/<group-name> |
Remove a connection from a group
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/connections/<connection-id> |
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>/groups/<group-name> |
Close a client connection
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id> |
1.0 |
DELETE |
https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/connections/<connection-id>?reason=<close-reason> |
Service Health
| API Version | API HTTP Method | Request URL |
|---|---|---|
1.0 |
GET |
https://<instance-name>.service.signalr.net/api/v1/health |
| Response Status Code | Description |
|---|---|
200 |
Service Good |
5xx |
Service Error |
Having issues? Try the troubleshooting guide or let us know.
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:
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.
In the window that opens, select the resource group, and then click Delete resource group.
In the new window, type the name of the resource group to delete, and then click Delete.
Having issues? Try the troubleshooting guide or let us know.
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.