通过

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

适用于 .NET 的 Azure WebJobs SignalR 服务客户端库 - 版本 1.11.2

  • 项目

此扩展提供从 Azure 函数访问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 资源并接收它们的连接字符串，可以通过单击以下方法部署示例模板：

    部署到 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>

ConnectionStringSetting SignalR 绑定的属性 (包括 SignalRAttribute、 SignalRConnectionInfoAttributeSignalRTriggerAttribute 等 ) 用于指定存储连接字符串的配置属性。 如果未指定，则 属性 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 SignalR 服务实例实现Azure Functions中的复原能力和灾难恢复。 有关详细信息，请参阅 Azure Functions 中的多个Azure SignalR 服务实例支持。

示例

SignalR 客户端协商

为了使客户端连接到 SignalR，它需要获取 SignalR 客户端中心 URL 和访问令牌。 我们称此过程为“协商”。

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

广播单个消息

若要从单个 Azure 函数调用将消息广播到中心中的所有连接，可以将 属性应用于 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>" }
    };
}

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

[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 函数调用将多个消息广播到中心中的所有连接，可以将 属性应用于 SignalRIAsyncCollector<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>" }
    });
}

将消息发送到连接、用户或组

若要将消息发送到连接、用户或组，函数类似于上述广播消息，只不过在 的属性中指定 ConnectionId或 UserIdGroupName 。SignalRMessage

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

[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 客户端连接或断开连接时触发函数，可以将 属性应用于 SignalRTriggerInvocationContext 参数。

下面是在 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 客户端发送消息时触发函数，可以将 属性应用于 SignalRTriggerInvocationContext 参数，将 特性应用于 SignalRParameter 名称与消息中的参数名称匹配的每个参数。

下面是当 SignalR 客户端发送目标为“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}.");
}

疑难解答

后续步骤

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

贡献

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

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

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

曝光数