[WebPubSub] Update the README of WebPubSubClient (#33267)

# Contributing to the Azure SDK

Please see our [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md) if you are not familiar with contributing to this repository or have questions.

For specific information about pull request etiquette and best practices, see [this section](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md#pull-request-etiquette-and-best-practices).

Author: zackliu

sdk/webpubsub/Azure.Messaging.WebPubSub.Client/README.md

@@ -1,10 +1,10 @@
 # Azure Web PubSub client library for .NET
 
-[Azure Web PubSub Service](https://aka.ms/awps/doc) is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe pattern. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP requests can also use Azure Web PubSub service.
+[Azure Web PubSub Service](https://aka.ms/awps/doc) is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe patterns. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from the server or submitting HTTP requests can also use Azure Web PubSub service.
 
-You can use this library in your client side to manage the WebSocket client connections, as shown in below diagram:
+You can use this library on your client side to manage the WebSocket client connections, as shown in the below diagram:
 
-![overflow](https://user-images.githubusercontent.com/668244/140014067-25a00959-04dc-47e8-ac25-6957bd0a71ce.png)
+![overflow](./samples/media/overview.png)
 
 Use this library to:
 
@@ -36,13 +36,23 @@ dotnet add package Azure.Messaging.WebPubSub.Client
 
 ### Authenticate the client
 
-In order to interact with the service, you'll need to create an instance of the `WebPubSubClient` class. To make this possible, you'll need an access token. You can copy and paste an access token from Azure portal.
+A Client uses a Client Access URL to connect and authenticate with the service. The Uri follow the patten as `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`. There're multiple ways to get a Client Access URL. As a quick start, you can copy and paste from Azure Portal, and for production, you usually need a negotiation server to generate the Uri.
+
+#### Use Client Access URL from Azure Portal
+
+As a quick start, you can go to the Portal and copy the **Client Access URL** from **Key** blade.
+
+![get_client_url](https://learn.microsoft.com/azure/azure-web-pubsub/media/howto-websocket-connect/generate-client-url.png)
+
+As shown in the diagram, the client will be granted permission of sending messages to the specific group and joining the specific group. Learn more about client permission, see [permissions](https://learn.microsoft.com/azure/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol#permissions)
 
 ```C# Snippet:WebPubSubClient_Construct
 var client = new WebPubSubClient(new Uri("<client-access-uri>"));
 ```
 
-And in production, you usually get `ClientAccessUri` from a negotiate server.
+#### Use negotiation server to generate Client Access URL
+
+In production, a client usually fetches the Client Access URL from a negotiation server. The server holds the connection string and generates the Client Access URL through `WebPubSubServiceClient`. As a sample, the code snippet below just demonstrates how to generate the Client Access URL inside a single process.
 
 ```C# Snippet:WebPubSubClient_Construct2
 var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
@@ -52,13 +62,23 @@ var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
 }));
 ```
 
-The `FetchClientAccessTokenFromServerAsync` usually fetch the token from server via Http request. And in the server side, you can use `WebPubSubServiceClient` to generate token and response to the fetch request.
-
 ```C# Snippet:WebPubSubClient_GenerateClientAccessUri
-var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
-return await serviceClient.GetClientAccessUriAsync();
+public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
+{
+    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
+    return await serviceClient.GetClientAccessUriAsync();
+}
 ```
 
+Features to differentiate `WebPubSubClient` and `WebPubSubServiceClient`.
+
+|Class Name|WebPubSubClient|WebPubSubServiceClient|
+|------|---------|---------|
+|Nuget Package Name|Azure.Messaging.WebPubSub.Client |Azure.Messaging.WebPubSub|
+|Features|Usually used on client side. Publish messages and subscribe to messages.|Usually used on server side. Generate Client Access Uri and manage clients|
+
+Find more details in [Azure.Messaging.WebPubSub](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/webpubsub/Azure.Messaging.WebPubSub)
+
 ## Key concepts
 
 ### Connection
@@ -67,11 +87,15 @@ A connection, also known as a client connection, represents an individual WebSoc
 
 ### Recovery
 
-If using reliable protocols, a new WebSocket will try to reconnect using the connection ID of the lost connection. If the WebSocket connection is successfully connected, the connection is recovered. And all group contexts will be recovered, and unreceived messages will be resent.
+If a client using reliable protocols disconnects, a new WebSocket tries to establish using the connection ID of the lost connection. If the new WebSocket connection is successfully connected, the connection is recovered. Throughout the time a client is disconnected, the service retains the client's context as well as all messages that the client was subscribed to, and when the client recovers, the service will send these messages to the client. If the service returns WebSocket error code `1008` or the recovery attempt lasts more than 30 seconds, the recovery fails.
+
+### Reconnect
+
+Reconnection happens when the client connection drops and fails to recover. Reconnection starts a new connection and the new connection has a new connection ID. Unlike recovery, the service treats the reconnected client as a new client connection. The client connection needs to rejoin groups. By default, the client library rejoins groups after reconnection.
 
 ### Hub
 
-A hub is a logical concept representing a collection of client connections. Usually, you use one hub for one purpose: for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub and, and during its lifetime, it is bound to that hub. Different applications can share one Azure Web PubSub service by using different hub names.
+A hub is a logical concept representing a collection of client connections. Usually, you use one hub for one purpose: for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub, and during its lifetime, it is bound to that hub. Different applications can share one Azure Web PubSub service by using different hub names.
 
 ### Group
 
@@ -81,29 +105,53 @@ A group is a subset of connections to the hub. You can add and remove connection
 
 Connections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or browser tabs.
 
-### Message
+## Client Lifetime
 
-When a client is connected, it can send messages to the upstream application, or receive messages from the upstream application, through the WebSocket connection. Also, it can send messages to groups and receive message from joined groups.
+Each of the Web PubSub clients is safe to cache and use as a singleton for the lifetime of the application. The registered event callbacks share the same lifetime with the client. This means you can add or remove callbacks at any time and the registration status won't change after reconnection or even stopping the client.
 
 ## Examples
 
-### Send to groups
+### Specify subprotocol
 
-```C# Snippet:WebPubSubClient_SendToGroup
-// Send message to group "testGroup"
-await client.SendToGroupAsync("testGroup", BinaryData.FromString("hello world"), WebPubSubDataType.Text);
+You can specify the subprotocol to be used by the client. By default, the client uses `json.reliable.webpubsub.azure.v1`. You can choose to use `json.reliable.webpubsub.azure.v1` or `json.webpubsub.azure.v1` as shown below.
+
+```C# Snippet:WebPubSubClient_JsonProtocol
+var client = new WebPubSubClient(new Uri("<client-access-uri>"), new WebPubSubClientOptions
+{
+    Protocol = new WebPubSubJsonProtocol()
+});
+```
+
+```C# Snippet:WebPubSubClient_JsonReliableProtocol
+var client = new WebPubSubClient(new Uri("<client-access-uri>"), new WebPubSubClientOptions
+{
+    Protocol = new WebPubSubJsonReliableProtocol()
+});
 ```
 
-### Send events to event handler
+### Consume messages from the server and groups
+
+A client can add callbacks to consume messages from the server and groups. Please note, clients can only receive group messages that it has joined.
+
+```C# Snippet:WebPubSubClient_Subscribe_ServerMessage
+client.ServerMessageReceived += eventArgs =>
+{
+    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
+    return Task.CompletedTask;
+};
+```
 
-```C# Snippet:WebPubSubClient_SendEvent
-// Send custom event to server
-await client.SendEventAsync("testEvent", BinaryData.FromString("hello world"), WebPubSubDataType.Text);
+```C# Snippet:WebPubSubClient_Subscribe_GroupMessage
+client.GroupMessageReceived += eventArgs =>
+{
+    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
+    return Task.CompletedTask;
+};
 ```
 
-### Handle the Connected event
+### Add callbacks for connected, disconnected, and stopped events
 
-The `Connected` event is called after the client receives connected message. The event will be triggered every reconnection.
+When a client connection is connected to the service, the `Connected` event is triggered once it received the connected message from the service.
 
 ```C# Snippet:WebPubSubClient_Subscribe_Connected
 client.Connected += eventArgs =>
@@ -113,9 +161,7 @@ client.Connected += eventArgs =>
 };
 ```
 
-### Handle the Disconnected event
-
-The `Disconnected` event is triggered every time the connection closed and could not be recovered
+When a client connection is disconnected and fails to recover, the `Disconnected` event is triggered.
 
 ```C# Snippet:WebPubSubClient_Subscribe_Disconnected
 client.Disconnected += eventArgs =>
@@ -125,9 +171,7 @@ client.Disconnected += eventArgs =>
 };
 ```
 
-### Handle the Stopped event
-
-The `Stopped` event is triggered when the client is stopped. The client won't try to reconnect after being stopped. This event is typically the result of calling `StopAsync` or disabling the `AutoReconnect`
+When a client is stopped, which means the client connection is disconnected and the client stops trying to reconnect, the `Stopped` event will be triggered. This usually happens after the `client.StopAsync()` is called, or disabled `AutoReconnect`. If you want to restart the client, you can call `client.StartAsync()` in the `Stopped` event.
 
 ```C# Snippet:WebPubSubClient_Subscribe_Stopped
 client.Stopped += eventArgs =>
@@ -137,40 +181,35 @@ client.Stopped += eventArgs =>
 };
 ```
 
-### Handle the Server message event
+### Auto rejoin groups and handle rejoin failure
 
-The `ServerMessageReceived` event is triggered when there's a message from server.
+When a client connection has dropped and fails to recover, all group contexts will be cleaned up on the service side. That means when the client reconnects, it needs to rejoin groups. By default, the client enabled `AutoRejoinGroups` options. However, this feature has limitations. The client can only rejoin groups that it's originally joined by the client rather than joined by the server side. And rejoin group operations may fail due to various reasons, e.g. the client doesn't have permission to join groups. In such cases, users need to add a callback to handle the failure.
 
-```C# Snippet:WebPubSubClient_Subscribe_ServerMessage
-client.ServerMessageReceived += eventArgs =>
+```C# Snippet:WebPubSubClient_Subscribe_RestoreFailed
+client.RejoinGroupFailed += eventArgs =>
 {
-    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
+    Console.WriteLine($"Restore group failed");
     return Task.CompletedTask;
 };
 ```
 
-### Handle the Group message event
+### Operation and retry
 
-The `GroupMessageReceived` event is triggered when there's a message from a group. You must join a group before you can receive messages from it.
+By default, the operation such as `client.JoinGroupAsync()`, `client.LeaveGroupAsync()`, `client.SendToGroupAsync()`, `client.SendEventAsync()` has three reties. You can use `WebPubSubClientOptions.MessageRetryOptions` to change. If all retries have failed, an error will be thrown. You can keep retrying by passing in the same `ackId` as previous retries, thus the service can help to deduplicate the operation with the same `ackId`
 
-```C# Snippet:WebPubSubClient_Subscribe_GroupMessage
-client.GroupMessageReceived += eventArgs =>
+```C# Snippet:WebPubSubClient_JoinGroupAndRetry
+// Send message to group "testGroup"
+try
 {
-    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
-    return Task.CompletedTask;
-};
-```
-
-### Handle the restore failure event
-
-The `RestoreGroupFailed` event is triggered when the `AutoRejoinGroups` is enabled and rejoining a group fails after reconnection.
-
-```C# Snippet:WebPubSubClient_Subscribe_RestoreFailed
-client.RejoinGroupFailed += eventArgs =>
+    await client.JoinGroupAsync("testGroup");
+}
+catch (SendMessageFailedException ex)
 {
-    Console.WriteLine($"Restore group failed");
-    return Task.CompletedTask;
-};
+    if (ex.AckId == null)
+    {
+        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
+    }
+}
 ```
 
 ## Troubleshooting

sdk/webpubsub/Azure.Messaging.WebPubSub.Client/samples/Sample1_HelloWorld.md

@@ -1,16 +1,26 @@
-# Create client, publish and subscribe group messages
+# Create clients, publish and subscribe to group messages
 
 This sample demonstrates the basic usage of Azure Web PubSub service, with the goal of quickly allowing you to publish to groups and subscribe to messages from groups. To accomplish this, the `WebPubSubClient` will be introduced, along with some of the core concepts of Azure Web PubSub service.
 
 ## Create the clients
 
-To interact with Azure WebPubSub service, a client is needed for each area of functionality. For each hub, a client must be created and copy and paste the `clientAcccessUri` from Azure Portal
+A Client uses a Client Access URL to connect and authenticate with the service. The Uri follow the patten as `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`. There're multiple ways to get a Client Access URL. As a quick start, you can copy and paste from Azure Portal, and for production, you usually need a negotiation server to generate the Uri.
+
+### Use Client Access URL from Azure Portal
+
+As a quick start, you can go to the Portal and copy the **Client Access URL** from **Key** blade.
+
+![get_client_url](https://learn.microsoft.com/azure/azure-web-pubsub/media/howto-websocket-connect/generate-client-url.png)
+
+As shown in the diagram, the client will be granted permission of sending messages to the specific group and joining the specific group. Learn more about client permission, see [permissions](https://learn.microsoft.com/azure/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol#permissions)
 
 ```C# Snippet:WebPubSubClient_Construct
 var client = new WebPubSubClient(new Uri("<client-access-uri>"));
 ```
 
-The `clientAcccessUri` also can be generated by `WebPubSubServiceClient`
+### Use negotiation server to generate Client Access URL
+
+In production, a client usually fetches the Client Access URL from a negotiation server. The server holds the connection string and generates the Client Access URL through `WebPubSubServiceClient`. As a sample, the code snippet below just demonstrates how to generate the Client Access URL inside a single process.
 
 ```C# Snippet:WebPubSubClient_Construct2
 var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
@@ -20,11 +30,19 @@ var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
 }));
 ```
 
-The client is responsible for making a connection to the service and efficiently publishing messages or subscribing messages from groups. By default, `WebPubSubClient` uses `json.reliable.webpubsub.azure.v1` subprotocol.
+```C# Snippet:WebPubSubClient_GenerateClientAccessUri
+public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
+{
+    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
+    return await serviceClient.GetClientAccessUriAsync();
+}
+```
+
+The client is responsible for making a connection to the service and efficiently publishing messages or subscribing to messages from groups. By default, `WebPubSubClient` uses `json.reliable.webpubsub.azure.v1` subprotocol.
 
 ## Subscribe to messages
 
-Messages can come from groups or from servers. The client can register an event handler to be notified of messages and system events. The event handler share the same lifetime with the client, so you can subscribe them before you start the client. If the client has a permission to join group, it can join group to subscribe messages from that group. But note joining group operation must be called after the client has been started.
+Messages can come from groups or from servers. The client can register a callback to be notified when messages have been received. The callbacks share the same lifetime with the client, so you can subscribe to them before you start the client. If the client has permission to join groups, it can join the group to subscribe to messages from that group. But note joining group operation must be called after the client has been started.
 
 ```C# Snippet:WebPubSubClient_Subscribe_ServerMessage
 client.ServerMessageReceived += eventArgs =>
@@ -42,9 +60,17 @@ client.GroupMessageReceived += eventArgs =>
 };
 ```
 
+## Start client
+
+After you call `client.StartAsync()`, the client starts to make connections to the service and be ready for sending messages.
+
+```csharp
+await client.StartAsync();
+```
+
 ## Publish messages to group or server
 
-To publish messages, a `WebPubSubClient` need to be created and started. The client can send event to server or send messages to groups.
+To publish messages, a `WebPubSubClient` need to be created and started. The client can send events to the server or send messages to groups.
 
 ```C# Snippet:WebPubSubClient_SendToGroup
 // Send message to group "testGroup"