通过

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

适用于 .NET 的 Azure Web PubSub 服务中间件客户端库 - 版本 1.2.0

  • 项目

Azure Web PubSub 服务 是一项服务，可用于使用 WebSocket 和发布-订阅模式生成实时消息传递 Web 应用程序。 任何支持 WebSocket API 的平台都可以轻松连接到服务，例如网页、移动应用程序、边缘设备等。该服务为你管理 WebSocket 连接，并允许多达 10 万 个并发 连接。 它提供强大的 API，用于管理这些客户端和传送实时消息。

任何需要在服务器和客户端或客户端之间进行实时发布-订阅消息传送的方案都可以使用 Azure Web PubSub 服务。 通常需要从服务器轮询或提交 HTTP 请求的传统实时功能也可以使用 Azure Web PubSub 服务。

此库可用于执行以下操作。 有关此处使用的术语的详细信息，请参阅主要概念部分。

  • 在 CloudNative CloudEvents 下分析上游请求
  • 为上游请求添加验证选项
  • 用于添加用户定义的功能以处理不同上游事件的 API

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

入门

安装包

从 NuGet 安装客户端库

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

先决条件

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

验证客户端

若要与服务交互，需要为 Web PubSub 服务提供有效的凭据。 为了实现此目的，需要使用连接字符串或密钥，可在 Azure 门户中对其进行访问。 此外，如果要调用服务 REST API，可以调用 AddWebPubSubServiceClient<THub>() ，其中 THub 是用户实现 WebPubSubHub 的侦听重要事件。

配置 Web PubSub 服务选项

public void ConfigureServices(IServiceCollection services)
{
    services.AddWebPubSub(o =>
    {
        o.ServiceEndpoint = new("<connection-string>");
    }).AddWebPubSubServiceClient<SampleHub>();
}

映射到 WebPubSubHub 终结点路由

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(endpoint =>
    {
        endpoint.MapWebPubSubHub<SampleHub>("/eventhandler");
    });
}

关键概念

有关 Azure Web PubSub 中的常规 Web PubSub 概念的信息

WebPubSubHub

WebPubSubHub 是一个抽象类，允许用户实现订阅的 Web PubSub 服务事件。 用户在服务端注册 事件处理程序 后，这些事件将从服务转发到服务器。 和 WebPubSubHub 提供了 4 种映射到服务事件的方法，使用户能够处理这些事件，例如客户端管理、验证或使用 Azure.Messaging.WebPubSub 来广播消息。 有关详细信息，请参阅下面的示例。

注意

在 4 种方法中， OnConnectAsync() 和 OnMessageReceivedAsync() 是阻止服务将遵循服务器返回的事件。 除了映射的正确响应之外，每当请求针对服务器端逻辑时，服务器都可能会引发异常。 和 UnauthorizedAccessException 将转换为 401Unauthorized ，rest 将转换为 500InternalServerError ，以及异常消息以返回服务。 然后，服务将删除当前的客户端连接。

示例

处理上游Connect事件

private sealed class SampleHub : WebPubSubHub
{
    internal WebPubSubServiceClient<SampleHub> _serviceClient;

    // Need to ensure service client is injected by call `AddServiceHub<SampleHub>` in ConfigureServices.
    public SampleHub(WebPubSubServiceClient<SampleHub> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        var response = new ConnectEventResponse
        {
            UserId = request.ConnectionContext.UserId
        };
        return new ValueTask<ConnectEventResponse>(response);
    }
}

疑难解答

设置控制台日志记录

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

后续步骤

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

贡献

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

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

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

曝光数