Quickstart: Publish messages using the service SDK for the Azure Web PubSub instance

This quickstart shows you how to publish messages to the clients using service SDK.

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

Prerequisites

  • This quickstart requires version 2.22.0 or higher of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Create a resource group

A resource group is a logical container into which Azure resources are deployed and managed. Use the az group create command to create a resource group named myResourceGroup in the eastus location.

az group create --name "myResourceGroup" -l "EastUS"

Create a Web PubSub instance

Use the Azure CLI az webpubsub create command to create a Web PubSub in the resource group from the previous step, providing the following information:

  • Resource name: A string of 3 to 24 characters that can contain only numbers (0-9), letters (a-z, A-Z), and hyphens (-)

    Important

    Each Web PubSub resource must have a unique name. Replace <your-unique-resource-name> with the name of your Web PubSub in the following examples.

  • Resource group name: myResourceGroup.

  • The location: EastUS.

  • Sku: Free_F1

az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1

The output of this command shows properties of the newly created resource. Take note of the two properties listed below:

  • Resource Name: The name you provided to the --name parameter above.
  • hostName: In the example, the host name is <your-unique-resource-name>.webpubsub.azure.com/.

At this point, your Azure account is the only one authorized to perform any operations on this new resource.

Get the ConnectionString for future use

Important

A connection string includes the authorization information required for your application to access Azure Web PubSub service. The access key inside the connection string is similar to a root password for your service. Please always be careful to protect your access keys. Use Azure Key Vault to manage and rotate your keys securely. Avoid distributing access keys to other users, hard-coding them, or saving them anywhere in plain text that is accessible to others. Rotate your keys if you believe they may have been compromised.

Use the Azure CLI az webpubsub key command to get the ConnectionString of the service.

az webpubsub key show --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --query primaryConnectionString

Copy the fetched ConnectionString and it will be used later when using service SDK as the value of <connection_string>.

Connect to the instance

Use the Azure CLI az webpubsub client command to start a WebSocket client connection to the service created from the previous step, providing the following information:

  • Hub name: A string of 1 to 127 characters. It should start with alphabetic characters (a-z, A-Z) and only contain alpha-numeric (0-9, a-z, A-Z) characters or underscore (_).

Hub is a logical set of the connected WebSocket connections. Check About Hubs, groups and connections for details about the concepts.

Important

Replace <your-unique-resource-name> with the name of your Web PubSub resource created from the previous steps.

  • Hub name: myHub1.
  • Resource group name: myResourceGroup.
  • User ID: user1
az webpubsub client start --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --hub-name "myHub1" --user-id "user1"

You can see that the command established a WebSocket connection to the Web PubSub service and you received a JSON message indicating that it is now successfully connected, and is assigned with a unique connectionId:

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

Publish messages using service SDK

Now let's use Azure Web PubSub SDK to publish a message to the connected client.

Prerequisites

Set up the project to publish messages

  1. Add a new project publisher and add the SDK package 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 and send messages to the clients.

    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 below command, replacing <connection_string> with the ConnectionString fetched in previous step:

    dotnet run "<connection_string>" "myHub1" "Hello World"
    
  4. You can see that the previous CLI client received the message.

    {"type":"message","from":"server","dataType":"text","data":"Hello World"}
    

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.

Follow the tutorials listed below to start building your own application.