你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure Web PubSub 服务客户端库 - 版本 1.3.0

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

可以在应用服务器端使用此库来管理 WebSocket 客户端连接，如下图所示：

可以使用此库来执行以下操作：

• 将消息发送到中心和组。
• 将消息发送到特定用户和连接。
• 将用户和连接组织到组中。
• 关闭连接
• 授予、撤销、检查现有连接的权限

有关此处使用的术语的详细信息，请参阅主要概念部分。

源代码 | 包 | API 参考文档 | 产品文档 | 示例

入门

安装包

从 NuGet 安装客户端库：

dotnet add package Azure.Messaging.WebPubSub

先决条件

• 一个 Azure 订阅。
• 一个现有的 Azure Web PubSub 服务实例。

创建 WebPubSubServiceClient 并对其进行身份验证

为了与服务交互，需要创建 WebPubSubServiceClient 类的实例。 为了实现此目的，需要使用连接字符串或密钥，可在 Azure 门户中对其进行访问。

// Create a WebPubSubServiceClient that will authenticate using a key credential.
var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "some_hub", new AzureKeyCredential(key));

关键概念

连接

连接（也称为客户端或客户端连接）表示连接到 Web PubSub 服务的单个 WebSocket 连接。 成功连接后，Web PubSub 服务会向此连接分配唯一的连接 ID。

集线器

中心是客户端连接集的逻辑概念。 通常将一个中心用于一种用途，例如聊天中心或通知中心 。 创建客户端连接后，它会连接到某个中心，并且在其生存期内属于该中心。 不同的应用程序可以使用不同的中心名称共享一个 Azure Web PubSub 服务。

组

组是与中心的连接的子集。 可以随时向组添加客户端连接或者从组中删除客户端连接。 例如，当某个客户端加入聊天室，或某个客户端离开聊天室，此类聊天室可以看成是一个组。 一个客户端可以加入多个组，一个组可以包含多个客户端。

User

与 Web PubSub 的连接可以属于一个用户。 用户可能具有多个连接，例如当单个用户跨多个设备或多个浏览器选项卡进行连接时。

Message

连接客户端后，可以通过 WebSocket 连接将消息发送到上游应用程序或是从上游应用程序接收消息。

示例

生成包含访问令牌的完整 URI，供连接在连接 Azure Web PubSub 时使用

// Generate client access URI for userA
serviceClient.GetClientAccessUri(userId: "userA");
// Generate client access URI with initial permissions
serviceClient.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1", "webpubsub.sendToGroup.group1" });
// Generate client access URI with initial groups to join when the connection connects
serviceClient.GetClientAccessUri(groups: new string[] { "group1", "group2" });

将消息发送到连接

向所有客户端广播文本消息

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

serviceClient.SendToAll("Hello World!");

向所有客户端广播 JSON 消息

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

serviceClient.SendToAll(RequestContent.Create(
        new
        {
            Foo = "Hello World!",
            Bar = 42
        }),
        ContentType.ApplicationJson);

向所有客户端广播二进制消息

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

Stream stream = BinaryData.FromString("Hello World!").ToStream();
serviceClient.SendToAll(RequestContent.Create(stream), ContentType.ApplicationOctetStream);

使用筛选器将消息广播到客户端

Azure Web PubSub 支持 OData 筛选器语法来筛选出要向其发送消息的连接。

有关语法的详细信息 filter ，请参阅 Azure Web PubSub 的 OData 筛选器语法。

var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");

// Use filter to send text message to anonymous connections
serviceClient.SendToAll(
        RequestContent.Create("Hello World!"),
        ContentType.TextPlain,
        filter: ClientConnectionFilter.Create($"userId eq {null}"));

// Use filter to send JSON message to connections in groupA but not in groupB
var group1 = "GroupA";
var group2 = "GroupB";
serviceClient.SendToAll(RequestContent.Create(
        new
        {
            Foo = "Hello World!",
            Bar = 42
        }),
        ContentType.ApplicationJson,
        filter: ClientConnectionFilter.Create($"{group1} in groups and not({group2} in groups)"));

连接管理

将某些用户的连接添加到某个组：

client.AddUserToGroup("some_group", "some_user");

// Avoid sending messages to users who do not exist.
if (client.UserExists("some_user").Value)
{
    client.SendToUser("some_user", "Hi, I am glad you exist!");
}

client.RemoveUserFromGroup("some_group", "some_user");

删除所有组的连接

var client = new WebPubSubServiceClient(connectionString, "some_hub");
client.RemoveConnectionFromAllGroups("some_connection");

故障排除

设置控制台日志记录

如果想要更深入地了解针对服务发出的请求，还可以轻松启用控制台记录。

后续步骤

有关如何使用此库的详细示例，请查看 示例 目录。

还可以 在此处找到更多示例。

贡献

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

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。