Push messages from server

Node.js

.NET Core

Python

• Java Development Kit (JDK).
• Apache Maven

Create a project directory named subscriber and install required dependencies

mkdir subscriber
cd subscriber
npm init -y

# The client SDK is available as a module on NPM
npm install @azure/web-pubsub-client

Connect to your Web PubSub resource and register a listener for the server-message event

A client uses a Client Access URL to connect and authenticate with your resource. This URL follows a pattern of wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. A client can have a few ways to obtain the Client Access URL. For this quick start, you can copy and paste one from Azure portal shown in the following diagram. It's best practice to not hard code the Client Access URL in your code. In the production world, we usually set up an app server to return this URL on demand. Generate Client Access URL describes the practice in detail.

As shown in the diagram above, the client joins the hub named myHub1.

In the subscriber project folder, create a file named subscribe.js with the following code

const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
// <client-access-url> is copied from Azure portal mentioned above
const client = new WebPubSubClient("<client-access-url>")

// Registers a handler for the "server-message" event
client.on("server-message", (e) => {
    console.log(`Received message ${e.message.data}`)
});

// Before a client can receive a message, 
// you must invoke start() on the client object.
await client.start();

Run the program

node subscribe.js

Now this client establishes a connection with your Web PubSub resource and is ready to receive messages pushed from your application server.

Create a project directory named subscriber and install required dependencies

mkdir subscriber
cd subscriber
# Create a .NET console app
dotnet new console

# Add the client SDK
dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

Connect to your Web PubSub resource and register a listener for the ServerMessageReceived event

A client uses a Client Access URL to connect and authenticate with your resource. This URL follows a pattern of wss://<service_name>.webpubsub.azure.cn/client/hubs/<hub_name>?access_token=<token>. A client can have a few ways to obtain the Client Access URL. For this quick start, you can copy and paste one from Azure portal shown in the following diagram. It's best practice to not hard code the Client Access URL in your code. In the production world, we usually set up an app server to return this URL on demand. Generate Client Access URL describes the practice in detail.

As shown in the diagram above, the client joins the hub named myHub1.

Replace the code in the Program.cs with the following code

using Azure.Messaging.WebPubSub.Clients;

// Instantiates the client object
// <client-access-uri> is copied from Azure portal mentioned above
var client = new WebPubSubClient(new Uri("<client-access-uri>"));
client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.Connected += eventArgs =>
{
    Console.WriteLine("Connected");
    return Task.CompletedTask;
};

await client.StartAsync();

// This keeps the subscriber active until the user closes the stream by pressing Ctrl+C
var streaming = Console.ReadLine();
while (streaming != null)
{
    if (!string.IsNullOrEmpty(streaming))
    {
        await client.SendToGroupAsync("stream", BinaryData.FromString(streaming + Environment.NewLine), WebPubSubDataType.Text);
    }

    streaming = Console.ReadLine();
}

await client.StopAsync();

Run the following command

dotnet run

Now this client establishes a connection with your Web PubSub resource and is ready to receive messages pushed from your application server.

Create a project directory named subscriber and install required dependencies:

mkdir subscriber
cd subscriber

# Create venv
python -m venv env
# Activate venv
source ./env/bin/activ

pip install azure-messaging-webpubsubservice
pip install websock

Use the WebSocket API to connect to your Web PubSub resource. Create a subscribe.py file with the following code

import asyncio
import sys
import websockets

from azure.messaging.webpubsubservice import WebPubSubServiceClient

async def connect(url):
    async with websockets.connect(url) as ws:
        print('connected')
        while True:
            print('Received message: ' + await ws.recv())

if __name__ == '__main__':

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

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

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    token = service.get_client_access_token()

    try:
        asyncio.get_event_loop().run_until_complete(connect(token['url']))
        except KeyboardInterrupt:
            pass

The code creates a WebSocket connection that is connected to a hub in Web PubSub. A hub is a logical unit in Web PubSub where you can publish messages to a group of clients. Key concepts contains the detailed explanation about the terms used in Web PubSub.

The Web PubSub service uses JSON Web Token (JWT) authentication. The sample code uses WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK to generate a URL to the service that contains the full URL with a valid access token.

After the connection is established, your client will receive messages through the WebSocket connection. Use await ws.recv() to listen for incoming messages.

Run the following command

python subscribe.py $connection_string "myHub1"

Create a project directory named pubsub

mkdir pubsub
cd pubsub

Use Maven to create a new console app called webpubsub-quickstart-subscriber;

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

cd webpubsub-quickstart-subscriber

Add WebSocket and Azure Web PubSub SDK to the dependencies node in pom.xml:

• azure-messaging-webpubsub: Web PubSub service SDK for Java
• Java-WebSocket: WebSocket client SDK for Java

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.1</version>
</dependency>

In Web PubSub, you can connect to the service and subscribe to messages through WebSocket connections. WebSocket is a full-duplex communication channel allowing the service to push messages to your client in real time. You can use any API or library that supports WebSocket. For this sample, we use package Java-WebSocket.

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

2. Edit replace the contents of the App.java file with the following code:

   package com.webpubsub.quickstart;
   
   import com.azure.messaging.webpubsub.*;
   import com.azure.messaging.webpubsub.models.*;
   
   import org.java_websocket.client.WebSocketClient;
   import org.java_websocket.handshake.ServerHandshake;
   
   import java.io.IOException;
   import java.net.URI;
   import java.net.URISyntaxException;
   
   /**
   * Connect to Azure Web PubSub service using WebSocket protocol
   */
   public class App 
   {
       public static void main( String[] args ) throws IOException, URISyntaxException
       {
           if (args.length != 2) {
               System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
               return;
           }
   
           WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
               .connectionString(args[0])
               .hub(args[1])
               .buildClient();
   
           WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());
   
           WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
               @Override
               public void onMessage(String message) {
                   System.out.println(String.format("Message received: %s", message));
               }
   
               @Override
               public void onClose(int arg0, String arg1, boolean arg2) {
                   // TODO Auto-generated method stub
               }
   
               @Override
               public void onError(Exception arg0) {
                   // TODO Auto-generated method stub
               }
   
               @Override
               public void onOpen(ServerHandshake arg0) {
                   // TODO Auto-generated method stub
               }
   
           };
   
           webSocketClient.connect();
           System.in.read();
       }
   }
   
   

   This code creates a WebSocket connection that is connected to a hub in Azure Web PubSub. A hub is a logical unit in Azure Web PubSub where you can publish messages to a group of clients. Key concepts contains the detailed explanation about the terms used in Azure Web PubSub.

   The Web PubSub service uses JSON Web Token (JWT) authentication. The sample code uses WebPubSubServiceClient.GetClientAccessUri() in Web PubSub SDK to generate a URL to the service that contains the full URL with a valid access token.

   After connection is established, your client will receive messages through the WebSocket connection. Use onMessage(String message) to listen for incoming messages.

Run the app with following command

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

Create a new project directory named publisher and install required dependencies

mkdir publisher
cd publisher

npm init

# This command installs the server SDK from NPM, 
# which is different from the client SDK you used in subscribe.js
npm install --save @azure/web-pubsub

Create a publish.js file with the following code

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

// This is the hub name we used on Azure portal when generating the Client Access URL. 
// It ensures this server can push messages to clients in the hub named "myHub1".
const hub = "myHub1";

let server = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);

// By default, the content type is `application/json`. 
// Specify contentType as `text/plain` for this demo.
server.sendToAll(process.argv[2], { contentType: "text/plain" });

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

Get the connection string

For this quickstart guide, we'll get it from Azure portal as shown below.

Run the server program

Run the following commands in a new command shell.

# Set the environment variable for your connection string.
export WebPubSubConnectionString="<Put your connection string here>" 

node publish.js "Hello World"

Observe the received messages on the client side

Try running the same "subscribe" program in multiple command shells to stimulate more than clients. As soon as the "publish" program is run, you should see messages being delivered in real-time to all these clients.

Create a project directory named publisher and install required dependencies:

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

Replace 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];

            // Either generate the token or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            await serviceClient.SendToAllAsync(message);
        }
    }
}

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

Run the server program to push messages to all connected clients

$connection_string="<connection-string>"
dotnet run $connection_string "myHub1" "Hello World"

Observe the received messages on the client side

# On the command shell used for running the "subscribe" program, you should see the received the messaged logged there. 
# Try running the same "subscribe" program in multiple command shells, which simluates more than clients. 
# Try running the "publish" program several times and you see messages being delivered in real-time to all these clients.   
Message received: Hello World

1. First, create a project directory named publisher 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
   
   

2. Use the 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 send_to_all() send the message to all connected clients in a hub.

3. Run the following command:

   python publish.py $connection_string "myHub1" "Hello World"
   

4. Check the previous command shell to that the subscriber received the message:

   Received message: Hello World
   

1. Go to the pubsub directory. Use Maven to create a publisher console app 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
   

2. Add the Azure Web PubSub SDK dependency into the dependencies node of pom.xml:

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

3. Use the Azure Web PubSub SDK to publish a message to the service. Go to the /src/main/java/com/webpubsub/quickstart directory, open the App.java file in your editor, and replace the contents 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);
       }
   }
   
   

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

4. Go to the webpubsub-quickstart-publisher directory and run the project using the following command:

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

5. You can see that the previous subscriber received the message:

   Message received: Hello World