Azure.Messaging.WebPubSub.Client 1.0.0

Azure Web PubSub 客户端库 for .NET

Web PubSub 是一个 Azure 管理服务，帮助开发者轻松构建具有实时功能和发布/订阅模式的 Web 应用程序。任何需要服务器和客户端之间或客户端之间实时发布/订阅消息的场景都可以使用 Web PubSub。对于通常需要从服务器轮询或提交 HTTP 请求的传统实时功能，也可以使用 Web PubSub。

您可以在客户端使用此库来管理 WebSocket 客户端连接，如下面的示意图所示

使用此库的用途

• 向组发送消息
• 将事件发送到 服务器
• 加入和离开组
• 监听来自组和服务器的信息

此处所用术语的详细信息请参阅 关键概念 部分。

入门指南

安装包

从 NuGet 安装客户端库

dotnet add package Azure.Messaging.WebPubSub.Client

先决条件

• 一个Azure 订阅。
• 现有的 Web PubSub 实例。创建 Web PubSub 实例

验证客户端

客户端使用客户端访问 URL 连接并验证与服务。Uri 遵循以下模式：wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。有多种方法获取客户端访问 URL。作为快速入门，您可以从 Azure Portal 复制并粘贴，对于生产环境，通常需要一个协商服务器来生成 Uri。

从 Azure Portal 使用客户端访问 URL

作为快速入门，您可以访问 Portal 并从 密钥 选项卡中复制 客户端访问 URL。

如图所示，客户端将获得向特定组发送消息和加入特定组的权限。了解更多关于客户端权限的信息，请参阅权限

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

使用协商服务器生成客户端访问 URL

在生产环境中，客户端通常从一个协商服务器获取客户端访问 URL。服务器持有连接字符串并通过 WebPubSubServiceClient 生成客户端访问 URL。以下代码示例仅演示如何在单个进程内生成客户端访问 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 的功能。

有关更多信息，请参阅Azure.Messaging.WebPubSub

关键概念

连接

一个连接，也称为客户端连接，代表一个连接到 Web PubSub 的 WebSocket 连接。当成功连接时，Web PubSub 给该连接分配一个唯一的连接 ID。每个 WebPubSubClient 创建其自己的专用连接。

恢复

如果使用可靠协议的客户端断开连接，则会尝试使用丢失连接的连接 ID 建立新的 WebSocket。如果新 WebSocket 连接成功连接，则恢复连接。在整个客户端断开连接期间，服务保留客户端的上下文以及客户端所订阅的所有消息，当客户端恢复时，服务将发送这些消息到客户端。如果服务返回 WebSocket 错误代码 1008 或恢复尝试持续超过 30 秒，则恢复失败。

重新连接

重新连接发生在客户端连接掉线且无法恢复的情况下。重新连接启动一个新的连接，新的连接有一个新的连接 ID。与恢复不同，服务将已重新连接的客户端视为新客户端连接。客户端连接需要重新加入组。默认情况下，客户端库在重新连接后会重新加入组。

Hub

Hub 是一种逻辑概念，表示客户端连接的集合。通常，您使用一个 Hub 来完成一个目的：例如，聊天 Hub 或通知 Hub。当客户端连接创建时，它会连接到 Hub，在其生命周期内，它与该 Hub 相绑定。不同的应用程序可以使用不同的 hub 名称共享一个 Web PubSub。

组

组是 Hub 连接的子集。您可以在任何时候向组添加或从组删除连接。例如，聊天室可以被认为是一个组。当客户端加入和离开房间时，它们被添加和从组中删除。一个连接可以属于多个组，一个组可以包含多个连接。

用户

Web PubSub 的连接可以属于一个用户。一个用户可能有多个连接，例如当单个用户在多个设备或浏览器标签页上连接时。

客户端生命周期

每个 Web PubSub 客户端都可以安全地缓存并在整个应用程序生命周期中使用单个实例。注册的事件回调与客户端共享相同的生命周期。这意味着您可以在任何时候添加或删除回调，并且在重新连接或停止客户端后，注册状态不会改变。

示例

指定子协议

您可以指定客户端使用的子协议。默认情况下，客户端使用 json.reliable.webpubsub.azure.v1。您可以选择使用 json.reliable.webpubsub.azure.v1 或 json.webpubsub.azure.v1，如下所示。

var client = new WebPubSubClient(new Uri("<client-access-uri>"), new WebPubSubClientOptions
{
    Protocol = new WebPubSubJsonProtocol()
});

var client = new WebPubSubClient(new Uri("<client-access-uri>"), new WebPubSubClientOptions
{
    Protocol = new WebPubSubJsonReliableProtocol()
});

从服务器和组中消费消息

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

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);
    }
}

故障排除

设置控制台日志

如果您想深入了解您对服务发出的请求，还可以 启用控制台日志。

下一步操作

您还可以在这里找到更多示例 链接。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意《贡献者许可协议》（CLA），声明您有权利并且确实授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.microsoft.com。

提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA，并且将适当装饰 PR（例如，标签，评论）。只需遵循 bot 提供的说明即可。您只需要在整个使用我们的 CLA 的所有存储库中这样做一次。

本项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或通过 [email protected] 联系我们，以获取任何其他问题或评论。