Microsoft.Azure.WebPubSub.AspNetCore 1.3.0

Azure Web PubSub 服务中间件客户端库，适用于 .NET

Azure Web PubSub 服务 是一种服务，可让您使用 WebSockets 和发布订阅模式构建实时消息 Web 应用程序。任何支持 WebSocket API 的平台都可以轻松连接到该服务，例如网页、移动应用程序、边缘设备等。该服务为您管理 WebSocket 连接，并允许最多 100K 并发 连接。它提供了强大的 API，供您管理这些客户端并传递实时消息。

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

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

• 在 CloudNative CloudEvents 下解析上游请求
• 为上游请求添加验证选项
• 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>();
}

使用 Azure Identity 配置

public void ConfigureServices(IServiceCollection services)
{
    services.AddWebPubSub(o =>
    {
        o.ServiceEndpoint = new WebPubSubServiceEndpoint(new Uri("<endpoint"), new DefaultAzureCredential());
    }).AddWebPubSubServiceClient<SampleHub>();
}

将 WebPubSubHub 映射到端点路由

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

基本概念

有关一般 Web PubSub 概念的详细信息，请参阅 Azure Web PubSub 概念

WebPubSubHub

WebPubSubHub 是一个抽象类，让用户实现订阅的 Web PubSub 服务事件。用户在服务端注册 事件处理器 后，这些事件将从服务端转发到服务器。并且 WebPubSubHub 提供了映射到服务事件的 4 个方法，以便用户处理这些事件，例如客户端管理、验证或与 Azure.Messaging.WebPubSub 一起广播消息。以下是一些示例的详细信息。

注意

在 4 个方法中，OnConnectAsync() 和 OnMessageReceivedAsync() 是阻塞事件，服务将尊重服务器的返回值。除了映射正确的响应外，服务器可以在请求违反服务器端逻辑时抛出异常。并且 UnauthorizedAccessException 和 AuthenticationException 将转换为 401Unauthorized，其余转换为 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);
    }
}

故障排除

配置控制台日志记录

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

下一步

请参阅 Samples 目录，了解如何使用此库的详细示例。

贡献

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

提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA，并适当地标记拉取请求（例如，标记、注释）。只需遵循机器人提供的说明即可。在所有使用我们的 CLA 的存储库中，您只需这样做一次。

此项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 [email protected]，如有任何附加问题或评论。