适用于 .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”。

如图所示，向客户端授予向特定组发送消息和加入特定组的权限。 请参阅权限，详细了解客户端权限。

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

在生产环境下，客户端通常从协商服务器提取 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 的功能。

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

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 事件。

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 门户的实时跟踪工具来检查通过 Web PubSub 资源的实时消息流量。