ASP.NET Core SignalR 配置

JSON/MessagePack 序列化选项

ASP.NET Core SignalR支持两个用于编码消息的协议: JSONMessagePack。 每个协议都具有序列化配置选项。

可以使用 AddJsonProtocol 扩展方法在服务器上配置 JSON 序列化。 AddJsonProtocol可在添加 SignalR 后添加 Startup.ConfigureServicesAddJsonProtocol方法采用接收对象的委托 options 。 该对象上的 PayloadSerializerOptions 属性是一个 System.Text.Json JsonSerializerOptions 对象,该对象可用于配置自变量和返回值的序列化。 有关详细信息,请参阅 system.object 文档

例如,若要将序列化程序配置为不更改属性名称的大小写(而不是默认的 camel 大小写 名称),请使用中的以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

在 .NET 客户端中, AddJsonProtocol HubConnectionBuilder上存在相同的扩展方法。 Microsoft.Extensions.DependencyInjection必须导入命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

备注

目前不能在 JavaScript 客户端中配置 JSON 序列化。

切换到 Newtonsoft.json

如果需要的功能 Newtonsoft.Json 在中不受支持 System.Text.Json ,请参阅切换 Newtonsoft.Json

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关更多详细信息,请参阅中 SignalR 的 MessagePack

备注

目前不能在 JavaScript 客户端中配置 MessagePack 序列化。

配置服务器选项

下表描述了用于配置中心的选项 SignalR :

选项 默认值 说明
ClientTimeoutInterval 30 秒 如果客户端未收到消息 (在此时间间隔内包含 keep-alive) ,服务器将认为客户端已断开连接。 由于实现方式,将客户端标记为断开连接可能需要更长时间。 建议值为值的两倍 KeepAliveInterval
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,连接将关闭。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改时 KeepAliveInterval ,请更改 ServerTimeout serverTimeoutInMilliseconds 客户端上的或设置。 推荐 ServerTimeout serverTimeoutInMilliseconds 值为,值为 double KeepAliveInterval
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个集线器的特定协议。
EnableDetailedErrors false 如果为,则在 true 集线器方法中引发异常时,详细的异常消息将返回到客户端。 默认值为, false 因为这些异常消息可能包含敏感信息。
StreamBufferCapacity 10 可为客户端上载流缓冲的最大项数。 如果达到此限制,则会阻止处理调用,直到服务器处理流项。
MaximumReceiveMessageSize 32 KB 单个传入集线器消息的最大大小。
MaximumParallelInvocationsPerClient 1 每个客户端可以在进行排队之前并行调用的最大集线器方法数。

可以通过在中提供对调用的选项委托,为所有中心配置选项 AddSignalR Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个集线器的选项用于替代和中提供的全局选项 AddSignalR ,可以使用进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 这些选项通过将委托传递给中的MapHub <T> 来配置 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

下表描述了用于配置 ASP.NET Core SignalR 的高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 64 KB 在应用反压之前,服务器从客户端接收的最大字节数。 增大此值后,服务器可以更快地接收更大的消息,而无需应用反压,但会增加内存消耗。
TransportMaxBufferSize 64 KB 在观察反压之前,服务器要发送的最大字节数。 增大此值后,服务器可以更快地缓冲更大的消息,而无需等待反压,但会增加内存消耗。
AuthorizationData 从应用于 Hub 类的属性中自动收集的数据 Authorize 用于确定客户端是否有权连接到集线器的 IAuthorizeData 对象的列表。
Transports 所有传输均已启用。 值的位标志枚举 HttpTransportType ,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 Websocket 传输的其他选项。
MinimumProtocolVersion 0 指定 negotiate 协议的最低版本。 这用于将客户端限制到较新的版本。
CloseOnAuthenticationExpiration false 设置此选项以启用身份验证过期跟踪,这会在令牌过期时关闭连接。

长轮询传输具有可使用属性配置的其他选项 LongPolling

选项 默认值 说明
PollTimeout 90秒 服务器在终止单个轮询请求之前等待发送到客户端的消息的最长时间。 减小此值将导致客户端更频繁地发出新的投票请求。

WebSocket 传输具有可使用属性配置的其他选项 WebSockets

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内未能关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并且应返回所需的值。

配置客户端选项

可以在 HubConnectionBuilder .net 和 JavaScript 客户端) 中可用的类型 (上配置客户端选项。 它在 Java 客户端中也可用,但 HttpHubConnectionBuilder 子类是包含生成器配置选项的内容,也是其 HubConnection 本身。

配置日志记录

使用方法在 .NET 客户端中配置日志记录 ConfigureLogging 。 日志提供程序和筛选器的注册方式与服务器上相同。 有关详细信息,请参阅ASP.NET Core 文档中的日志记录

备注

若要注册日志记录提供程序,必须安装必要的包。 有关 完整列表, 请参阅文档内置的日志记录提供程序部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供 LogLevel 一个值,该值指示要生成的最小日志消息级别。 日志将写入浏览器控制台窗口。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

还可以 LogLevel 提供表示日志级别 string 名称的值,而不是值。 在无法访问常量的环境中配置日志记录时,这 SignalR LogLevel 非常有用。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

下表列出了可用的日志级别。 提供的值用于 configureLogging 设置 要记录 的最小日志级别。 将记录在此级别记录的消息或表 中列出的 级别。

字符串 LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info information LogLevel.Information
warn warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 指定 方法 configureLogging 中的 。

有关日志记录的信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 它是一个高级日志记录 API,允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 以下代码片段演示如何与 Java java.util.logging 客户端 SignalR 一起使用 。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 会加载包含以下警告消息的默认无操作记录器:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以放心地忽略这一点。

配置允许的传输

可以在 JavaScript (调用中 SignalR 配置 WithUrl withUrl 使用的传输) 。 的值的按位 OR HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认启用所有传输。

例如,若要禁用事件Server-Sent,但允许 WebSockets 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过设置提供给 的选项对象 transport 上的 字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

在此版本的 Java 客户端 Websockets 中,是唯一可用的传输。

在 Java 客户端中,使用 上的 方法 withTransport 选择传输 HttpHubConnectionBuilder 。 Java 客户端默认使用 WebSockets 传输。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

备注

SignalRJava 客户端尚不支持传输回退。

配置 bearer 身份验证

若要提供身份验证数据和请求,请使用 JavaScript (中的) 来指定返回所需访问 SignalR AccessTokenProvider accessTokenFactory 令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP"Bearer 身份验证"令牌传入 (将标头与类型为 Authorization Bearer) 。 在 JavaScript 客户端中,访问令牌用作 Bearer 令牌,但在某些情况下,浏览器 API 会限制应用标头 (,具体而言,在 Server-Sent 事件和 WebSockets 请求中) 。 在这些情况下,访问令牌作为查询字符串值 提供 access_token

在 .NET 客户端中 AccessTokenProvider ,可以使用 中的选项委托指定 选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过设置 中的 options 对象上的 字段 accessTokenFactory 来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的 bearer 令牌。 使用withAccessTokenFactory提供RxJava 单一 <String> 。 通过调用 Single.defer,可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和保持活动状态选项

可用于配置超时和保持活动状态行为的其他选项在对象 HubConnection 本身上可用:

选项 默认值 说明
ServerTimeout 30 秒 (30,000 毫秒) 服务器活动的超时。 如果服务器未在此时间间隔内发送消息,则客户端会认为服务器已断开连接,并触发事件 (Closed onclose JavaScript) 。 此值必须足够大,使 ping 消息能够从服务器发送,并且客户端在超时间隔内接收该消息。 建议的值至少是服务器值的两倍,以 KeepAliveInterval 允许 ping 到达时间。
HandshakeTimeout 15 秒 初始服务器握手的超时。 如果服务器在此时间间隔内未发送握手响应,客户端将取消握手,并触发事件 (Closed onclose JavaScript) 。 这是一个高级设置,只有在由于严重的网络延迟而发生握手超时错误时,才应修改此设置。 有关握手过程的更多详细信息,请参阅中心 SignalR 协议规范
KeepAliveInterval 15 秒 确定客户端发送 ping 消息的时间间隔。 从客户端发送任何消息时,计时器将重置为间隔的开始。 如果客户端尚未在服务器上的 集内发送消息,则服务器 ClientTimeoutInterval 会认为客户端已断开连接。

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在 JavaScript 中的 (中配置其他) Java 客户端上的各种配置 API 上的 WithUrl withUrl HubConnectionBuilder HttpHubConnectionBuilder 方法:

.NET 选项 默认值 说明
AccessTokenProvider null 一个函数,它返回作为 HTTP 请求中的持有者身份验证令牌提供的字符串。
SkipNegotiation false 将此设置为 true 以跳过协商步骤。 仅当 websocket 传输为唯一启用的传输时才受支持。 使用 Azure 服务时,无法启用此设置 SignalR 。
ClientCertificates 要发送以对请求进行身份验证的 TLS 证书的集合。
Cookies cookie要随每个 http 请求一起发送的 http 的集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 Websocket。 客户端在关闭之后等待服务器确认关闭请求的最长时间。 如果服务器在这段时间内没有确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的附加 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并将其返回,或返回一个新的 HttpMessageHandler 实例。 当替换处理程序时,请确保从提供的处理程序复制您要保留的设置,否则,所配置的选项 (如 Cookie s 和标头) 将不会应用于新的处理程序。
Proxy null 发送 HTTP 请求时要使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值可发送 HTTP 和 Websocket 请求的默认凭据。 这样就可以使用 Windows 身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项的 ClientWebSocketOptions 实例。
ApplicationMaxBufferSize 1 MB 在应用反压之前,从服务器接收的最大字节数。 增加此值后,客户端可以更快地接收更大的消息,而无需应用反压,但可以增加内存消耗。
TransportMaxBufferSize 1 MB 在观察反压之前,客户端应用程序发送的最大字节数。 增大此值后,客户端可以更快地缓冲更大的消息,而无需等待反压,但会增加内存消耗。

在 .NET 客户端中,可以通过提供给的 options 委托来修改这些选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

在 Java 客户端中,这些选项可以在 HttpHubConnectionBuilderHubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源

JSON/MessagePack 序列化选项

ASP.NET Core SignalR支持两个用于编码消息的协议: JSONMessagePack。 每个协议都具有序列化配置选项。

可以使用 AddJsonProtocol 扩展方法在服务器上配置 JSON 序列化。 AddJsonProtocol可在添加 SignalR 后添加 Startup.ConfigureServicesAddJsonProtocol方法采用接收对象的委托 options 。 该对象上的 PayloadSerializerOptions 属性是一个 System.Text.Json JsonSerializerOptions 对象,该对象可用于配置自变量和返回值的序列化。 有关详细信息,请参阅 system.object 文档

例如,若要将序列化程序配置为不更改属性名称的大小写(而不是默认的 camel 大小写 名称),请使用中的以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

在 .NET 客户端中, AddJsonProtocol HubConnectionBuilder上存在相同的扩展方法。 Microsoft.Extensions.DependencyInjection必须导入命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

备注

目前不能在 JavaScript 客户端中配置 JSON 序列化。

切换到 Newtonsoft.json

如果需要的功能 Newtonsoft.Json 在中不受支持 System.Text.Json ,请参阅切换 Newtonsoft.Json

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关更多详细信息,请参阅中 SignalR 的 MessagePack

备注

目前不能在 JavaScript 客户端中配置 MessagePack 序列化。

配置服务器选项

下表描述了用于配置中心的选项 SignalR :

选项 默认值 说明
ClientTimeoutInterval 30 秒 如果客户端未收到消息 (在此时间间隔内包含 keep-alive) ,服务器将认为客户端已断开连接。 由于实现方式,将客户端标记为断开连接可能需要更长时间。 建议值为值的两倍 KeepAliveInterval
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,连接将关闭。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改时 KeepAliveInterval ,请更改 ServerTimeout serverTimeoutInMilliseconds 客户端上的或设置。 推荐 ServerTimeout serverTimeoutInMilliseconds 值为,值为 double KeepAliveInterval
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个中心的特定协议。
EnableDetailedErrors false 如果为 ,则当在 Hub 方法中引发异常时,向客户端 true 返回详细的异常消息。 默认值为 false ,因为这些异常消息可以包含敏感信息。
StreamBufferCapacity 10 客户端上传流可以缓冲的最大项数。 如果达到此限制,将阻止对调用的处理,直到服务器处理流项。
MaximumReceiveMessageSize 32 KB 单个传入中心消息的最大大小。
MaximumParallelInvocationsPerClient 1 每个客户端在排队之前可以并行调用的最大中心方法数。

可以通过向 中的调用提供选项委托来配置 AddSignalR 所有中心的选项 Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个中心的选项会替代 中提供的全局选项 AddSignalR ,并且可以使用 进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 通过向 中的 MapHub 传递委托来配置 <T> 这些选项 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

下表介绍了用于配置 ASP.NET Core SignalR 高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 32 KB 在应用反压之前,服务器从客户端接收的最大字节数。 增加此值可让服务器更快接收较大的消息,而无需应用反压,但会增加内存消耗。
AuthorizationData 自动从应用于 Authorize Hub 类的属性收集的数据。 用于确定客户端是否有权连接到中心的 IAuthorizeData 对象的列表。
TransportMaxBufferSize 32 KB 服务器在观察反压之前由应用发送的最大字节数。 增加此值可让服务器更快速地缓冲较大的消息,而无需等待反压,但会增加内存消耗。
Transports 所有传输都已启用。 位标志值 HttpTransportType 枚举,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 WebSockets 传输的其他选项。
MinimumProtocolVersion 0 指定协商协议的最低版本。 这用于将客户端限制为较新版本。

长轮询传输具有其他选项,可以使用 属性 LongPolling 进行配置:

选项 默认值 说明
PollTimeout 90 秒 服务器在终止单个轮询请求之前等待消息发送到客户端的最长时间。 减小此值会导致客户端更频繁地发出新的轮询请求。

WebSocket 传输具有其他选项,可以使用 属性 WebSockets 进行配置:

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内无法关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并预期返回所需的值。

配置客户端选项

可以在 .NET 和 JavaScript 客户端 (中可用的类型 HubConnectionBuilder 配置客户端) 。 它在 Java 客户端中也可用,但子类包含生成器配置选项以及 HttpHubConnectionBuilder HubConnection 本身。

配置日志记录

日志记录是使用 方法在 .NET 客户端中 ConfigureLogging 配置的。 日志记录提供程序和筛选器的注册方式与在服务器上的注册方式相同。 有关详细信息,请参阅 ASP.NET Core日志记录文档。

备注

若要注册日志记录提供程序,必须安装必要的包。 有关 完整列表, 请参阅文档内置的日志记录提供程序部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供 LogLevel 一个值,该值指示要生成的最小日志消息级别。 日志将写入浏览器控制台窗口。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

还可以 LogLevel 提供表示日志级别 string 名称的值,而不是值。 在无法访问常量的环境中配置日志记录时,这 SignalR LogLevel 非常有用。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

下表列出了可用的日志级别。 提供的值用于 configureLogging 设置 要记录 的最小日志级别。 将记录在此级别记录的消息或表 中列出的 级别。

字符串 LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info information LogLevel.Information
warn warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 指定 方法 configureLogging 中的 。

有关日志记录的信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 它是一个高级日志记录 API,允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 以下代码片段演示如何与 Java java.util.logging 客户端 SignalR 一起使用 。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 会加载包含以下警告消息的默认无操作记录器:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以放心地忽略这一点。

配置允许的传输

可以在 JavaScript (调用中 SignalR 配置 WithUrl withUrl 使用的) 。 的值的按位 OR HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认启用所有传输。

例如,若要禁用事件Server-Sent,但允许 WebSockets 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过设置提供给 的选项对象 transport 上的 字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

在此版本的 Java 客户端 Websockets 中,是唯一可用的传输。

在 Java 客户端中,使用 上的 方法 withTransport 选择传输 HttpHubConnectionBuilder 。 Java 客户端默认使用 WebSockets 传输。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

备注

SignalRJava 客户端尚不支持传输回退。

配置 bearer 身份验证

若要提供身份验证数据和请求,请使用 JavaScript (中的) 来指定返回所需访问 SignalR AccessTokenProvider accessTokenFactory 令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP"Bearer 身份验证"令牌传入 (将标头与类型为 Authorization Bearer) 。 在 JavaScript 客户端中,访问令牌用作 Bearer 令牌,但在某些情况下,浏览器 API 会限制应用标头 (,具体而言,在 Server-Sent 事件和 WebSockets 请求中) 。 在这些情况下,访问令牌作为查询字符串值 提供 access_token

在 .NET 客户端中 AccessTokenProvider ,可以使用 中的选项委托指定 选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过设置 中的 options 对象上的 字段 accessTokenFactory 来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的 bearer 令牌。 使用withAccessTokenFactory提供RxJava Single <String> 。 如果调用了 单延迟,你可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和 keep-alive 选项

用于配置超时和保持活动状态的其他选项可用于 HubConnection 对象本身:

选项 默认值 说明
ServerTimeout 30秒 (30000 毫秒) 服务器活动超时。 如果服务器未在此时间间隔内发送消息,则客户端会将服务器视为断开连接,并 Closed onclose 在 JavaScript) 中触发事件 (。 此值必须足够大,以便从服务器发送 ping 消息 ,并 在超时间隔内由客户端接收该消息。 建议值至少为服务器值的两倍 KeepAliveInterval ,以允许 ping 到达的时间。
HandshakeTimeout 15 秒 初始服务器握手的超时时间。 如果服务器在此时间间隔内未发送握手响应,则客户端将取消握手,并 Closed onclose 在 JavaScript) 中触发事件 (。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 确定客户端发送 ping 消息的间隔。 如果从客户端发送任何消息,则会将计时器重置为间隔的开始时间。 如果客户端没有在服务器上的设置中发送消息 ClientTimeoutInterval ,则服务器会将客户端视为已断开连接。

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在中的 WithUrl withUrl JavaScript) 方法 (上 HubConnectionBuilder 或在 HttpHubConnectionBuilder Java 客户端中的各种配置 api 上配置其他选项:

.NET 选项 默认值 说明
AccessTokenProvider null 一个函数,它返回作为 HTTP 请求中的持有者身份验证令牌提供的字符串。
SkipNegotiation false 将此设置为 true 以跳过协商步骤。 仅当 websocket 传输为唯一启用的传输时才受支持。 使用 Azure 服务时,无法启用此设置 SignalR 。
ClientCertificates 要发送以对请求进行身份验证的 TLS 证书的集合。
Cookies cookie要随每个 http 请求一起发送的 http 的集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 Websocket。 客户端在关闭之后等待服务器确认关闭请求的最长时间。 如果服务器在这段时间内没有确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的附加 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并将其返回,或返回一个新的 HttpMessageHandler 实例。 当替换处理程序时,请确保从提供的处理程序复制您要保留的设置,否则,所配置的选项 (如 Cookie s 和标头) 将不会应用于新的处理程序。
Proxy null 发送 HTTP 请求时要使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值可发送 HTTP 和 Websocket 请求的默认凭据。 这样就可以使用 Windows 身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项的 ClientWebSocketOptions 实例。

在 .NET 客户端中,这些选项可以通过提供给 的选项委托进行修改 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给 的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

在 Java 客户端中,可以使用从 返回的 HttpHubConnectionBuilder 上的方法配置这些选项 HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源

JSON/MessagePack 序列化选项

SignalRASP.NET Core支持两种用于编码消息的协议:JSONMessagePack。 每个协议都有序列化配置选项。

可以使用 AddJsonProtocol 扩展方法在服务器上配置 JSON 序列化。 AddJsonProtocol可以在 Add in之后 SignalR 添加 Startup.ConfigureServicesAddJsonProtocol方法采用接收 对象的 options 委托。 该对象上的 PayloadSerializerOptions属性是一个对象,可用于配置参数序列化和 System.Text.Json JsonSerializerOptions 返回值。 有关详细信息,请参阅 System.Text.Json 文档

例如,若要将序列化程序配置为不更改属性名称的大小写,而不是默认的 camel 大小写 名称,请使用 中的以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null
    });

在 .NET 客户端中 AddJsonProtocol ,HubConnectionBuilder上存在相同的扩展方法。 必须 Microsoft.Extensions.DependencyInjection 导入 命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

备注

目前无法配置 JavaScript 客户端中的 JSON 序列化。

切换到 Newtonsoft.Json

如果需要 中 Newtonsoft.Json 不支持的 的功能, System.Text.Json 请参阅 Newtonsoft.Json 切换到

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关详细信息,请参阅 SignalR 中的 MessagePack。

备注

目前无法配置 JavaScript 客户端中的 MessagePack 序列化。

配置服务器选项

下表介绍了用于配置中心 SignalR 的选项:

选项 默认值 说明
ClientTimeoutInterval 30 秒 如果客户端未收到包含此时间间隔内保持 (连接消息,则) 客户端断开连接。 由于实现方式的原因,客户端被标记为已断开连接的时间可能长于此超时间隔。 建议值为值的两 KeepAliveInterval 倍。
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,则连接将关闭。 这是一个高级设置,只有在由于严重的网络延迟而发生握手超时错误时,才应修改此设置。 有关握手过程的更多详细信息,请参阅中心 SignalR 协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改 KeepAliveInterval 时,更改 ServerTimeout 客户端 serverTimeoutInMilliseconds 上的 或 设置。 建议的 ServerTimeoutserverTimeoutInMilliseconds 值是 值的两 KeepAliveInterval 倍。
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个中心的特定协议。
EnableDetailedErrors false 如果为 ,则当在 Hub 方法中引发异常时,向客户端 true 返回详细的异常消息。 默认值为 false ,因为这些异常消息可以包含敏感信息。
StreamBufferCapacity 10 客户端上传流可以缓冲的最大项数。 如果达到此限制,将阻止对调用的处理,直到服务器处理流项。
MaximumReceiveMessageSize 32 KB 单个传入中心消息的最大大小。

可以通过向 中的调用提供选项委托来配置 AddSignalR 所有中心的选项 Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个中心的选项会替代 中提供的全局选项 AddSignalR ,并且可以使用 进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 通过向 中的 MapHub 传递委托来配置 <T> 这些选项 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

下表介绍了用于配置 ASP.NET Core SignalR 高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 32 KB 在应用反压之前,服务器从客户端接收的最大字节数。 增加此值可让服务器更快接收较大的消息,而无需应用反压,但会增加内存消耗。
AuthorizationData 自动从应用于 Authorize Hub 类的属性收集的数据。 用于确定客户端是否有权连接到中心的 IAuthorizeData 对象的列表。
TransportMaxBufferSize 32 KB 服务器在观察反压之前由应用发送的最大字节数。 增加此值可让服务器更快速地缓冲较大的消息,而无需等待反压,但会增加内存消耗。
Transports 所有传输都已启用。 位标志值 HttpTransportType 枚举,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 WebSockets 传输的其他选项。
MinimumProtocolVersion 0 指定协商协议的最低版本。 这用于将客户端限制为较新版本。

长轮询传输具有其他选项,可以使用 属性 LongPolling 进行配置:

选项 默认值 说明
PollTimeout 90 秒 服务器在终止单个轮询请求之前等待消息发送到客户端的最长时间。 减小此值会导致客户端更频繁地发出新的轮询请求。

WebSocket 传输具有其他选项,可以使用 属性 WebSockets 进行配置:

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内无法关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并且应返回所需的值。

配置客户端选项

可以在 HubConnectionBuilder .net 和 JavaScript 客户端) 中可用的类型 (上配置客户端选项。 它在 Java 客户端中也可用,但 HttpHubConnectionBuilder 子类是包含生成器配置选项的内容,也是其 HubConnection 本身。

配置日志记录

使用方法在 .NET 客户端中配置日志记录 ConfigureLogging 。 日志提供程序和筛选器的注册方式与服务器上相同。 有关详细信息,请参阅ASP.NET Core 文档中的日志记录

备注

若要注册日志记录提供程序,必须安装所需的包。 有关完整列表,请参阅文档的 内置日志记录提供程序 部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet 包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供一个 LogLevel 值,该值指示要生成的日志消息的最小级别。 日志将写入浏览器控制台窗口中。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

LogLevel您还可以提供一个 string 表示日志级别名称的值,而不是一个值。 当 SignalR 你在无法访问常量的环境中配置日志记录时,这非常有用 LogLevel

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

下表列出了可用的日志级别。 为 configureLogging 设置将记录的 最小 日志级别而提供的值。 将记录在此级别上记录的消息 或在表中列出的级别

字符串 LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info information LogLevel.Information
warn warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 在方法中指定 configureLogging

有关日志记录的详细信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 这是一个高级日志记录 API,它允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 下面的代码段演示如何将用于 java.util.logging SignalR Java 客户端。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 将加载默认的非操作记录器,并提供以下警告消息:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以安全地忽略此情况。

配置允许的传输

使用的传输 SignalR 可在 WithUrl JavaScript) 的调用 (中进行配置 withUrl 。 的值的按位 "或" HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认情况下,将启用所有传输。

例如,禁用 Server-Sent 事件传输,但允许 Websocket 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过 transport 在提供的选项对象上设置字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

此版本的 Java 客户端 websocket 是唯一可用的传输。

在 Java 客户端中,通过中的方法选择了传输 withTransport HttpHubConnectionBuilder 。 Java 客户端默认使用 Websocket 传输。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

备注

SignalRJava 客户端尚不支持传输回退。

配置持有者身份验证

若要与请求一起提供身份验证数据 SignalR ,请使用 AccessTokenProvider accessTokenFactory JavaScript) 中 (选项来指定返回所需访问令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP "持有者身份验证" 令牌传入 (使用 Authorization) 类型的标头 Bearer 。 在 JavaScript 客户端中,访问令牌用作持有者令牌, 在某些情况下,浏览器 api 会限制在 Server-Sent 事件和 websocket 请求) (具体应用标头的能力。 在这些情况下,访问令牌作为查询字符串值提供 access_token

在 .NET 客户端中, AccessTokenProvider 可使用中的选项委托指定选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过 accessTokenFactory 在中设置 "选项" 对象上的字段来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的持有者令牌。 使用withAccessTokenFactory提供RxJava Single <String> 。 如果调用了 单延迟,你可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和 keep-alive 选项

用于配置超时和保持活动状态的其他选项可用于 HubConnection 对象本身:

选项 默认值 说明
ServerTimeout 30秒 (30000 毫秒) 服务器活动超时。 如果服务器未在此时间间隔内发送消息,则客户端会将服务器视为断开连接,并 Closed onclose 在 JavaScript) 中触发事件 (。 此值必须足够大,以便从服务器发送 ping 消息 ,并 在超时间隔内由客户端接收该消息。 建议值至少为服务器值的两倍 KeepAliveInterval ,以允许 ping 到达的时间。
HandshakeTimeout 15 秒 初始服务器握手的超时时间。 如果服务器在此时间间隔内未发送握手响应,则客户端将取消握手,并 Closed onclose 在 JavaScript) 中触发事件 (。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 确定客户端发送 ping 消息的间隔。 如果从客户端发送任何消息,则会将计时器重置为间隔的开始时间。 如果客户端没有在服务器上的设置中发送消息 ClientTimeoutInterval ,则服务器会将客户端视为已断开连接。

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在 JavaScript (中配置其他) Java 客户端上的各种配置 API 上的 WithUrl withUrl HubConnectionBuilder HttpHubConnectionBuilder 方法:

.NET 选项 默认值 说明
AccessTokenProvider null 返回字符串的函数,该字符串在 HTTP 请求中作为 Bearer 身份验证令牌提供。
SkipNegotiation false 将此选项设置为 true 以跳过协商步骤。 仅在 WebSockets 传输是唯一启用的传输 时支持。 使用 Azure 服务时,无法启用 SignalR 此设置。
ClientCertificates 要发送用于对请求进行身份验证的 TLS 证书的集合。
Cookies 要随每个 HTTP cookie 请求一起发送的 HTTP 集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 WebSockets。 客户端在关闭后等待服务器确认关闭请求的最长时间。 如果服务器在此时间内未确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的其他 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的 。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并返回它,或返回新 HttpMessageHandler 实例。 替换处理程序时,请确保从提供的处理程序复制要保留的设置,否则配置的选项 (如 s 和 headers) 不适用于新 Cookie 处理程序。
Proxy null 发送 HTTP 请求时使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值以发送 HTTP 和 WebSockets 请求的默认凭据。 这允许使用Windows身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项 的 ClientWebSocketOptions 实例。

在 .NET 客户端中,这些选项可以通过提供给 的选项委托进行修改 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给 的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

在 Java 客户端中,可以使用从 返回的 HttpHubConnectionBuilder 上的方法配置这些选项 HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源

JSON/MessagePack 序列化选项

SignalRASP.NET Core支持两种用于编码消息的协议:JSONMessagePack。 每个协议都有序列化配置选项。

可以使用 AddJsonProtocol 扩展方法在服务器上配置 JSON 序列化。 AddJsonProtocol可以在 Add in之后 SignalR 添加 Startup.ConfigureServicesAddJsonProtocol方法采用接收 对象的 options 委托。 该对象上的 PayloadSerializerOptions属性是一个对象,可用于配置参数序列化和 System.Text.Json JsonSerializerOptions 返回值。 有关详细信息,请参阅 System.Text.Json 文档

例如,若要将序列化程序配置为不更改属性名称的大小写,而不是默认的 camel 大小写 名称,请使用 中的以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

在 .NET 客户端中 AddJsonProtocol ,HubConnectionBuilder上存在相同的扩展方法。 必须 Microsoft.Extensions.DependencyInjection 导入 命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

备注

目前无法配置 JavaScript 客户端中的 JSON 序列化。

切换到 Newtonsoft.Json

如果需要 中 Newtonsoft.Json 不支持的 的功能, System.Text.Json 请参阅 Newtonsoft.Json 切换到

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关详细信息,请参阅 SignalR 中的 MessagePack。

备注

目前无法配置 JavaScript 客户端中的 MessagePack 序列化。

配置服务器选项

下表介绍了用于配置中心 SignalR 的选项:

选项 默认值 说明
ClientTimeoutInterval 30 秒 如果客户端未收到包含此时间间隔内保持 (连接消息,则) 客户端断开连接。 由于实现方式的原因,客户端被标记为已断开连接的时间可能长于此超时间隔。 建议值为值的两 KeepAliveInterval 倍。
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,则连接将关闭。 这是一个高级设置,只有在由于严重的网络延迟而发生握手超时错误时,才应修改此设置。 有关握手过程的更多详细信息,请参阅中心 SignalR 协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改 KeepAliveInterval 时,更改 ServerTimeout 客户端 serverTimeoutInMilliseconds 上的 或 设置。 建议的 ServerTimeoutserverTimeoutInMilliseconds 值是 值的两 KeepAliveInterval 倍。
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个中心的特定协议。
EnableDetailedErrors false 如果为 ,则当在 Hub 方法中引发异常时,向客户端 true 返回详细的异常消息。 默认值为 false ,因为这些异常消息可以包含敏感信息。
StreamBufferCapacity 10 可为客户端上载流缓冲的最大项数。 如果达到此限制,则会阻止处理调用,直到服务器处理流项。
MaximumReceiveMessageSize 32 KB 单个传入集线器消息的最大大小。

可以通过在中提供对调用的选项委托,为所有中心配置选项 AddSignalR Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个集线器的选项用于替代和中提供的全局选项 AddSignalR ,可以使用进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 这些选项通过将委托传递给中的MapHub <T> 来配置 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

下表描述了用于配置 ASP.NET Core SignalR 的高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 32 KB 在应用反压之前,服务器从客户端接收的最大字节数。 增大此值后,服务器可以更快地接收更大的消息,而无需应用反压,但会增加内存消耗。
AuthorizationData 从应用于 Hub 类的属性中自动收集的数据 Authorize 用于确定客户端是否有权连接到集线器的 IAuthorizeData 对象的列表。
TransportMaxBufferSize 32 KB 在观察反压之前,服务器要发送的最大字节数。 增大此值后,服务器可以更快地缓冲更大的消息,而无需等待反压,但会增加内存消耗。
Transports 所有传输均已启用。 值的位标志枚举 HttpTransportType ,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 Websocket 传输的其他选项。

长轮询传输具有可使用属性配置的其他选项 LongPolling

选项 默认值 说明
PollTimeout 90秒 服务器在终止单个轮询请求之前等待发送到客户端的消息的最长时间。 减小此值将导致客户端更频繁地发出新的投票请求。

WebSocket 传输具有可使用属性配置的其他选项 WebSockets

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内未能关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并且应返回所需的值。

配置客户端选项

可以在 HubConnectionBuilder .net 和 JavaScript 客户端) 中可用的类型 (上配置客户端选项。 它在 Java 客户端中也可用,但 HttpHubConnectionBuilder 子类是包含生成器配置选项的内容,也是其 HubConnection 本身。

配置日志记录

使用方法在 .NET 客户端中配置日志记录 ConfigureLogging 。 日志提供程序和筛选器的注册方式与服务器上相同。 有关详细信息,请参阅ASP.NET Core 文档中的日志记录

备注

若要注册日志记录提供程序,必须安装所需的包。 有关完整列表,请参阅文档的 内置日志记录提供程序 部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet 包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供一个 LogLevel 值,该值指示要生成的日志消息的最小级别。 日志将写入浏览器控制台窗口中。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

LogLevel您还可以提供一个 string 表示日志级别名称的值,而不是一个值。 当 SignalR 你在无法访问常量的环境中配置日志记录时,这非常有用 LogLevel

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

下表列出了可用的日志级别。 为 configureLogging 设置将记录的 最小 日志级别而提供的值。 将记录在此级别上记录的消息 或在表中列出的级别

字符串 LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info information LogLevel.Information
warn warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 在方法中指定 configureLogging

有关日志记录的详细信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 这是一个高级日志记录 API,它允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 下面的代码段演示如何将用于 java.util.logging SignalR Java 客户端。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 将加载默认的非操作记录器,并提供以下警告消息:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以安全地忽略此情况。

配置允许的传输

使用的传输 SignalR 可在 WithUrl JavaScript) 的调用 (中进行配置 withUrl 。 的值的按位 "或" HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认情况下,将启用所有传输。

例如,禁用 Server-Sent 事件传输,但允许 Websocket 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过 transport 在提供的选项对象上设置字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

此版本的 Java 客户端 websocket 是唯一可用的传输。

在 Java 客户端中,通过中的方法选择了传输 withTransport HttpHubConnectionBuilder 。 Java 客户端默认使用 Websocket 传输。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

备注

SignalRJava 客户端尚不支持传输回退。

配置持有者身份验证

若要与请求一起提供身份验证数据 SignalR ,请使用 AccessTokenProvider accessTokenFactory JavaScript) 中 (选项来指定返回所需访问令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP "持有者身份验证" 令牌传入 (使用 Authorization) 类型的标头 Bearer 。 在 JavaScript 客户端中,访问令牌用作持有者令牌, 在某些情况下,浏览器 api 会限制在 Server-Sent 事件和 websocket 请求) (具体应用标头的能力。 在这些情况下,访问令牌作为查询字符串值提供 access_token

在 .NET 客户端中, AccessTokenProvider 可使用中的选项委托指定选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过 accessTokenFactory 在中设置 "选项" 对象上的字段来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的持有者令牌。 使用withAccessTokenFactory提供RxJava Single <String> 。 如果调用了 单延迟,你可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和 keep-alive 选项

用于配置超时和保持活动状态的其他选项可用于 HubConnection 对象本身:

选项 默认值 说明
ServerTimeout 30秒 (30000 毫秒) 服务器活动超时。 如果服务器未在此时间间隔内发送消息,则客户端会将服务器视为断开连接,并 Closed onclose 在 JavaScript) 中触发事件 (。 此值必须足够大,以便从服务器发送 ping 消息 ,并 在超时间隔内由客户端接收该消息。 建议值至少为服务器值的两倍 KeepAliveInterval ,以允许 ping 到达的时间。
HandshakeTimeout 15 秒 初始服务器握手的超时时间。 如果服务器在此时间间隔内未发送握手响应,则客户端将取消握手,并 Closed onclose 在 JavaScript) 中触发事件 (。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 确定客户端发送 ping 消息的间隔。 如果从客户端发送任何消息,则会将计时器重置为间隔的开始时间。 如果客户端没有在服务器上的设置中发送消息 ClientTimeoutInterval ,则服务器会将客户端视为已断开连接。

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在中的 WithUrl withUrl JavaScript) 方法 (上 HubConnectionBuilder 或在 HttpHubConnectionBuilder Java 客户端中的各种配置 api 上配置其他选项:

.NET 选项 默认值 说明
AccessTokenProvider null 一个函数,它返回作为 HTTP 请求中的持有者身份验证令牌提供的字符串。
SkipNegotiation false 将此设置为 true 以跳过协商步骤。 仅当 websocket 传输为唯一启用的传输时才受支持。 使用 Azure 服务时,无法启用此设置 SignalR 。
ClientCertificates 要发送以对请求进行身份验证的 TLS 证书的集合。
Cookies cookie要随每个 http 请求一起发送的 http 的集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 Websocket。 客户端在关闭之后等待服务器确认关闭请求的最长时间。 如果服务器在这段时间内没有确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的附加 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并将其返回,或返回一个新的 HttpMessageHandler 实例。 当替换处理程序时,请确保从提供的处理程序复制您要保留的设置,否则,所配置的选项 (如 Cookie s 和标头) 将不会应用于新的处理程序。
Proxy null 发送 HTTP 请求时要使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值可发送 HTTP 和 Websocket 请求的默认凭据。 这样就可以使用 Windows 身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项的 ClientWebSocketOptions 实例。

在 .NET 客户端中,可以通过提供给的 options 委托来修改这些选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

在 Java 客户端中,这些选项可以在 HttpHubConnectionBuilderHubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源

JSON/MessagePack 序列化选项

SignalRASP.NET Core支持两种用于编码消息的协议:JSONMessagePack。 每个协议都有序列化配置选项。

可以使用AddJsonProtocol SignalR 扩展方法在服务器上配置 JSON 序列化,该方法可在方法中添加后 Startup.ConfigureServices 添加。 AddJsonProtocol方法采用接收 对象的 options 委托。 该对象上的 PayloadSerializerSettings属性是一 JSON.NET 对象,可用于配置参数序列化和 JsonSerializerSettings 返回值。 有关详细信息,请参阅 JSON.NET 文档

例如,若要将序列化程序配置为使用"PascalCase"属性名称,而不是默认的 camel 大小写 名称,请使用 中的以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

在 .NET 客户端中 AddJsonProtocol ,HubConnectionBuilder上存在相同的扩展方法。 必须 Microsoft.Extensions.DependencyInjection 导入 命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    })
    .Build();

备注

目前无法配置 JavaScript 客户端中的 JSON 序列化。

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关详细信息,请参阅 SignalR 中的 MessagePack。

备注

目前无法配置 JavaScript 客户端中的 MessagePack 序列化。

配置服务器选项

下表介绍了用于配置中心 SignalR 的选项:

选项 默认值 说明
ClientTimeoutInterval 30 秒 如果客户端未收到包含此时间间隔内保持 (连接消息,则) 客户端断开连接。 由于实现方式的原因,客户端被标记为已断开连接的时间可能长于此超时间隔。 建议值为值的两 KeepAliveInterval 倍。
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,则连接将关闭。 这是一个高级设置,只有在由于严重的网络延迟而发生握手超时错误时,才应修改此设置。 有关握手过程的更多详细信息,请参阅中心 SignalR 协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改 KeepAliveInterval 时,更改 ServerTimeout 客户端 serverTimeoutInMilliseconds 上的 或 设置。 建议的 ServerTimeoutserverTimeoutInMilliseconds 值是 值的两 KeepAliveInterval 倍。
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个中心的特定协议。
EnableDetailedErrors false 如果为 ,则当在 Hub 方法中引发异常时,向客户端 true 返回详细的异常消息。 默认值为 false ,因为这些异常消息可以包含敏感信息。

可以通过向 中的调用提供选项委托来配置 AddSignalR 所有中心的选项 Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个中心的选项会替代 中提供的全局选项 AddSignalR ,并且可以使用 进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 通过向 中的 MapHub 传递委托来配置 <T> 这些选项 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSignalR((configure) =>
    {
        var desiredTransports =
            HttpTransportType.WebSockets |
            HttpTransportType.LongPolling;

        configure.MapHub<ChatHub>("/chathub", (options) =>
        {
            options.Transports = desiredTransports;
        });
    });
}

下表介绍了用于配置 ASP.NET Core SignalR 高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 32 KB 从客户端接收服务器缓冲的最大字节数。 增大此值可使服务器接收更大的消息,但可能会对内存消耗产生负面影响。
AuthorizationData 自动从应用于 Authorize Hub 类的属性收集的数据。 用于确定客户端是否有权连接到中心的 IAuthorizeData 对象的列表。
TransportMaxBufferSize 32 KB 服务器缓冲的应用发送的最大字节数。 增加此值允许服务器发送更大的消息,但可能会对内存消耗产生负面影响。
Transports 所有传输都已启用。 位标志值 HttpTransportType 枚举,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 WebSockets 传输的其他选项。

长轮询传输具有其他选项,可以使用 属性 LongPolling 进行配置:

选项 默认值 说明
PollTimeout 90 秒 服务器在终止单个轮询请求之前等待消息发送到客户端的最长时间。 减小此值会导致客户端更频繁地发出新的轮询请求。

WebSocket 传输具有其他选项,可以使用 属性 WebSockets 进行配置:

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内无法关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并预期返回所需的值。

配置客户端选项

可以在 .NET 和 JavaScript 客户端 (中可用的类型 HubConnectionBuilder 配置客户端) 。 它在 Java 客户端中也可用,但子类包含生成器配置选项以及 HttpHubConnectionBuilder HubConnection 本身。

配置日志记录

日志记录是使用 方法在 .NET 客户端中 ConfigureLogging 配置的。 日志记录提供程序和筛选器的注册方式与在服务器上的注册方式相同。 有关详细信息,请参阅 ASP.NET Core日志记录文档。

备注

若要注册日志记录提供程序,必须安装必要的包。 有关 完整列表, 请参阅文档内置的日志记录提供程序部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供 LogLevel 一个值,该值指示要生成的最小日志消息级别。 日志将写入浏览器控制台窗口。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 指定 方法 configureLogging 中的 。

有关日志记录的信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 它是一个高级日志记录 API,允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 以下代码片段演示如何与 Java java.util.logging 客户端 SignalR 一起使用 。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 会加载包含以下警告消息的默认无操作记录器:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以放心地忽略这一点。

配置允许的传输

可以在 JavaScript (调用中 SignalR 配置 WithUrl withUrl 使用的传输) 。 的值的按位 OR HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认情况下,将启用所有传输。

例如,禁用 Server-Sent 事件传输,但允许 Websocket 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过 transport 在提供的选项对象上设置字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

此版本的 Java 客户端 websocket 是唯一可用的传输。

配置持有者身份验证

若要与请求一起提供身份验证数据 SignalR ,请使用 AccessTokenProvider accessTokenFactory JavaScript) 中 (选项来指定返回所需访问令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP "持有者身份验证" 令牌传入 (使用 Authorization) 类型的标头 Bearer 。 在 JavaScript 客户端中,访问令牌用作持有者令牌, 在某些情况下,浏览器 api 会限制在 Server-Sent 事件和 websocket 请求) (具体应用标头的能力。 在这些情况下,访问令牌作为查询字符串值提供 access_token

在 .NET 客户端中, AccessTokenProvider 可使用中的选项委托指定选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过 accessTokenFactory 在中设置 "选项" 对象上的字段来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的持有者令牌。 使用withAccessTokenFactory提供RxJava Single <String> 。 如果调用了 单延迟,你可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和 keep-alive 选项

用于配置超时和保持活动状态的其他选项可用于 HubConnection 对象本身:

选项 默认值 说明
ServerTimeout 30秒 (30000 毫秒) 服务器活动超时。 如果服务器未在此时间间隔内发送消息,则客户端会将服务器视为断开连接,并 Closed onclose 在 JavaScript) 中触发事件 (。 此值必须足够大,以便从服务器发送 ping 消息 ,并 在超时间隔内由客户端接收该消息。 建议值至少为服务器值的两倍 KeepAliveInterval ,以允许 ping 到达的时间。
HandshakeTimeout 15 秒 初始服务器握手的超时时间。 如果服务器在此时间间隔内未发送握手响应,则客户端将取消握手,并 Closed onclose 在 JavaScript) 中触发事件 (。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 确定客户端发送 ping 消息的间隔。 如果从客户端发送任何消息,则会将计时器重置为间隔的开始时间。 如果客户端没有在服务器上的设置中发送消息 ClientTimeoutInterval ,则服务器会将客户端视为已断开连接。

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在中的 WithUrl withUrl JavaScript) 方法 (上 HubConnectionBuilder 或在 HttpHubConnectionBuilder Java 客户端中的各种配置 api 上配置其他选项:

.NET 选项 默认值 说明
AccessTokenProvider null 一个函数,它返回作为 HTTP 请求中的持有者身份验证令牌提供的字符串。
SkipNegotiation false 将此设置为 true 以跳过协商步骤。 仅当 websocket 传输为唯一启用的传输时才受支持。 使用 Azure 服务时,无法启用此设置 SignalR 。
ClientCertificates 要发送以对请求进行身份验证的 TLS 证书的集合。
Cookies cookie要随每个 http 请求一起发送的 http 的集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 Websocket。 客户端在关闭之后等待服务器确认关闭请求的最长时间。 如果服务器在这段时间内没有确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的附加 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并将其返回,或返回一个新的 HttpMessageHandler 实例。 当替换处理程序时,请确保从提供的处理程序复制您要保留的设置,否则,所配置的选项 (如 Cookie s 和标头) 将不会应用于新的处理程序。
Proxy null 发送 HTTP 请求时要使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值可发送 HTTP 和 Websocket 请求的默认凭据。 这样就可以使用 Windows 身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项的 ClientWebSocketOptions 实例。

在 .NET 客户端中,可以通过提供给的 options 委托来修改这些选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

在 Java 客户端中,这些选项可以在 HttpHubConnectionBuilderHubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源

JSON/MessagePack 序列化选项

ASP.NET Core SignalR支持两个用于编码消息的协议: JSONMessagePack。 每个协议都具有序列化配置选项。

可以使用AddJsonProtocol扩展方法在服务器上配置 JSON 序列化,该扩展方法可在方法添加 SignalR 后添加 Startup.ConfigureServicesAddJsonProtocol方法采用接收对象的委托 options 。 该对象的 PayloadSerializerSettings 属性是一个 JSON.NET JsonSerializerSettings 对象,该对象可用于配置自变量和返回值的序列化。 有关详细信息,请参阅 JSON.NET 文档

例如,若要将序列化程序配置为使用 "PascalCase" 属性名称,而不是默认的 camel 大小写 名称,请在中使用以下代码 Startup.ConfigureServices

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

在 .NET 客户端中, AddJsonProtocol HubConnectionBuilder上存在相同的扩展方法。 Microsoft.Extensions.DependencyInjection必须导入命名空间才能解析扩展方法:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    })
    .Build();

备注

目前不能在 JavaScript 客户端中配置 JSON 序列化。

MessagePack 序列化选项

可以通过向 AddMessagePackProtocol 调用提供委托来配置 MessagePack 序列化。 有关更多详细信息,请参阅中 SignalR 的 MessagePack

备注

目前不能在 JavaScript 客户端中配置 MessagePack 序列化。

配置服务器选项

下表描述了用于配置中心的选项 SignalR :

选项 默认值 说明
HandshakeTimeout 15 秒 如果客户端在此时间间隔内未发送初始握手消息,连接将关闭。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范
KeepAliveInterval 15 秒 如果服务器未在此时间间隔内发送消息,则会自动发送 ping 消息,使连接保持打开状态。 更改时 KeepAliveInterval ,请更改 ServerTimeout serverTimeoutInMilliseconds 客户端上的或设置。 推荐 ServerTimeout serverTimeoutInMilliseconds 值为,值为 double KeepAliveInterval
SupportedProtocols 所有已安装的协议 此中心支持的协议。 默认情况下,允许在服务器上注册的所有协议。 可以从此列表中删除协议,以禁用各个集线器的特定协议。
EnableDetailedErrors false 如果为,则在 true 集线器方法中引发异常时,详细的异常消息将返回到客户端。 默认值为, false 因为这些异常消息可能包含敏感信息。

可以通过在中提供对调用的选项委托,为所有中心配置选项 AddSignalR Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

单个集线器的选项用于替代和中提供的全局选项 AddSignalR ,可以使用进行配置 AddHubOptions

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

高级 HTTP 配置选项

用于 HttpConnectionDispatcherOptions 配置与传输和内存缓冲区管理相关的高级设置。 这些选项通过将委托传递给中的MapHub <T> 来配置 Startup.Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSignalR((configure) =>
    {
        var desiredTransports =
            HttpTransportType.WebSockets |
            HttpTransportType.LongPolling;

        configure.MapHub<ChatHub>("/chathub", (options) =>
        {
            options.Transports = desiredTransports;
        });
    });
}

下表描述了用于配置 ASP.NET Core SignalR 的高级 HTTP 选项的选项:

选项 默认值 说明
ApplicationMaxBufferSize 32 KB 服务器缓冲的客户端接收到的最大字节数。 增大此值可使服务器接收更大的消息,但可能会对内存消耗产生负面影响。
AuthorizationData 从应用于 Hub 类的属性中自动收集的数据 Authorize 用于确定客户端是否有权连接到集线器的 IAuthorizeData 对象的列表。
TransportMaxBufferSize 32 KB 由服务器缓冲的应用发送的最大字节数。 增大此值后,服务器将发送更大的消息,但会对内存消耗产生负面影响。
Transports 所有传输均已启用。 值的位标志枚举 HttpTransportType ,可限制客户端可用于连接的传输。
LongPolling 请参阅下文。 特定于长轮询传输的其他选项。
WebSockets 请参阅下文。 特定于 Websocket 传输的其他选项。

长轮询传输具有可使用属性配置的其他选项 LongPolling

选项 默认值 说明
PollTimeout 90秒 服务器在终止单个轮询请求之前等待发送到客户端的消息的最长时间。 减小此值将导致客户端更频繁地发出新的投票请求。

WebSocket 传输具有可使用属性配置的其他选项 WebSockets

选项 默认值 说明
CloseTimeout 5 秒 服务器关闭后,如果客户端在此时间间隔内未能关闭,则连接将终止。
SubProtocolSelector null 一个委托,可用于将 Sec-WebSocket-Protocol 标头设置为自定义值。 委托接收客户端请求的值作为输入,并且应返回所需的值。

配置客户端选项

可以在 HubConnectionBuilder .net 和 JavaScript 客户端) 中可用的类型 (上配置客户端选项。 它在 Java 客户端中也可用,但 HttpHubConnectionBuilder 子类是包含生成器配置选项的内容,也是其 HubConnection 本身。

配置日志记录

使用方法在 .NET 客户端中配置日志记录 ConfigureLogging 。 日志提供程序和筛选器的注册方式与服务器上相同。 有关详细信息,请参阅ASP.NET Core 文档中的日志记录

备注

若要注册日志记录提供程序,必须安装所需的包。 有关完整列表,请参阅文档的 内置日志记录提供程序 部分。

例如,若要启用控制台日志记录,请安装 Microsoft.Extensions.Logging.Console NuGet 包。 调用 AddConsole 扩展方法:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

在 JavaScript 客户端中,存在类似的 configureLogging 方法。 提供一个 LogLevel 值,该值指示要生成的日志消息的最小级别。 日志将写入浏览器控制台窗口中。

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

备注

若要完全禁用日志记录,请 signalR.LogLevel.None 在方法中指定 configureLogging

有关日志记录的详细信息,请参阅 SignalR 诊断文档

SignalRJava 客户端使用SLF4J库进行日志记录。 这是一个高级日志记录 API,它允许库的用户通过引入特定的日志记录依赖项来选择自己的特定日志记录实现。 下面的代码段演示如何将用于 java.util.logging SignalR Java 客户端。

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

如果未在依赖项中配置日志记录,SLF4J 将加载默认的非操作记录器,并提供以下警告消息:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

可以安全地忽略此情况。

配置允许的传输

使用的传输 SignalR 可在 WithUrl JavaScript) 的调用 (中进行配置 withUrl 。 的值的按位 "或" HttpTransportType 可用于将客户端限制为仅使用指定的传输。 默认情况下,将启用所有传输。

例如,禁用 Server-Sent 事件传输,但允许 Websocket 和长轮询连接:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

在 JavaScript 客户端中,通过 transport 在提供的选项对象上设置字段来配置传输 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

配置持有者身份验证

若要与请求一起提供身份验证数据 SignalR ,请使用 AccessTokenProvider accessTokenFactory JavaScript) 中 (选项来指定返回所需访问令牌的函数。 在 .NET 客户端中,此访问令牌作为 HTTP "持有者身份验证" 令牌传入 (使用 Authorization) 类型的标头 Bearer 。 在 JavaScript 客户端中,访问令牌用作持有者令牌, 在某些情况下,浏览器 api 会限制在 Server-Sent 事件和 websocket 请求) (具体应用标头的能力。 在这些情况下,访问令牌作为查询字符串值提供 access_token

在 .NET 客户端中, AccessTokenProvider 可使用中的选项委托指定选项 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

在 JavaScript 客户端中,通过 accessTokenFactory 在中设置 "选项" 对象上的字段来配置访问令牌 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

在 SignalR Java 客户端中,可以通过向 HttpHubConnectionBuilder提供访问令牌工厂来配置用于身份验证的持有者令牌。 使用withAccessTokenFactory提供RxJava Single <String> 。 如果调用了 单延迟,你可以编写逻辑来为客户端生成访问令牌。

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

配置超时和 keep-alive 选项

用于配置超时和保持活动状态的其他选项可用于 HubConnection 对象本身:

选项 默认值 说明
ServerTimeout 30秒 (30000 毫秒) 服务器活动超时。 如果服务器未在此时间间隔内发送消息,则客户端会将服务器视为断开连接,并 Closed onclose 在 JavaScript) 中触发事件 (。 此值必须足够大,以便从服务器发送 ping 消息 ,并 在超时间隔内由客户端接收该消息。 建议值至少为服务器值的两倍 KeepAliveInterval ,以允许 ping 到达的时间。
HandshakeTimeout 15 秒 初始服务器握手的超时时间。 如果服务器在此时间间隔内未发送握手响应,则客户端将取消握手,并 Closed onclose 在 JavaScript) 中触发事件 (。 这是一种高级设置,只应在握手超时错误由于严重网络延迟而发生时进行修改。 有关握手过程的详细信息,请参阅 SignalR 集线器协议规范

在 .NET 客户端中,超时值指定为 TimeSpan 值。

配置其他选项

可以在中的 WithUrl withUrl JavaScript) 方法 (上 HubConnectionBuilder 或在 HttpHubConnectionBuilder Java 客户端中的各种配置 api 上配置其他选项:

.NET 选项 默认值 说明
AccessTokenProvider null 一个函数,它返回作为 HTTP 请求中的持有者身份验证令牌提供的字符串。
SkipNegotiation false 将此设置为 true 以跳过协商步骤。 仅当 websocket 传输为唯一启用的传输时才受支持。 使用 Azure 服务时,无法启用此设置 SignalR 。
ClientCertificates 要发送以对请求进行身份验证的 TLS 证书的集合。
Cookies cookie要随每个 http 请求一起发送的 http 的集合。
Credentials 要随每个 HTTP 请求一起发送的凭据。
CloseTimeout 5 秒 仅 Websocket。 客户端在关闭之后等待服务器确认关闭请求的最长时间。 如果服务器在这段时间内没有确认关闭,客户端将断开连接。
Headers 要随每个 HTTP 请求一起发送的附加 HTTP 标头的映射。
HttpMessageHandlerFactory null 一个委托,可用于配置或替换 HttpMessageHandler 用于发送 HTTP 请求的。 不用于 WebSocket 连接。 此委托必须返回非 null 值,并接收默认值作为参数。 修改该默认值的设置并将其返回,或返回一个新的 HttpMessageHandler 实例。 当替换处理程序时,请确保从提供的处理程序复制您要保留的设置,否则,所配置的选项 (如 Cookie s 和标头) 将不会应用于新的处理程序。
Proxy null 发送 HTTP 请求时要使用的 HTTP 代理。
UseDefaultCredentials false 设置此布尔值可发送 HTTP 和 Websocket 请求的默认凭据。 这允许使用Windows身份验证。
WebSocketConfiguration null 可用于配置其他 WebSocket 选项的委托。 接收可用于配置选项 的 ClientWebSocketOptions 实例。

在 .NET 客户端中,这些选项可以通过提供给 的选项委托进行修改 WithUrl

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 客户端中,可以在提供给 的 JavaScript 对象中提供这些选项 withUrl

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

在 Java 客户端中,可以使用从 返回的 HttpHubConnectionBuilder 上的方法配置这些选项 HubConnectionBuilder.create("HUB URL")

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

其他资源