Azure.Messaging.WebPubSub 1.4.0

Azure Web PubSub 服务 .NET 客户端库

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

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

使用此库

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

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

源代码 | 包 | 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 服务。

组

组是中心点的连接子集。您可以在任何时候将客户端连接添加到组中，或从组中移除客户端连接。例如，当客户端加入聊天室时，或当客户端离开聊天室时，这个聊天室可以被视为一个组。客户端可以加入多个组，且一个组可以包含多个客户端。

用户

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

消息

当客户端连接时，它可以通过 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的仓中做一次。

本工程采用了微软开源行为准则。有关更多信息，请参阅行为准则常见问题，或通过[email protected]联系以提出更多问题或意见。