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
Use the Bash environment in Azure Cloud Shell. For more information, see Azure Cloud Shell Quickstart - Bash.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you are running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.
When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
- 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
--nameparameter 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
Add a new project
publisherand add the SDK packagepackage Azure.Messaging.WebPubSub.mkdir publisher cd publisher dotnet new console dotnet add package Azure.Messaging.WebPubSubUpdate the
Program.csfile to use theWebPubSubServiceClientclass 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.Run the below command, replacing
<connection_string>with the ConnectionString fetched in previous step:dotnet run "<connection_string>" "myHub1" "Hello World"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.
