Skip to content

Commit 0b9dbc5

Browse files
cebundycebundy
committed
Review client SDK quickstart
1 parent a23a6cd commit 0b9dbc5

File tree

1 file changed

+93
-32
lines changed

1 file changed

+93
-32
lines changed

‎articles/azure-web-pubsub/quickstart-use-client-sdk.md

Lines changed: 93 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,48 @@ Get started with the Azure Web PubSub client SDK for Python or JavaScript to cre
2929
3030
## Prerequisites
3131

32-
- An Azure subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)
32+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
3333
- A Web PubSub instance. If you haven't created one, you can follow the guidance: [Create a Web PubSub instance from Azure portal](./howto-develop-create-instance.md)
3434
- A file editor such as Visual Studio Code.
3535

36-
Install the dependencies for the language you're using:
36+
## Setting up
37+
38+
### Create an Azure Web PubSub service instance
39+
40+
1. In the Azure portal and from **Home**, select **Create a resource**.
41+
1. In the **Search the Marketplace** box, enter *Web PubSub*.
42+
1. Select **Web PubSub** from the results.
43+
1. Select **Create**.
44+
1. Create a new resource group
45+
1. Select **Create new**.
46+
1. Enter the name and select **OK**.
47+
1. Enter a **Resource Name** for the service instance.
48+
1. Select **Pricing tier**. You can choose **Free** for testing.
49+
1. Select **Create**, then **Create** again to confirm the new service instance.
50+
1. Select **Go to resource** to go to the service instance when the deployment is complete.
51+
52+
### Generate the client URL
53+
54+
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>`.
55+
56+
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.
57+
58+
1. In the Azure portal, go to your Web PubSub service resource page.
59+
1. Select **Keys** from the menu.
60+
1. In the **Client URL Generator** section:
61+
1. Select **Send To Groups**
62+
1. Select **Allow Sending To Specific Groups**.
63+
1. Enter *group1* in the **Group Name** field and select **Add**.
64+
1. Select **Join/Leave Groups**.
65+
1. Select **Allow Joining/Leaving Specific Groups**.
66+
1. Enter *group1* in the **Group Name** field and select **Add**.
67+
1. Copy and save the **Client Access URL** for use later in this article.
68+
69+
:::image type="content" source="media/howto-websocket-connect/generate-client-url.png" alt-text="Screenshot of the Web PubSub Client URL Generator.":::
70+
71+
### Install programming language
72+
73+
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.
3774

3875
# [JavaScript](#tab/javascript)
3976

@@ -49,7 +86,7 @@ Install both the .NET Core SDK and dotnet runtime.
4986

5087
---
5188

52-
## Add the Web PubSub client SDK
89+
### Install the package
5390

5491
# [JavaScript](#tab/javascript)
5592

@@ -73,34 +110,25 @@ dotnet add package Azure.Messaging.WebPubSub.Client --prerelease
73110

74111
---
75112

76-
## Connect to Web PubSub
77-
78-
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>`.
113+
## Code examples
79114

80-
1. In the Azure portal, go to your Web PubSub service resource page.
81-
1. Select **Keys** from the menu.
82-
1. In the **Client URL Generator** section:
83-
1. Select **Send To Groups**
84-
1. Select **Allow Sending To Specific Groups**.
85-
1. Enter *group1* in the **Group Name** field and select **Add**.
86-
1. Select **Join/Leave Groups**.
87-
1. Select **Allow Joining/Leaving Specific Groups**.
88-
1. Enter *group1* in the **Group Name** field and select **Add**.
89-
1. Copy the **Client Access URL**.
115+
From your terminal window, create a new directory and navigate to it.
90116

91-
:::image type="content" source="media/howto-websocket-connect/generate-client-url.png" alt-text="Screenshot of the Web PubSub Client URL Generator.":::
117+
### Create and connect to the Web PubSub service
92118

93-
As shown above, the client has the permissions to send messages to and join a specific group named `group1`.
119+
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 in your code.
94120

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

96123
# [JavaScript](#tab/javascript)
97124

98-
Add a file with name `index.js` and add following code:
125+
Create a file with name `index.js` and enter following code:
99126

100127
```javascript
101128
const { WebPubSubClient } = require("@azure/web-pubsub-client");
102-
// Instantiates the client object. <client-access-url> is copied from Azure portal mentioned above.
103-
const client = new WebPubSubClient("<client-access-url>");
129+
// Instantiates the client object. env.process.env.WebPubSubClientURL
130+
// env.process.env.WebPubSubClientURL is the Client Access URL from Azure portal
131+
const client = new WebPubSubClient(env.process.env.WebPubSubClientURL);
104132
```
105133

106134
# [C#](#tab/csharp)
@@ -109,8 +137,10 @@ Edit the `Program.cs` file and add following code:
109137

110138
```csharp
111139
using Azure.Messaging.WebPubSub.Clients;
112-
// Instantiates the client object. <client-access-uri> is copied from Azure portal mentioned above.
113-
var client = new WebPubSubClient(new Uri("<client-access-uri>"));
140+
// Client Access URL from Azure portal
141+
var clientURL = args[0]; \
142+
// Instantiates the client object.
143+
var client = new WebPubSubClient(new Uri(clientURL));
114144
```
115145

116146
---
@@ -121,6 +151,8 @@ To receive message from a group, you need to subscribe to the group and add a ca
121151

122152
# [JavaScript](#tab/javascript)
123153

154+
Add this code to the `index.js` file:
155+
124156
```javascript
125157
// callback to group messages.
126158
client.on("group-message", (e) => {
@@ -136,6 +168,8 @@ client.joinGroup("group1");
136168

137169
# [C#](#tab/csharp)
138170

171+
Add this code to the `Program.cs` file:
172+
139173
```csharp
140174
// callback to group messages.
141175
client.GroupMessageReceived += eventArgs =>
@@ -158,19 +192,54 @@ Then you can send messages to the group and as the client has joined the group b
158192

159193
# [JavaScript](#tab/javascript)
160194

195+
Add this code to the `index.js` file:
196+
161197
```javascript
162198
client.sendToGroup("group1", "Hello World", "text");
163199
```
164200

165201
# [C#](#tab/csharp)
166202

203+
Add this code to the `Program.cs` file:
204+
167205
```csharp
168206
await client.SendToGroupAsync("group1", BinaryData.FromString("Hello World"), WebPubSubDataType.Text);
169207
```
170208

171209
---
172210

173-
## Repository and Samples
211+
## Run the code
212+
213+
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 see the message you sent in the first terminal window.
214+
215+
# [JavaScript](#tab/javascript)
216+
217+
Add this code to the `index.js` file:
218+
219+
```bash
220+
export WebPubSubClientURL="<Client Access URL>"
221+
node index.js
222+
```
223+
224+
# [C#](#tab/csharp)
225+
226+
Copy the Client Access URL from the portal and run the following command in your terminal replacing the `<client-access-url>` with the Client Access URL you copied from the portal:
227+
228+
```bash
229+
dotnet run <client-access-url>
230+
```
231+
232+
---
233+
234+
## Clean up resources
235+
236+
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**.
237+
238+
## Next steps
239+
240+
This quickstart provides you with a basic idea of how to connect to the Web PubSub with client SDK and how to subscribe to group messages and publish messages to groups.
241+
242+
To learn more the Web PubSub service SDKs, see the following resources:
174243

175244
# [JavaScript](#tab/javascript)
176245

@@ -187,11 +256,3 @@ await client.SendToGroupAsync("group1", BinaryData.FromString("Hello World"), We
187256
[.NET SDK repository on GitHub](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/webpubsub/Azure.Messaging.WebPubSub.Client)
188257

189258
[Log streaming sample](https://github.com/Azure/azure-webpubsub/tree/main/samples/csharp/logstream/sdk)
190-
191-
---
192-
193-
## Next steps
194-
195-
This quickstart provides you with a basic idea of how to connect to the Web PubSub with client SDK and how to subscribe to group messages and publish messages to groups.
196-
197-
[!INCLUDE [next step](includes/include-next-step.md)]

0 commit comments

Comments
 (0)