共用方式為

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

備註

關於此處所用術語的細節，請參閱 關鍵概念 條目。

用戶端 SDK 旨在加速開發者的工作流程;更具體地說，

  • 簡化客戶連線管理
  • 簡化用戶端間的訊息傳送
  • 用戶端連線意外中斷後，自動重試
  • 在從連線中斷恢復後，可靠地依數量與順序傳送訊息

如圖所示，您的客戶端與您的 Web PubSub 資源建立了 WebSocket 連線。 截圖顯示客戶端與 Web PubSub 資源建立 WebSocket 連線

入門指南

安裝套件

安裝 NuGet 的用戶端函式庫：

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

先決條件

  • Azure 訂用帳戶
  • 一個現有的網頁 PubSub 實例

驗證用戶端

用戶端使用 a Client Access URL 來連接並驗證服務。 Client Access URL 遵循 的模式為 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。 有多種方法可以取得 Client Access URL。 作為快速開始，你可以從 Azure portal 複製貼上，而在生產環境中通常需要一個協商伺服器來產生 Client Access URL。 詳情請參閱。

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

作為快速開始，你可以到 Azure 入口網站，在 Keys 面板中複製 Client Access URL。

展示如何在 Azure 入口網站取得客戶端存取網址的截圖

如圖所示，客戶端被授權向特定群組發送訊息並加入特定群組。 想了解更多關於客戶權限的資訊，請參見 權限。

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
Features 用於用戶端。 發佈訊息並訂閱訊息。 伺服器端使用。 產生用戶端存取 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/記錄器套件檔。

即時追蹤

使用 Azure 入口網站的 即時追蹤工具 ，透過你的 Web PubSub 資源檢查即時訊息流量。

  • Last updated on