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

Note

The client SDK is still in preview version. The interface may change in later versions.

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• 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.

JavaScript

Install Node.js

Node.js

C#

Install both the .NET Core SDK and dotnet runtime.

.NET Core

Install the package

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

JavaScript

The SDK is available as an npm module.

Open a terminal window and install the Web PubSub client SDK using the following command.

npm install @azure/web-pubsub-client

Note that the SDK is available as an npm module.

C#

Open a terminal window to create your project and install the Web PubSub client SDK.

# 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

Note that the SDK is available as a NuGet packet.

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.

JavaScript

In the terminal window, create a new directory for your project and change to that directory.

mkdir webpubsub-client
cd webpubsub-client

Create a file with name index.js and enter following code:

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);

C#

Edit the Program.cs file and add following code:

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.

JavaScript

Add this following code to the index.js file:

// 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");

C#

Add the following code to the Program.cs file:

// 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.

JavaScript

Add the following code to the index.js file:

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

C#

Add the following code to the Program.cs file:

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.

JavaScript

To start the client go the terminal and run the following command. Replace the <Client Access URL> with the client access URL you copied from the portal.

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

C#

To start the client, run the following command in your terminal replacing the <client-access-url> with the client access URL you copied from the portal:

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:

JavaScript

JavaScript SDK repository on GitHub

TypeScript sample

Browser sample

Chat app sample

C#

.NET SDK repository on GitHub

Log streaming sample