适用于 .NET 的 Azure Web PubSub 客户端库

客户端 SDK 旨在加快开发人员的工作流;更具体地说，

• 简化客户端连接的管理
• 简化在客户端之间发送消息
• 在客户端连接意外中断后自动重试
• 从连接中断恢复后，可靠地按照数量和顺序传递消息

如图所示，客户端与 Web PubSub 资源建立 WebSocket 连接。

入门

安装软件包

从 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。

如图所示，客户端有权将消息发送到特定组并加入特定组。 详细了解客户端权限，请参阅 权限。

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

使用协商服务器生成 Client Access URL

在生产环境中，客户端通常会从协商服务器中提取 Client Access URL 数据。 服务器保存 connection string 并生成 Client Access URL 通过 WebPubSubServiceClient。 作为示例，代码片段只是演示如何生成 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的功能。

示例

从服务器和群组消费消息

客户端可以添加回调以使用来自服务器和组的消息。 请注意，客户端只能接收其已加入的群组消息。

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后。 如果要重启客户端，您可以在client.StartAsync()事件中调用Stopped。

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 资源检查实时消息流量。