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 free account.
  • a Bash and PowerShell command shell. The Python, JavaScript and Java samples require a Bash command shell.
  • A file editor such as VSCode.
  • 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. If you're using Cloud Shell, it isn't necessary to sign in.

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.

RESOURCE_GROUP="webpubsub-resource-group"
LOCATION="EastUS"
WEB_PUBSUB_NAME="<your-unique-name>"

Create a resource group for the Web PubSub project.

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

2. Deploy a Web PubSub service instance

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

az webpubsub create \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --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.

az webpubsub key show --name $WEB_PUBSUB_NAME --resource-group $RESOURCE_GROUP --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.

az webpubsub client start \
  --name $WEB_PUBSUB_NAME \
  --resource-group $RESOURCE_GROUP \
  --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

  1. Open a new command shell for this project.

  2. Save the connection string from the client shell. Replace the <your_connection_string> placeholder with the connection string you displayed in an earlier step.

    connection_string="<your_connection_string>"
    
  3. Now, select the language for your project.

  1. 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
    
  2. 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.

  3. Run the following command to publish a message to the service.

    dotnet run $connection_string "myHub1" "Hello World"
    
  4. 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.

az group delete --name $RESOURCE_GROUP --yes