Flutter实时通信插件netcore_signalr的使用

简介

signalr_netcore 是一个用于 Flutter 应用程序的 ASP.NET Core SignalR 客户端库。ASP.NET Core SignalR 是一个开源库，它简化了向应用程序添加实时Web功能的过程。实时Web功能使服务器端代码能够即时推送内容到客户端。

本库经过测试，支持 ASP.NET Core 3.1 和 ASP.NET Core 6。该客户端能够调用服务器端的Hub函数（包括流式函数）并接收由服务器发起的方法调用。它还支持自动重连功能。

该客户端支持以下传输协议：

• WebSocket
• Service Side Events
• Long Polling

该客户端支持以下Hub协议：

• Json
• MessagePack

示例

聊天客户端/服务器

• 聊天客户端/服务器 - 一个简单的客户端/服务器聊天应用。
• 集成测试应用 - 查看客户端如何调用各种类型的Hub函数。

开始使用

在 pubspec.yaml 文件中添加 signalr_netcore 依赖项：

dependencies:
  flutter:
    sdk: flutter

  signalr_netcore:

重要提示：如果你遇到问题（例如未接收到消息回调），请尝试使用旧版本，如 signalr_netcore: 0.1.7+2-nullsafety.3，但请注意，该版本不支持自动重连功能，需要手动处理。

使用方法

以下是一些基本用法的示例：

1. 创建Hub连接

// 导入库
import 'package:signalr_netcore/signalr_client.dart';

// 服务器地址
final serverUrl = "192.168.10.50:51001";

// 创建连接
final hubConnection = HubConnectionBuilder().withUrl(serverUrl).build();

// 连接关闭时打印消息
hubConnection.onclose((error) => print("Connection Closed"));

日志记录可以通过 logging 包进行配置：

// 导入库
import 'package:logging/logging.dart';
import 'package:signalr_netcore/signalr_client.dart';

// 配置日志
Logger.root.level = Level.ALL;
Logger.root.onRecord.listen((LogRecord rec) {
  print('${rec.level.name}: ${rec.time}: ${rec.message}');
});

// 日志记录级别为Hub协议
final hubProtLogger = Logger("SignalR - hub");

// 日志记录级别为传输
final transportProtLogger = Logger("SignalR - transport");

// 创建带有日志记录选项的连接
final httpOptions = HttpConnectionOptions(logger: transportProtLogger);
final hubConnection = HubConnectionBuilder().withUrl(serverUrl, options: httpOptions).configureLogging(hubProtLogger).build();

// 连接关闭时打印消息
hubConnection.onclose((error) => print("Connection Closed"));

2. 连接到Hub

调用以下方法开始握手并连接客户端到SignalR服务器：

await hubConnection.start();

3. 调用Hub函数

假设有一个Hub函数：

public string MethodOneSimpleParameterSimpleReturnValue(string p1)
{
  Console.WriteLine($"'MethodOneSimpleParameterSimpleReturnValue' invoked. Parameter value: '{p1}");
  return p1;
}

客户端可以调用此函数：

final result = await hubConnection.invoke("MethodOneSimpleParameterSimpleReturnValue", args: <Object>["ParameterValue"]);
logger.log(LogLevel.Information, "Result: '$result'");

4. 调用客户端函数

假设服务器调用名为 “aClientProvidedFunction” 的函数：

await Clients.Caller.SendAsync("aClientProvidedFunction", null);

客户端可以这样实现：

hubConnection.on("aClientProvidedFunction", _handleAClientProvidedFunction);

// 取消注册函数
// a) 取消注册特定实现
// hubConnection.off("aClientProvidedFunction", method: _handleServerInvokeMethodNoParametersNoReturnValue);
// b) 取消注册所有实现
// hubConnection.off("aClientProvidedFunction");

void _handleAClientProvidedFunction(List<Object> parameters) {
  logger.log(LogLevel.Information, "Server invoked the method");
}

5. 使用Msgpack进行序列化

如果需要使用Msgpack协议进行序列化，需要在客户端和服务器上都进行配置。

客户端

import 'package:signalr_netcore/msgpack_hub_protocol.dart';

_hubConnection = HubConnectionBuilder()
          .withUrl(_serverUrl, options: httpOptions)
          /* 配置Hub使用Msgpack协议 */
          .withHubProtocol(MessagePackHubProtocol())
          .withAutomaticReconnect()
          .configureLogging(logger)
          .build();

服务器

在ASP.NET Core项目中添加以下包：

Microsoft.AspNetCore.SignalR.Protocols.MessagePack

然后在 ConfigureServices 方法中配置Hub使用Msgpack协议：

public void ConfigureServices(IServiceCollection services)
{
    // 配置Hub使用Msgpack协议
    services.AddSignalR().AddMessagePackProtocol();
}

参数类型注意事项

所有函数参数和返回值都通过 dart:convert 包（json.encode/json.decode）进行序列化/反序列化。确保你：

• 只使用简单参数类型
• 或者使用实现了 toJson() 方法的对象，因为该方法被 dart:convert 包用来序列化对象。

如何暴露MessageHeaders对象以便客户端发送默认头

final defaultHeaders = MessageHeaders();
defaultHeaders.setHeaderValue("HEADER_MOCK_1", "HEADER_VALUE_1");
defaultHeaders.setHeaderValue("HEADER_MOCK_2", "HEADER_VALUE_2");

final httpConnectionOptions = HttpConnectionOptions(
          httpClient: WebSupportingHttpClient(logger, httpClientCreateCallback: _httpClientCreateCallback),
          accessTokenFactory: () => Future.value('JWT_TOKEN'),
          logger: logger,
          logMessageContent: true,
          headers: defaultHeaders);

final _hubConnection = HubConnectionBuilder()
          .withUrl(_serverUrl, options: httpConnectionOptions)
          .withAutomaticReconnect(retryDelays: [2000, 5000, 10000, 20000, null])
          .configureLogging(logger)
          .build();

HTTP请求日志：

I/flutter ( 5248): Starting connection with transfer format 'TransferFormat.Text'.
I/flutter ( 5248): Sending negotiation request: https://localhost:5000/negotiate?negotiateVersion=1
I/flutter ( 5248): HTTP send: url 'https://localhost:5000/negotiate?negotiateVersion=1', method: 'POST' content: '' content length = '0' 
headers: '{ content-type: text/plain;charset=UTF-8 }, { HEADER_MOCK_1: HEADER_VALUE_1 }, { X-Requested-With: FlutterHttpClient }, { HEADER_MOCK_2: HEADER_VALUE_2 }, { Authorization: Bearer JWT_TOKEN }'

示例代码

聊天客户端/服务器

import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const Placeholder();
  }
}