Quickstart: Publish messages using the Azure Web PubSub service SDK

Azure Web PubSub helps you manage WebSocket clients. This quickstart shows you how to publish messages to WebSocket clients using Azure Web PubSub service SDK.

Prerequisites

An Azure subscription, if you don't have one, create a trial subscription.
a Bash and PowerShell command shell. The Python, JavaScript and Java samples require a Bash command shell.
A file editor such as VS Code.
Azure CLI: install the Azure CLI

If creating the project on a local machine, you'll need to install the dependencies for the language you're using:

Install both the .NET Core SDK and the aspnetcore and dotnet runtime.

.NET Core

1. Setup

To sign in to Azure from the CLI, run the following command and follow the prompts to complete the authentication process.

az login

Ensure you're running the latest version of the CLI via the upgrade command.

az upgrade

Next, install or update the Azure Web PubSub extension for the CLI if it wasn't installed with az upgrade.

az extension add --name webpubsub --upgrade

1. Create a resource group

Set the following environment variables. Replace the <placeholder> with a unique Web PubSub name.

Bash
Azure PowerShell

RESOURCE_GROUP="webpubsub-resource-group"
LOCATION="China East 2"
WEB_PUBSUB_NAME="<your-unique-name>"

$ResourceGroupName = 'webpubsub-resource-group'
$Location = 'China East 2'
$WebPubSubName = '<YourUniqueName>'

Create a resource group for the Web PubSub project.

Bash
Azure PowerShell

az group create \
  --name $RESOURCE_GROUP \
  --location $LOCATION

az group create --location $Location --name $ResourceGroupName

2. Deploy a Web PubSub service instance

Use the az webpubsub create command to create and deploy a Web PubSub service instance.

Bash
Azure PowerShell

az webpubsub create \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --sku Free_F1

az webpubsub create `
  --name $WebPubSubName `
  --location $Location `
  --resource-group $ResourceGroupName `
  --sku Free_F1

Save the service's connection string. The connection string is used by the service SDK to publish messages.

Important

In a production environment, you should securely store connection strings using Azure Key Vault.

Bash
Azure PowerShell

az webpubsub key show --name $WEB_PUBSUB_NAME --resource-group $RESOURCE_GROUP --query primaryConnectionString

az webpubsub key show --name $WebPubSubName --resource-group $ResourceGroupName --query primaryConnectionString

3. Connect a client to the service instance

Create a Web PubSub client. The client maintains a connection to the service until it's terminated.

Use the az webpubsub client command to start a WebSocket client connection to the service. The clients always connect to a hub, so provide a hub name for the client to connect to.

Bash
Azure PowerShell

az webpubsub client start \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --hub-name "myHub1" \
  --user-id "user1"

az webpubsub client start `
  --name $WebPubSubName `
  --resource-group $ResourceGroupName `
  --hub-name 'myHub1' `
  --user-id 'user1'

The connection to the Web PubSub service is established when you see a JSON message indicating that the client is now successfully connected, and is assigned a unique connectionId:

{"type":"system","event":"connected","userId":"user1","connectionId":"<your_unique_connection_id>"}

4. Publish messages using service SDK

You'll use the Azure Web PubSub SDK to publish a message to all the clients connected to the hub. You can choose between C#, JavaScript, Python and Java. The dependencies for each language are installed in the steps for that language. Python, JavaScript and Java require a bash shell to run the commands in this quickstart.

Set up the project to publish messages

Open a new command shell for this project.
Save the connection string from the client shell. Replace the <your_connection_string> placeholder with the connection string you displayed in an earlier step.
- Bash
- Azure PowerShell
```
connection_string="<your_connection_string>"
```
```
$connection_string = "<your_connection_string>"
```
Now, select the language for your project.

Add a new project named publisher and the SDK package Azure.Messaging.WebPubSub.

mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub

Update the Program.cs file to use the WebPubSubServiceClient class to send messages to the clients. Replace the code in the Program.cs file with the following code.

using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;

namespace publisher
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 3) {
                Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];
            var message = args[2];

            var service = new WebPubSubServiceClient(connectionString, hub);

            // Send messages to all the connected clients
            // You can also try SendToConnectionAsync to send messages to the specific connection
            await service.SendToAllAsync(message);
        }
    }
}

The service.SendToAllAsync() call simply sends a message to all connected clients in the hub.

Run the following command to publish a message to the service.
```
dotnet run $connection_string "myHub1" "Hello World"
```
The previous command shell containing the Web PubSub client shows the received message.
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

Create a new folder named publisher for this project and install required dependencies:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Use Azure Web PubSub SDK to publish a message to the service. Create a publish.js file containing the code:

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

if (process.argv.length !== 3) {
  console.log('Usage: node publish <message>');
  return 1;
}
const hub = "myHub1";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });

The sendToAll() call simply sends a message to all connected clients in a hub.

Run the following command to publish a message to the service:

export WebPubSubConnectionString=$connection_string
node publish "Hello World"

The previous command shell containing the Web PubSub client shows the received message.
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

Create a new folder named publisher for this project and install required dependencies:

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate
pip install azure-messaging-webpubsubservice

Use Azure Web PubSub SDK to publish a message to the service. Create a publish.py file with the below code:

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

The service.send_to_all() method sends the message to all connected clients in a hub.

Run the following command to publish a message to the service:
```
python publish.py $connection_string "myHub1" "Hello World"
```
The previous command shell containing the Web PubSub client shows the received message.
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

Use Maven to create a new console app named webpubsub-quickstart-publisher and go to the webpubsub-quickstart-publisher directory:

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-publisher --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-publisher

Add the Azure Web PubSub SDK to the dependencies node of pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

Go to the src/main/java/com/webpubsub/quickstart directory.

Replace the contents in the App.java file with the following code:

package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App 
{
    public static void main( String[] args )
    {
        if (args.length != 3) {
            System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();
        service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
    }
}

This code uses the Azure Web PubSub SDK to publish a message to the service. The service.sendToAll() call sends a message to all connected clients in a hub.

Return t the webpubsub-quickstart-publisher directory containing the pom.xml file and compile the project by using the following mvn command.
```
mvn compile
```
Build the package.
```
mvn package
```

Run the following mvn command to execute the app to publish a message to the service:

mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args=" '$connection_string' 'myHub1' 'Hello World'"

The previous command shell containing the Web PubSub client shows the received message.
```
{"type":"message","from":"server","dataType":"text","data":"Hello World"}
```

Cleanup

You can delete the resources that you created in this quickstart by deleting the resource group that contains them.

Bash
Azure PowerShell

az group delete --name $RESOURCE_GROUP --yes

az group delete --name $ResourceGroup --yes

Next steps

This quickstart provides you a basic idea of how to connect to the Web PubSub service and how to publish messages to the connected clients.

In real-world applications, you can use SDKs in various languages build your own application. We also provide Function extensions for you to build serverless applications easily.

Use these resources to start building your own application:

Tutorial: Publish and subscribe to messages in Azure Web PubSub

Tutorial: Create a simple chatroom with Azure Web PubSub

Tutorial: Use a service-supported subprotocol for client streaming

Tutorial: Build serverless chat with Azure Functions and Web PubSub

Tutorial: Configure an event listener

Play with live demos

Explore more Azure Web PubSub samples