共用方式為


ASP.NET Core SignalR 設定

本文涵蓋 ASP.NET Core SignalR 設定。

如需 BlazorSignalR 指導 (其會新增或取代本文中的指引),請參閱 ASP.NET Core BlazorSignalR 指導

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Startup.ConfigureServices 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊的風險。
MaximumParallelInvocationsPerClient 1 每個用戶端可在放入佇列之前平行呼叫的中樞方法數目上限。
DisableImplicitFromServicesParameters false 如果可能,則會從 DI 解析中樞方法引數。

Program.cs 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

 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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Program.cs 中將委派傳遞至 MapHub

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 選項的選項:

選項 預設值 說明
ApplicationMaxBufferSize 64 KB 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 64 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。
MinimumProtocolVersion 0 指定交涉通訊協定的最低版本。 這是用來將用戶端限制為較新版本。
CloseOnAuthenticationExpiration false 設定此選項以啟用驗證到期追蹤,而驗證到期追蹤將會在權杖到期時關閉連線。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 Single.defer,您可以撰寫邏輯來產生用戶端的存取權杖。

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

設定逾時和保持運作選項

設定逾時和保持運作行為的其他選項:

選項 預設值 說明
WithServerTimeout 30 秒 (30,000 毫秒) 伺服器活動的逾時,並且直接設定於 HubConnectionBuilder。 如果伺服器尚未在此間隔內傳送訊息,則用戶端會將伺服器視為已中斷連線,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器保持運作間隔 (WithKeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時,並且可以在 HubConnection 物件本身上使用。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
WithKeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔,並且直接設定於 HubConnectionBuilder。 此設定可讓伺服器偵測強制中斷連線的情況,例如用戶端拔除其電腦與網路的連線。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

下列範例顯示預設值兩倍的值:

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

設定具狀態重新連線

SignalR 具狀態重新連線可減少用戶端在網路連線中暫時中斷連線的感知停機時間,例如切換網路連線或短暫的存取中斷。

具狀態重新連線藉由以下方式達成此目的:

  • 暫時緩衝伺服器和用戶端上的資料。
  • 確認伺服器和用戶端都已接收到訊息 (ACK-ing)。
  • 辨識連線何時啟動,並在連線關閉時重新執行可能已傳送的訊息。

具狀態重新連線可在 ASP.NET Core 8.0 和更高版本中使用。

選擇在伺服器中樞端點和用戶端上進行具狀態重新連線:

  • 更新伺服器中樞端點組態以啟用 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 個位元組。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
UseDefaultCredentials false 將此布林值設定為傳送 HTTP 和 WebSockets 要求的預設認證。 這可讓您使用 Windows 驗證。
WebSocketConfiguration null 可用來設定其他 WebSocket 選項的委派。 接收可用來設定選項的 ClientWebSocketOptions 執行個體。
ApplicationMaxBufferSize 1 MB 套用 backpressure 之前,用戶端可緩衝處理之接收自伺服器的位元組數目上限。 增加此值可讓用戶端更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 1 MB 觀察到 backpressure 之前,用戶端可緩衝處理的使用者應用程式所傳送位元組數目上限。 增加此值可讓用戶端更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。

在 .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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定,而這可以新增至 Startup.ConfigureServices 方法中 AddSignalR 之後。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerSettings 屬性是 Json.NET JsonSerializerSettings 物件,而此物件可以用來設定引數和傳回值的序列化。 如需詳細資訊,請參閱 Json.NET 文件

例如,若要將序列化程式設定為使用 "PascalCase" 屬性名稱,而不是預設駝峰式大小寫名稱,請在 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 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。

Startup.ConfigureServices 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Startup.Configure 中將委派傳遞至 MapHub

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 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
TransportMaxBufferSize 32 KB 伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器傳送較大的訊息,但可能會對記憶體耗用量造成負面影響。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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

在 Java 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定,而這可以新增至 Startup.ConfigureServices 方法中 AddSignalR 之後。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerSettings 屬性是 Json.NET JsonSerializerSettings 物件,而此物件可以用來設定引數和傳回值的序列化。 如需詳細資訊,請參閱 Json.NET 文件

例如,若要將序列化程式設定為使用 "PascalCase" 屬性名稱,而不是預設駝峰式大小寫名稱,請在 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 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。

Startup.ConfigureServices 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Startup.Configure 中將委派傳遞至 MapHub

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 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
TransportMaxBufferSize 32 KB 伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器傳送較大的訊息,但可能會對記憶體耗用量造成負面影響。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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

在 Java 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Startup.ConfigureServices 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊風險。

Startup.ConfigureServices 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Startup.Configure 中將委派傳遞至 MapHub

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 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
TransportMaxBufferSize 32 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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

在 Java 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Startup.ConfigureServices 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊風險。

Startup.ConfigureServices 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Startup.Configure 中將委派傳遞至 MapHub

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 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
TransportMaxBufferSize 32 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
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 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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

在 Java 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Startup.ConfigureServices 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊風險。
MaximumParallelInvocationsPerClient 1 每個用戶端可在放入佇列之前平行呼叫的中樞方法數目上限。

Startup.ConfigureServices 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Startup.Configure 中將委派傳遞至 MapHub

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 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
TransportMaxBufferSize 32 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
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 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
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.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

在 JavaScript 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Program.cs 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊風險。
MaximumParallelInvocationsPerClient 1 每個用戶端可在放入佇列之前平行呼叫的中樞方法數目上限。

Program.cs 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Program.cs 中將委派傳遞至 MapHub

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 選項的選項:

選項 預設值 說明
ApplicationMaxBufferSize 64 KB 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 64 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。
MinimumProtocolVersion 0 指定交涉通訊協定的最低版本。 這是用來將用戶端限制為較新版本。
CloseOnAuthenticationExpiration false 設定此選項以啟用驗證到期追蹤,而驗證到期追蹤將會在權杖到期時關閉連線。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
UseDefaultCredentials false 將此布林值設定為傳送 HTTP 和 WebSockets 要求的預設認證。 這可讓您使用 Windows 驗證。
WebSocketConfiguration null 可用來設定其他 WebSocket 選項的委派。 接收可用來設定選項的 ClientWebSocketOptions 執行個體。
ApplicationMaxBufferSize 1 MB 套用 backpressure 之前,用戶端可緩衝處理之接收自伺服器的位元組數目上限。 增加此值可讓用戶端更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 1 MB 觀察到 backpressure 之前,用戶端可緩衝處理的使用者應用程式所傳送位元組數目上限。 增加此值可讓用戶端更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。

在 .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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源

JSON/MessagePack 序列化選項

ASP.NET Core SignalR 支援兩種可編碼訊息的通訊協定: JSONMessagePack。 每個通訊協定都會有序列化設定選項。

JSON 序列化可以使用 AddJsonProtocol 擴充方法在伺服器上進行設定。 AddJsonProtocol 可以新增至 Startup.ConfigureServices 中的 AddSignalR 後面。 AddJsonProtocol 方法會採用可接收 options 物件的委派。 該物件的 PayloadSerializerOptions 屬性是 System.Text.Json JsonSerializerOptions 物件,可用於設定引數和傳回值的序列化。 如需詳細資訊,請參閱 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();

注意

目前無法在 JavaScript 用戶端中設定 JSON 序列化。

切換至 Newtonsoft.Json

如果您需要 System.Text.Json 中不支援的 Newtonsoft.Json 功能,則請參閱切換至 Newtonsoft.Json

MessagePack 序列化選項

您可以提供 AddMessagePackProtocol 呼叫的委派,來設定 MessagePack 序列化。 如需詳細資料,請參閱 SignalR 中的 MessagePack

注意

目前無法在 JavaScript 用戶端中設定 MessagePack 序列化。

設定伺服器選項

下表描述用於設定 SignalR 中樞的選項:

選項 預設值 說明
ClientTimeoutInterval 30 秒 如果伺服器尚未在此間隔內收到訊息 (包括保持運作),則會將用戶端視為已中斷連線。 因這個作業的實作方式,將用戶端標記為已中斷連線所需的時間會比此逾時間隔還要久。 建議的值是 KeepAliveInterval 值的兩倍。
HandshakeTimeout 15 秒 如果用戶端未在此時間間隔內傳送初始交握訊息,則會關閉連線。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 如果伺服器未在此間隔內傳送訊息,則會自動傳送 Ping 訊息,以保持開啟連線。 變更 KeepAliveInterval 時,請變更用戶端上的 ServerTimeoutserverTimeoutInMilliseconds 設定。 建議的 ServerTimeoutserverTimeoutInMilliseconds 值是 KeepAliveInterval 值的兩倍。
SupportedProtocols 所有已安裝的通訊協定 此中樞所支援的通訊協定。 預設會允許伺服器上所註冊的所有通訊協定。 您可以從此清單中移除通訊協定,以停用個別中樞的特定通訊協定。
EnableDetailedErrors false 如果 true,則中樞方法中擲回例外狀況時,會將詳細的例外狀況訊息傳回給用戶端。 預設值是 false,因為這些例外狀況訊息可以包含敏感性資訊。
StreamBufferCapacity 10 可針對用戶端上傳資料流所緩衝處理的項目數上限。 如果達到此限制,則除非伺服器處理資料流項目,否則會封鎖叫用的處理。
MaximumReceiveMessageSize 32 KB 單一傳入中樞訊息的大小上限。 提高此值可能會增加拒絕服務 (DoS) 攻擊風險。
MaximumParallelInvocationsPerClient 1 每個用戶端可在放入佇列之前平行呼叫的中樞方法數目上限。
DisableImplicitFromServicesParameters false 如果可能,則會從 DI 解析中樞方法引數。

Program.cs 中將選項委派提供給 AddSignalR 呼叫,即可設定所有中樞的選項。

 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,以設定與傳輸和記憶體緩衝區管理相關的進階設定。 這些選項的設定方式是在 Program.cs 中將委派傳遞至 MapHub

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 選項的選項:

選項 預設值 說明
ApplicationMaxBufferSize 64 KB 套用 backpressure 之前,伺服器可緩衝處理之接收自用戶端的位元組數目上限。 增加此值可讓伺服器更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 64 KB 觀察到 backpressure 之前,伺服器可緩衝處理的應用程式所傳送位元組數目上限。 增加此值可讓伺服器更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。
AuthorizationData 從套用至中樞類別之 Authorize 屬性自動收集的資料。 IAuthorizeData 物件清單,用來判斷是否授權用戶端來連線至中樞。
Transports 會啟用所有傳輸。 HttpTransportType 值的位元旗標列舉,可限制用戶端可用來連線的傳輸。
LongPolling 請參閱下方 。 長輪詢傳輸特定的其他選項。
WebSockets 請參閱下方 。 WebSockets 傳輸特定的其他選項。
MinimumProtocolVersion 0 指定交涉通訊協定的最低版本。 這是用來將用戶端限制為較新版本。
CloseOnAuthenticationExpiration false 設定此選項以啟用驗證到期追蹤,而驗證到期追蹤將會在權杖到期時關閉連線。

長輪詢傳輸有其他選項,而這些選項可以使用 LongPolling 屬性進行設定:

選項 預設值 說明
PollTimeout 90 秒 終止單一輪詢要求之前,伺服器等待訊息傳送至用戶端的時間量上限。 減少此值會導致用戶端更頻繁地發出新的輪詢要求。

WebSocket 傳輸有其他選項,而這些選項可以使用 WebSockets 屬性進行設定:

選項 預設值 說明
CloseTimeout 5 秒鐘 伺服器關閉之後,如果無法在此時間間隔內關閉用戶端,則會終止連線。
SubProtocolSelector null 可用來將 Sec-WebSocket-Protocol 標頭設定為自訂值的委派。 委派會接收用戶端所要求的值以作為輸入,而且預期會傳回所需的值。

設定用戶端選項

您可以在 HubConnectionBuilder 類型 (可在 .NET 和 JavaScript 用戶端中使用) 上設定用戶端選項。 其也可以在 Java 用戶端中使用,但 HttpHubConnectionBuilder 子類別包含產生器設定選項,以及位於 HubConnection 本身。

設定記錄

使用 ConfigureLogging 方法,以在 .NET 用戶端中設定記錄。 記錄提供者和篩選的註冊方式可以與其在伺服器上的註冊方式相同。 如需詳細資訊,請參閱 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();

您也可以提供代表記錄層級名稱的 string 值,而不是 LogLevel 值。 在您無法存取 LogLevel 常數的環境中設定 SignalR 記錄時,這十分有用。

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

下表列出可用的記錄層級。 您提供給 configureLogging 的值會設定將要記錄的「最低」記錄層級。 將會記錄在此層級 (「或表格中在其後面所列出的層級」) 所記錄的訊息。

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

注意

若要完全停用記錄,請在 configureLogging 方法中指定 signalR.LogLevel.None

如需記錄的詳細資訊,請參閱 SignalR 診斷文件

SignalR Java 用戶端會使用 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 值的位元 OR 可以用來限制用戶端只能使用所指定的傳輸。 預設會啟用所有傳輸。

例如,停用「伺服器傳送的事件」傳輸,但允許 WebSockets 和長輪詢連線:

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

在 JavaScript 用戶端中,傳輸的設定方式是在提供給 withUrl 的選項物件上設定 transport 欄位:

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

在此版的 Java 用戶端中,Websockets 是唯一可用的傳輸。

在 Java 用戶端中,會使用 HttpHubConnectionBuilder 上的 withTransport 方法來選取傳輸。 Java 用戶端預設為使用 WebSockets 傳輸。

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

注意

SignalR Java 用戶端尚未支援傳輸後援。

設定持有人驗證

若要提供驗證資料以及 SignalR 要求,請使用 AccessTokenProvider 選項 (在 JavaScript 中,為 accessTokenFactory) 來指定可傳回所需存取權杖的函數。 在 .NET 用戶端中,會以 HTTP 「持有人驗證」權杖的形式傳入此存取權杖 (搭配使用 Authorization 標頭與 Bearer 類型)。 在 JavaScript 用戶端中,存取權杖會用作持有人權杖,但下列情況「除外」:瀏覽器 API 限制套用標頭的能力 (特別是在「伺服器傳送的事件」和 WebSockets 要求中)。 在這些情況下,會以查詢字串值 access_token 的形式來提供存取權杖。

在 .NET 用戶端中,可以使用 WithUrl 中的選項委派來指定 AccessTokenProvider 選項:

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

在 JavaScript 用戶端中,於 withUrl 中的選項物件上設定 accessTokenFactory 欄位,以設定存取權杖:

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>。 透過呼叫 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 事件 (在 JavaScript 中,為 onclose)。 此值必須夠大,才能從伺服器傳送 Ping 訊息,「而且」用戶端才能在逾時間隔內收到 Ping 訊息。 建議值至少是伺服器 (KeepAliveInterval) 值兩倍的數字,以允許 Ping 到達的時間。
HandshakeTimeout 15 秒 初始伺服器交握的逾時。 如果伺服器未在此間隔內傳送交握回應,則用戶端會取消交握,並觸發 Closed 事件 (在 JavaScript 中,為 onclose)。 只有在因嚴重網路延遲而發生交握逾時錯誤時,才應該修改此進階設定。 如需交握程序的詳細資料,請參閱 SignalR 中樞通訊協定規格
KeepAliveInterval 15 秒 決定用戶端傳送 Ping 訊息的間隔。 從用戶端傳送任何訊息都會將計時器重設為間隔的開始。 如果用戶端尚未在伺服器上所設定的 ClientTimeoutInterval 內傳送訊息,則伺服器會將用戶端視為已中斷連線。

在 .NET 用戶端中,會將逾時值指定為 TimeSpan 值。

設定其他選項

您可以在 HubConnectionBuilderWithUrl (在 JavaScript 中,為 withUrl) 方法中,或在 Java 用戶端中 HttpHubConnectionBuilder 的各種設定 API 上設定其他選項:

.NET 選項 預設值 說明
AccessTokenProvider null 傳回字串的函數,而此字串在 HTTP 要求中是作為持有人驗證權杖所提供。
SkipNegotiation false 將此設定為 true,以跳過交涉步驟。 只有在 WebSocket 傳輸是唯一啟用的傳輸時才支援。 使用 Azure SignalR Service 時,無法啟用此設定。
ClientCertificates 空的 要傳送至驗證要求的 TLS 憑證集合。
Cookies 空的 要與每個 HTTP 要求一起傳送的 HTTP 集合。
Credentials 空的 要與每個 HTTP 要求一起傳送的認證。
CloseTimeout 5 秒鐘 僅限 WebSockets。 用戶端在關閉後等待伺服器認可關閉要求的時間量上限。 如果伺服器未在此時間內認可關閉,則用戶端會中斷連線。
Headers 空的 要與每個 HTTP 要求一起傳送之其他 HTTP 標頭的對應。
HttpMessageHandlerFactory null 委派,可用來設定或取代用來傳送 HTTP 要求的 HttpMessageHandler。 不適用於 WebSocket 連線。 此委派必須傳回非 Null 值,而且會以參數形式接收預設值。 修改該預設值的設定並將其傳回,或傳回新的 HttpMessageHandler 執行個體。 取代處理常式時,請務必複製您想要從所提供的處理常式中保留的設定,否則,所設定的選項 (例如 Cookies 和標頭) 將不會套用至新的處理常式。
Proxy null 要在傳送 HTTP 要求時使用的 HTTP Proxy。
UseDefaultCredentials false 將此布林值設定為傳送 HTTP 和 WebSockets 要求的預設認證。 這可讓您使用 Windows 驗證。
WebSocketConfiguration null 可用來設定其他 WebSocket 選項的委派。 接收可用來設定選項的 ClientWebSocketOptions 執行個體。
ApplicationMaxBufferSize 1 MB 套用 backpressure 之前,用戶端可緩衝處理之接收自伺服器的位元組數目上限。 增加此值可讓用戶端更快速地接收較大的訊息,而不需要套用 backpressure,但會增加記憶體耗用量。
TransportMaxBufferSize 1 MB 觀察到 backpressure 之前,用戶端可緩衝處理的使用者應用程式所傳送位元組數目上限。 增加此值可讓用戶端更快速地緩衝處理較大的訊息,而不需要等待 backpressure,但會增加記憶體耗用量。

在 .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 用戶端中,可以在提供給 withUrl 的 JavaScript 物件中提供這些選項:

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 用戶端中,可以使用 HubConnectionBuilder.create("HUB URL") 所傳回 HttpHubConnectionBuilder 上的方法來設定這些選項

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

其他資源