Quickstart: Create a client using the Azure Web PubSub client SDK (preview)

Get started with the Azure Web PubSub client SDK for .NET or JavaScript to create a Web PubSub client that:

• connects to a Web PubSub service instance
• subscribes a Web PubSub group.
• publishes a message to the Web PubSub group.

API reference documentation | Library source code | Package (JavaScript npm) | Samples

API reference documentation | Library source code | Package (NuGet) | Samples

Prerequisites

• An Azure account with an active subscription. Create a trial subscription.
• A file editor such as Visual Studio Code.

Setting up

Create an Azure Web PubSub service instance

1. In the Azure portal Home page, select Create a resource.
2. In the Search the Marketplace box, enter Web PubSub.
3. Select Web PubSub from the results.
4. Select Create.
5. Create a new resource group
   1. Select Create new.
   2. Enter the name and select OK.
6. Enter a Resource Name for the service instance.
7. Select Pricing tier. You can choose Free for testing.
8. Select Create, then Create again to confirm the new service instance.
9. Once deployment is complete, select Go to resource.

Generate the client URL

A client uses a Client Access URL to connect and authenticate with the service, which follows a pattern of wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>.

To give the client permission to send messages to and join a specific group, you must generate a Client Access URL with the Send To Groups and Join/Leave Groups permissions.

1. In the Azure portal, go to your Web PubSub service resource page.
2. Select Keys from the menu.
3. In the Client URL Generator section:
   1. Select Send To Groups
   2. Select Allow Sending To Specific Groups.
   3. Enter group1 in the Group Name field and select Add.
   4. Select Join/Leave Groups.
   5. Select Allow Joining/Leaving Specific Groups.
   6. Enter group1 in the Group Name field and select Add.
   7. Copy and save the Client Access URL for use later in this article.

Install programming language

This quickstart uses the Azure Web PubSub client SDK for JavaScript or C#. Open a terminal window and install the dependencies for the language you're using.

Install the package

Install the Azure Web PubSub client SDK for the language you're using.

npm install @azure/web-pubsub-client

# create project directory
mkdir webpubsub-client

# change to the project directory
cd webpubsub-client

# Add a new .NET project
dotnet new console

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

Code examples

Create and connect to the Web PubSub service

This code example creates a Web PubSub client that connects to the Web PubSub service instance. A client uses a Client Access URL to connect and authenticate with the service. 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.

For this example, you can use the Client Access URL you generated in the portal.

mkdir webpubsub-client
cd webpubsub-client

const { WebPubSubClient } = require("@azure/web-pubsub-client");
// Instantiates the client object. env.process.env.WebPubSubClientURL 
// env.process.env.WebPubSubClientURL is the Client Access URL from Azure portal
const client = new WebPubSubClient(env.process.env.WebPubSubClientURL);

using Azure.Messaging.WebPubSub.Clients;
// Client Access URL from Azure portal
var clientURL = Environment.GetEnvironmentVariable("WebPubSubClientURL"));
// Instantiates the client object. 
var client = new WebPubSubClient(new Uri(clientURL));

Subscribe to a group

To receive message from a group, you need to subscribe to the group and add a callback to handle messages you receive from the group. The following code subscribes the client to a group called group1.

// callback to group messages.
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// before joining group, the client needs to start
client.start();

// join a group to subscribe message from the group
client.joinGroup("group1");

// callback to group messages.
client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

// before joining group, the client needs to start
await client.StartAsync();

// join a group to subscribe message from the group
await client.JoinGroupAsync("group1");

Publish a message to a group

After your client has subscribed to the group, it can send messages to and receive the message from the group.

client.sendToGroup("group1", "Hello World", "text");

await client.SendToGroupAsync("group1", BinaryData.FromString("Hello World"), WebPubSubDataType.Text);

Run the code

Run the client in your terminal. To verify the client is sending and receiving messages, you can open a second terminal and start the client from the same directory. You can see the message you sent from the second client in the first client's terminal window.

export WebPubSubClientURL="<Client Access URL>"
node index.js

export WebPubSubClientURL="<Client Access URL>"
dotnet run <client-access-url>

Clean up resources

To delete the resources you created in this quickstart, you can delete the resource group you created. Go to the Azure portal, select your resource group, and select Delete resource group.

Next steps

To learn more the Web PubSub service client SDKs, see the following resources: