適用於 .NET 的 Azure Web PubSub 用戶端程式庫

發行項
2024-04-09

注意

此處所用詞彙的詳細資料詳述於《重要概念》一文。

用戶端 SDK 旨在加速開發人員的工作流程; 更具體地來說，是要

簡化用戶端連線的管理
簡化用戶端之間的訊息傳送
在用戶端連線意外卸除之後的自動重試
在從連線卸除復原後，可靠地以數字和有序地傳遞訊息

如下圖所示，您的用戶端會使用 Web PubSub 資源建立 WebSocket 連線。 Screenshot showing clients establishing WebSocket connection with a Web PubSub resource

開始使用

Install the package

從 NuGet 安裝用戶端程式庫：

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

必要條件

Azure 訂閱
現有的 Web PubSub 執行個體

驗證用戶端

用戶端會使用 Client Access URL 來連線及驗證服務。 Client Access URL 遵循模式 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。取得 Client Access URL 的方法有好幾種。若要快速開始，您可以從 Azure 入口網站複製並貼上，而針對生產環境，您通常需要交涉伺服器來產生 Client Access URL。查看詳細資料。

從 Azure 入口網站使用用戶端存取 URL

若要快速開始，您可以前往 Azure 入口網站，並從 [金鑰] 刀鋒視窗複製 [用戶端存取 URL]。

Screenshot showing how to get Client Access Url on Azure portal

如圖所示，用戶端已獲授與將訊息傳送至特定群組並加入特定群組的許可權。深入了解用戶端權限，請參閱權限。

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

使用交涉伺服器產生 `Client Access URL`

在生產環境中，用戶端通常會從交涉伺服器擷取 Client Access URL。伺服器會保存 connection string，並透過 WebPubSubServiceClient 產生 Client Access URL。作為範例，程式碼片段只是示範如何在單一流程內產生 Client Access URL。

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

區分 WebPubSubClient 和 WebPubSubServiceClient 的功能。

類別名稱	WebPubSubClient	WebPubSubServiceClient
NuGet 套件名稱	Azure.Messaging.WebPubSub.Client	Azure.Messaging.WebPubSub
功能	用於用戶端。發佈訊息並訂閱訊息。	用於伺服器端。產生用戶端存取 URI 並管理用戶端

範例

從伺服器和群組取用訊息

用戶端可以新增回撥，以取用來自伺服器和群組的訊息。請注意，用戶端只能接收已加入的群組訊息。

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

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

新增 `connected`、`disconnected` 和 `stopped` 事件的回撥

當用戶端連線至服務時，一旦收到來自服務的已連線訊息，就會觸發 connected 事件。

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

當用戶端連線中斷連線且無法復原時，就會觸發 disconnected 事件。

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

當用戶端停止時，表示用戶端連線已中斷連線，而用戶端會停止嘗試重新連線，則會觸發 stopped 事件。這通常是在呼叫 client.StopAsync() 或停用 AutoReconnect 之後發生。如果您想要重新啟動用戶端，您可以在 Stopped 事件中呼叫 client.StartAsync()。

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

自動重新加入群組並處理重新加入失敗

當用戶端連線已卸除且無法復原時，服務端會清除所有群組內容。這表示當用戶端重新連線時，它必須重新加入群組。根據預設，用戶端已啟用 AutoRejoinGroups 選項。不過，這個方法有一些限制。用戶端只能重新加入原本由用戶端加入的群組，而不是由伺服器端加入。而重新加入群組作業可能會因為各種原因而失敗，例如，客戶端沒有加入群組的權限。在這種情況下，使用者必須新增回撥來處理這類失敗。

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

作業和重試

根據預設，client.JoinGroupAsync()、client.LeaveGroupAsync()、client.SendToGroupAsync()、client.SendEventAsync() 等作業有三個重試。您可以使用 WebPubSubClientOptions.MessageRetryOptions 來變更。如果所有重試都失敗，則會擲回錯誤。您可以繼續重試，方法是傳入與先前的重試相同的 ackId，因此服務可協助以相同的 ackId 重複資料刪除作業。

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

疑難排解

啟用記錄

使用此程式庫時，您可以設定下列環境變數來取得偵錯記錄。

export AZURE_LOG_LEVEL=verbose

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

即時追蹤

從 Azure 入口網站使用 Live Trace 工具，透過 Web PubSub 資源檢查即時訊息流量。

共用方式為