ASP.NET 核心 SignalR 配置

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 Program.cs 中使用以下代码：

builder.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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 AddSignalR 中向 Program.cs 调用提供选项委托，为所有中心配置选项。

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

单个集线器的选项将覆盖AddSignalR提供的全局选项，并且可以使用AddHubOptions进行配置。

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

高级 HTTP 配置选项

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

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

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

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

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

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

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

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

用于配置超时和保持连接行为的其他选项：

var builder = new HubConnectionBuilder()
    .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
    .WithServerTimeout(TimeSpan.FromSeconds(60))
    .WithKeepAliveInterval(TimeSpan.FromSeconds(30))
    .Build();

builder.On<string, string>("ReceiveMessage", (user, message) => ...

await builder.StartAsync();

var connection = new signalR.HubConnectionBuilder()
  .withUrl("/chatHub")
  .withServerTimeout(60000)
  .withKeepAliveInterval(30000)
  .build();

配置监控状态的重新连接

SignalR 有状态重连可以减少客户端因网络连接暂时中断（例如在切换网络连接或短暂失去访问权限时）而感知到的停机时间。

有状态重新连接可通过以下方式实现此目的：

• 暂时缓冲服务器和客户端上的数据。
• 服务端和客户端对收到的消息进行确认（ACK）。
• 识别连接何时启动并重播连接关闭时可能已发送的消息。

有状态重连在 .NET 8 或更高版本中可用。

在服务器中心终结点和客户端处选择加入监控状态的重新连接：

• 更新服务器中心终结点配置以启用 AllowStatefulReconnects 选项：

  app.MapHub<MyHub>("/hubName", options =>
  {
      options.AllowStatefulReconnects = true;
  });
  

  （可选）可以全局设置服务器允许的最大缓冲区大小（以字节为单位），也可以使用 StatefulReconnectBufferSize 选项针对特定的中心进行设置：

  全局设置的 StatefulReconnectBufferSize 选项：

  builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
  

  针对特定中心进行设置的 StatefulReconnectBufferSize 选项：

  builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
  

  StatefulReconnectBufferSize 选项是可选的，默认值为 100,000 字节。

• 更新 JavaScript 或 TypeScript 客户端代码，以启用 withStatefulReconnect 选项：

  const builder = new signalR.HubConnectionBuilder()
    .withUrl("/hubname")
    .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
  const connection = builder.build();
  

  bufferSize 选项是可选的，默认值为 100,000 字节。

• 更新 .NET 客户端代码以启用 WithStatefulReconnect 选项：

    var builder = new HubConnectionBuilder()
        .WithUrl("<hub url>")
        .WithStatefulReconnect();
    builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000);
    var hubConnection = builder.Build();
  

  StatefulReconnectBufferSize 选项是可选的，默认值为 100,000 字节。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，若要将序列化程序配置为使用“PascalCase”属性名称，而不是默认的 camelCase 名称，请使用以下代码 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();

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 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 中的 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 选项的选项：

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 诊断文档。

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，若要将序列化程序配置为使用“PascalCase”属性名称，而不是默认的 camelCase 名称，请使用以下代码 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();

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 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 中的 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 选项的选项：

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 诊断文档。

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 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 中的 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 选项的选项：

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 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 中的 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 选项的选项：

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 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 中的 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 选项的选项：

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

可以在服务器上使用 AddJsonProtocol 扩展方法来配置 JSON 序列化。 可将 AddJsonProtocol 添加到 AddSignalR 中的 Program.cs 之后。 AddJsonProtocol 方法采用接收 options 对象的委托。 该 PayloadSerializerOptions 对象的属性是一个 System.Text.JsonJsonSerializerOptions 对象，可用于配置参数和返回值的序列化。 有关详细信息，请参阅 System.Text.Json 文档。

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 Program.cs 中使用以下代码：

builder.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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 AddSignalR 中向 Program.cs 调用提供选项委托，为所有中心配置选项。

builder.Services.AddSignalR(hubOptions =>
{
    hubOptions.EnableDetailedErrors = true;
    hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});

单个集线器的选项将覆盖AddSignalR提供的全局选项，并且可以使用AddHubOptions进行配置。

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

高级 HTTP 配置选项

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

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

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

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

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台

JSON/MessagePack 序列化选项

ASP.NET Core SignalR 支持两种编码消息的协议： JSON 和 MessagePack。 各个协议都有可用于序列化的配置选项。

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

例如，要将序列化程序配置为不更改属性名称的大小写，但又不使用默认的大小写名称，请在 Program.cs 中使用以下代码：

builder.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();

切换到 Newtonsoft.Json

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

MessagePack 序列化选项

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

配置服务器选项

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

可以通过在 AddSignalR 中向 Program.cs 调用提供选项委托，为所有中心配置选项。

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

单个集线器的选项将覆盖AddSignalR提供的全局选项，并且可以使用AddHubOptions进行配置。

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

高级 HTTP 配置选项

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

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

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

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

长轮询传输提供可使用 LongPolling 属性配置的其他选项：

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

配置客户端选项

客户端选项可以在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 的值将设置记录的最低日志级别。 将记录此级别的或表中该级别后面列出的级别的消息。

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

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

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 值的按位 OR 来限制客户端仅使用指定的传输。 默认情况下，所有传输都处于启用状态。

例如，要禁用“服务器发送的事件”传输，但允许 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();

配置持有者身份验证

若要提供身份验证数据以及 SignalR 请求，请使用 AccessTokenProvider 选项（accessTokenFactory 在 JavaScript 中）指定返回所需访问令牌的函数。 在 .NET 客户端中，此访问令牌作为 HTTP“持有者身份验证”令牌传入（将 Authorization 标头与类型 Bearer一起使用）。 在 JavaScript 客户端中，访问令牌充当持有者令牌，除了少数浏览器 API 会限制标头应用能力的情况（特别是在“服务器发送的事件”和 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();

在 Java 客户端中 SignalR ，可以通过向 HttpHubConnectionBuilder 提供访问令牌工厂来配置持有者令牌以用于身份验证。 使用 withAccessTokenFactory 提供 RxJavaSingle<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 对象本身上，可以配置超时和保持活动行为的其他选项。

配置附加选项

可以在WithUrl的withUrl方法中（在 JavaScript 中为HubConnectionBuilder）或 Java 客户端中的HttpHubConnectionBuilder上的各种配置 API 中配置其他选项。

在 .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 客户端中，可以在提供给以下对象的 withUrlJavaScript 对象中提供这些选项：

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();

其他资源

• ASP.NET Core 入门 SignalR
• 在 ASP.NET Core 中使用集线器 SignalR
• ASP.NET Core SignalR JavaScript 客户端
• ASP.NET Core SignalR .NET 客户端
• 在 ASP.NET Core SignalR 中使用 MessagePack 中心协议
• ASP.NET Core SignalR 支持的平台