使用 Azure SignalR 服务进行 Azure Functions 开发和配置

基于类的模型提供了更好的编程体验，可以替代 SignalR 输入和输出绑定，具有以下特点：

• 更灵活的协商、发送消息和管理组体验。
• 支持更多管理功能，包括关闭连接、检查连接、用户或组是否存在。
• 强类型中心
• 支持在同一处设置中心名称和连接字符串。

以下代码演示了如何在基于类的模型中编写 SignalR 绑定：

首先，定义派生自 ServerlessHub 类的中心：

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub
{
    private const string HubName = nameof(Functions); // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("negotiate")]
    public async Task<HttpResponseData> Negotiate([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
    {
        var negotiateResponse = await NegotiateAsync(new() { UserId = req.Headers.GetValues("userId").FirstOrDefault() });
        var response = req.CreateResponse();
        response.WriteBytes(negotiateResponse.ToArray());
        return response;
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.SendAsync("newMessage", new NewMessage(invocationContext, message));
    }

    [Function("JoinGroup")]
    public Task JoinGroup([SignalRTrigger(HubName, "messages", "JoinGroup", "connectionId", "groupName")] SignalRInvocationContext invocationContext, string connectionId, string groupName)
    {
        return Groups.AddToGroupAsync(connectionId, groupName);
    }
}

在 Program.cs 文件中，注册无服务器中心：

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(b => b.Services
        .AddServerlessHub<Functions>())
    .Build();

基于类的模型中的协商体验

与使用 SignalR 输入绑定 [SignalRConnectionInfoInput] 相比，基于类的模型中的协商更为灵活。 基类 ServerlessHub 具备 NegotiateAsync 方法，允许用户自定义协商选项，例如 userId、claims 等。

Task<BinaryData> NegotiateAsync(NegotiationOptions? options = null)

在基于类的模型中发送消息和管理体验

可以通过访问基类 ServerlessHub 提供的成员来发送消息、管理组或管理客户端。

• ServerlessHub.Clients 用于向客户端发送消息。
• ServerlessHub.Groups 用于管理与组的连接，例如向组添加连接、从组中删除连接。
• ServerlessHub.UserGroups 用于通过组管理用户，例如将用户添加到组、从组中删除用户。
• ServerlessHub.ClientManager 用于检查连接是否存在、关闭连接等操作。

强类型中心

强类型中心可支持你在向客户端发送消息时使用强类型方法。 若要在基于类的模型中使用强类型中心，请将客户端方法提取到接口 T 中，并通过 ServerlessHub<T> 派生中心类。

以下代码是客户端方法的接口示例。

public interface IChatClient
{
    Task newMessage(NewMessage message);
}

然后，可以使用强类型方法，如下所示：

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub<IChatClient>
{
    private const string HubName = nameof(Functions);  // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.newMessage(new NewMessage(invocationContext, message));
    }
}

支持在同一处设置中心名称和连接字符串

• 系统会自动将无服务器中心的类名设为 HubName。
• 你可能已注意到无服务器中心类上使用的 SignalRConnection 属性，如下所示：

  [SignalRConnection("AzureSignalRConnectionString")]
  public class Functions : ServerlessHub<IChatClient>
  

  该属性支持自定义无服务器中心的连接字符串的位置。 如果未指定，则使用默认值 AzureSignalRConnectionString。

基于类的模型提供一致的 SignalR 服务器端编程体验，具有以下功能：

• 减少配置工作量：类名称用作 HubName，方法名称用作 Event，Category 根据方法名称自动确定。
• 自动参数绑定：不需要 ParameterNames 和属性 [SignalRParameter]。 参数按顺序自动绑定到 Azure Function 方法的参数上。
• 便捷的输出和协商体验。

以下代码演示了这些功能：

public class HubName1 : ServerlessHub
{
    [FunctionName("negotiate")]
    public SignalRConnectionInfo Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req)
    {
        return Negotiate(req.Headers["x-ms-signalr-user-id"], GetClaims(req.Headers["Authorization"]));
    }

    [FunctionName(nameof(OnConnected))]
    public async Task OnConnected([SignalRTrigger]InvocationContext invocationContext, ILogger logger)
    {
        await Clients.All.SendAsync(NewConnectionTarget, new NewConnection(invocationContext.ConnectionId));
        logger.LogInformation($"{invocationContext.ConnectionId} has connected");
    }

    [FunctionName(nameof(Broadcast))]
    public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        await Clients.All.SendAsync(NewMessageTarget, new NewMessage(invocationContext, message));
        logger.LogInformation($"{invocationContext.ConnectionId} broadcast {message}");
    }

    [FunctionName(nameof(OnDisconnected))]
    public void OnDisconnected([SignalRTrigger]InvocationContext invocationContext)
    {
    }
}

需要利用基于类的模型的所有函数都需是继承自 ServerlessHub 的类的方法。 示例中的类名称 HubName1 是中心名称。

定义中心方法

所有中心方法必须具有由 [SignalRTrigger] 属性修饰的 InvocationContext 参数，并使用无参数构造函数。 然后将方法名称视为参数事件。

默认情况下，除了方法名称外，category=messages 是以下名称之一：

• OnConnected：视为 category=connections, event=connected
• OnDisconnected：视为 category=connections, event=disconnected

参数绑定体验

在基于类的模型中，[SignalRParameter] 是不必要的，因为默认情况下，所有参数都标记为 [SignalRParameter]，除非是以下情况之一：

• 参数由绑定属性修饰
• 参数的类型为 ILogger 或 CancellationToken
• 参数由属性 [SignalRIgnore] 修饰

基于类的模型中的协商体验

与使用 SignalR 输入绑定 [SignalR] 相比，基于类的模型中的协商更为灵活。 基类 ServerlessHub 具有一个方法：

SignalRConnectionInfo Negotiate(string userId = null, IList<Claim> claims = null, TimeSpan? lifeTime = null)

此功能使用户可以在函数执行期间自定义 userId 或 claims。

使用 SignalRFilterAttribute

用户可以继承和实现抽象类 SignalRFilterAttribute。 如果 FilterAsync 中引发异常，会将 403 Forbidden 发送回客户端。

下面的示例演示如何实现仅允许 admin 调用 broadcast 的客户筛选器。

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
internal class FunctionAuthorizeAttribute: SignalRFilterAttribute
{
    private const string AdminKey = "admin";

    public override Task FilterAsync(InvocationContext invocationContext, CancellationToken cancellationToken)
    {
        if (invocationContext.Claims.TryGetValue(AdminKey, out var value) &&
            bool.TryParse(value, out var isAdmin) &&
            isAdmin)
        {
            return Task.CompletedTask;
        }

        throw new Exception($"{invocationContext.ConnectionId} doesn't have admin role");
    }
}

利用属性对函数进行授权。

[FunctionAuthorize]
[FunctionName(nameof(Broadcast))]
public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
{
}