Microsoft.Azure.WebJobs.Extensions.SignalRService 1.14.0

Azure WebJobs SignalR 服务客户端库，用于.NET

此扩展为从Azure Function访问Azure SignalR 服务提供了功能。

入门指南

安装包

使用NuGet安装SignalR服务客户端

dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService

先决条件

• Azure 订阅： 为了使用Azure服务，包括Azure SignalR服务，您需要一个订阅。如果没有现有的Azure账户，可以注册一个免费试用或在使用Visual Studio 订阅时使用您的账户福利来创建一个账户。

• Azure SignalR 资源： 要使用 SignalR 服务客户端库，您还需要一个 Azure SignalR 资源。如果您不熟悉创建 Azure 资源，您可能想要遵循使用 Azure 门户创建 SignalR 资源的逐步指南。在那里，您还可以找到使用 Azure CLI、Azure PowerShell 或 Azure 资源管理器 (ARM) 模板创建 SignalR 资源的详细说明。

  要快速在 Azure 中创建所需的 SignalR 资源并获得连接字符串，您可以通过单击来部署我们的示例模板。

  实例部署后，在门户中将其打开，并找到其设置页面。将服务模式设置更改为 无服务器。

验证客户端

为了使 SignalR 服务客户端能够访问 SignalR 资源，它需要了解如何对其进行身份验证。这么做最简单的方法是使用连接字符串，可以在Azure 门户中找到，或者使用以下 Azure CLI / Azure PowerShell 片段。

Azure CLI 片段

az signalr key list -n <your-resource-name> -g <your-resource-group-name> --query primaryKey -o tsv

Azure PowerShell 片段

Get-AzSignalRKey -ResourceGroupName <your-resource-name> -Name <your-resource-name>

SignalR 绑定的 ConnectionStringSetting 属性（包括 SignalRAttribute、SignalRConnectionInfoAttribute、SignalRTriggerAttribute 等）用于指定存储连接字符串的配置属性。如果没有指定，则期望 AzureSignalRConnectionString 属性包含连接字符串。

对于本地开发，请使用 local.settings.json 文件来存储连接字符串

{
  "Values": {
    "<connection_name>": "<connection-string>"
  }
}

部署后，请使用 应用程序设置 来设置连接字符串。

关键概念

SignalR 服务客户端与 SignalR 客户端对比

SignalR 服务客户端：指的是此库。它以无服务器风格提供了 SignalR 服务器 功能。

SignalR 客户端：与 SignalR 服务器 的相反概念。有关更多信息，请参阅 ASP.NET Core SignalR 客户端。

SignalR 连接信息输入绑定

SignalRConnectionInfo 输入绑定使得生成 SignalR 客户端连接到 Azure SignalR 服务所需令牌变得容易。

请遵循Azure SignalR 连接信息输入绑定教程 以了解有关 SignalR 连接信息输入绑定的更多信息。

SignalR 输出绑定

SignalR 输出绑定允许：

• 向所有连接、单个连接、用户或组发送消息。
• 在组中添加/删除单个用户/连接。

请遵循Azure SignalR 输出绑定 以了解有关 SignalR 输出绑定的更多信息。

SignalR 触发器

SignalR 触发器允许当消息被发送到 Azure SignalR 服务时执行函数。

请遵循Azure SignalR 触发器 以了解有关 SignalR 触发器的更多信息。

支持的场景

• 为 SignalR 客户端进行协商。
• 管理类似在组中添加/删除单个用户/连接的组。
• 向单个用户/连接、组或所有用户/连接发送消息。
• 在 Azure Functions 中使用多个 Azure SignalR 服务实例以实现弹性恢复和灾难恢复。请参阅Azure Functions 中 Azure SignalR 服务实例的多种支持 中的详细信息。

示例

SignalR 客户端的协商

为了使客户端能够连接到SignalR，它需要获得SignalR客户端Hub URL和访问令牌。我们将这个过程称为“协商”。

[FunctionName("Negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req,
    [SignalRConnectionInfo(HubName = "<hub_name>", UserId = "<user_id>")] SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

广播单个消息

要从单个Azure Function调用中向Hub中的所有连接广播消息，可以将SignalR属性应用到函数返回值上。返回值应该是SignalRMessage类型。

[FunctionName("sendOneMessageWithReturnValueBinding")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

您也可以使用SignalRMessage类型的out参数。

[FunctionName("messages")]
public static void SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req, [SignalR(HubName = "<hub_name>")] out SignalRMessage message)
{
    message = new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

广播多条消息

要从单个Azure Function调用中向Hub中的所有连接广播多条消息，可以将SignalR属性应用到IAsyncCollector<SignalRMessage>参数上。

[FunctionName("messages")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
    [SignalR(HubName = "<hub_name>")] IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
    new SignalRMessage
    {
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    });
}

向连接、用户或组发送消息

要向连接、用户或组发送消息，函数与上面广播消息的过程类似，不同之处在于您需要在SignalRMessage的属性中指定ConnectionId、UserId或GroupName。

以下是使用返回值绑定发送用户消息的示例。

[FunctionName("messages")]
[return: SignalR(HubName = "<hub_name>")]
public static SignalRMessage SendMessageToUser(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req)
{
    return new SignalRMessage
    {
        UserId = "<user_id>",
        Target = "<target>",
        Arguments = new[] { "<here_can_be_multiple_objects>" }
    };
}

SignalR客户端连接触发器

要触发在SignalR客户端连接或断开时调用的函数，可以将SignalRTrigger属性应用到InvocationContext参数上。

以下是已在SignalR客户端连接时记录连接ID的示例。请确保SignalRTrigger构造函数的第二个参数是connections，表示触发器的类别是连接。第三个

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("<hubName>", "connections", "connected")] InvocationContext invocationContext, ILogger logger)
{
    logger.LogInformation($"{invocationContext.ConnectionId} was connected.");
}

SignalR客户端消息触发器

要触发在SignalR客户端发送消息时调用的函数，可以将SignalRTrigger属性应用到InvocationContext参数上，将SignalRParameter属性应用到每个匹配您消息中参数名称的参数上。

以下是记录带有目标“SendMessage”的消息内容的示例。

[FunctionName("SignalRTest")]
public static void Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")] InvocationContext invocationContext, [SignalRParameter] string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

故障排除

• 请参阅Monitor Azure Functions以获取函数故障排除指导。
• Azure SignalR服务的故障排除指南

下一步操作

阅读Azure函数简介或创建Azure函数指南

贡献

有关构建、测试和为此库贡献的详细信息，请参阅我们的CONTRIBUTING.md。

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权利，实际上也确实授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

本项目采用了Microsoft Open Source Code of Conduct。有关更多信息和常见问题解答，请参阅Code of Conduct FAQ，或通过[email protected]与以任何其他问题或意见。