次の方法で共有


ASP.NET Core SignalR の構成

この記事では、ASP.NET Core SignalR の構成について説明します。

この記事のガイダンスに追加されるまたは優先する BlazorSignalR のガイダンスについては、「ASP.NET Core BlazorSignalR ガイダンス」をご覧ください。

JSON または MessagePack のシリアル化オプション

ASP.NET Core SignalR は、メッセージをエンコードするために JSONMessagePack の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。
MaximumParallelInvocationsPerClient 1 キューに入れる前に各クライアントから並列で呼び出すことができるハブ メソッドの最大数。
DisableImplicitFromServicesParameters false ハブ メソッドの引数は、可能であれば DI から解決されます。

オプションは、Program.cs 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できますが、メモリ消費が増加する可能性があります。
TransportMaxBufferSize 64 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。
MinimumProtocolVersion 0 ネゴシエート プロトコルの最小バージョンを指定します。 これは、クライアントを新しいバージョンに制限するために使用します。
CloseOnAuthenticationExpiration false このオプションを設定すると、トークンの有効期限が切れたときに接続を閉じる認証有効期限追跡が有効になります。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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) 値の 2 倍以上の数値です。
HandshakeTimeout 15 秒 初期サーバー ハンドシェイクのタイムアウト。HubConnection オブジェクト自体で利用できます。 この間隔以内にサーバーからハンドシェイク応答を送信しない場合、クライアントによって、ハンドシェイクが取り消され、Closedイベント (JavaScript の場合は onclose) がトリガーされます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
WithKeepAliveInterval 15 秒 クライアントから ping メッセージを送信する間隔を決定します。HubConnectionBuilder に直接設定します。 この設定により、サーバーでハードの切断を検出できます。たとえば、クライアントがコンピューターをネットワークから取り外したときなどです。 クライアントからメッセージを送信すると、タイマーが間隔の開始にリセットされます。 サーバーに設定されている ClientTimeoutInterval 以内にクライアントからメッセージを送信しない場合、サーバーによって、クライアントが切断されたと見なされます。

.NET クライアントでは、タイムアウト値は TimeSpan 値として指定します。

次の例では、既定値の 2 倍の値を示します。

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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。
ApplicationMaxBufferSize 1 MB バックプレッシャを適用する前にクライアントによってバッファー処理され、サーバーで受信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できるようになりますが、メモリ消費量が増加する可能性があります。
TransportMaxBufferSize 1 MB バックプレッシャを観測する前にクライアントによってバッファー処理され、ユーザー アプリケーションから送信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。

.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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

JSON シリアル化は、AddJsonProtocol 拡張メソッドを使用してサーバー上に構成でき、このメソッドは Startup.ConfigureServices メソッド内の AddSignalR の後に追加できます。 AddJsonProtocol メソッドは、options オブジェクトを受け取るデリゲートを取ります。 そのオブジェクトの PayloadSerializerSettings プロパティは、引数と戻り値のシリアル化の構成に使用できる Json.NET JsonSerializerSettings オブジェクトです。 詳細については、Json.NET のドキュメントを参照してください。

たとえば、既定のキャメル ケースの名前ではなく、"パスカル ケース" プロパティを使用するようにシリアライザーを構成するには、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();

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。

オプションは、Startup.ConfigureServices 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
TransportMaxBufferSize 32 KB サーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはより大きなメッセージを送信できますが、メモリ消費に悪影響を与える可能性があります。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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();

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
HandshakeTimeout 15 秒 初期サーバー ハンドシェイクのタイムアウト。 この間隔以内にサーバーからハンドシェイク応答を送信しない場合、クライアントによって、ハンドシェイクが取り消され、Closedイベント (JavaScript の場合は onclose) がトリガーされます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。

.NET クライアントでは、タイムアウト値は TimeSpan 値として指定します。

追加のオプションの構成

追加オプションは、HubConnectionBuilderWithUrl (JavaScript の場合は withUrl) メソッド、または Java クライアントの HttpHubConnectionBuilder のさまざまな構成 API で構成できます。

.NET オプション 既定値 説明
AccessTokenProvider null HTTP 要求でベアラー認証トークンとして提供される文字列を返す関数。
SkipNegotiation false ネゴシエーション手順をスキップするには、これを true に設定します。 WebSocket トランスポートが唯一有効なトランスポートである場合にのみサポートされます。 この設定は、Azure SignalR サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。

.NET クライアントでは、これらのオプションは、WithUrl に指定するオプション デリゲートで変更できます。

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

JavaScript クライアントでは、これらのオプションは、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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

JSON シリアル化は、AddJsonProtocol 拡張メソッドを使用してサーバー上に構成でき、このメソッドは Startup.ConfigureServices メソッド内の AddSignalR の後に追加できます。 AddJsonProtocol メソッドは、options オブジェクトを受け取るデリゲートを取ります。 そのオブジェクトの PayloadSerializerSettings プロパティは、引数と戻り値のシリアル化の構成に使用できる Json.NET JsonSerializerSettings オブジェクトです。 詳細については、Json.NET のドキュメントを参照してください。

たとえば、既定のキャメル ケースの名前ではなく、"パスカル ケース" プロパティを使用するようにシリアライザーを構成するには、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();

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。

オプションは、Startup.ConfigureServices 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
TransportMaxBufferSize 32 KB サーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはより大きなメッセージを送信できますが、メモリ消費に悪影響を与える可能性があります。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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();

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。

.NET クライアントでは、これらのオプションは、WithUrl に指定するオプション デリゲートで変更できます。

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

JavaScript クライアントでは、これらのオプションは、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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 この値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。

オプションは、Startup.ConfigureServices 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより迅速に受信できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
TransportMaxBufferSize 32 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより迅速にバッファーできますが、メモリ消費が増加する可能性があります。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。

.NET クライアントでは、これらのオプションは、WithUrl に指定するオプション デリゲートで変更できます。

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

JavaScript クライアントでは、これらのオプションは、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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 この値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。

オプションは、Startup.ConfigureServices 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより迅速に受信できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
TransportMaxBufferSize 32 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより迅速にバッファーできますが、メモリ消費が増加する可能性があります。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。
MinimumProtocolVersion 0 ネゴシエート プロトコルの最小バージョンを指定します。 これは、クライアントを新しいバージョンに制限するために使用します。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。

.NET クライアントでは、これらのオプションは、WithUrl に指定するオプション デリゲートで変更できます。

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

JavaScript クライアントでは、これらのオプションは、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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 この値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。
MaximumParallelInvocationsPerClient 1 キューに入れる前に各クライアントから並列で呼び出すことができるハブ メソッドの最大数。

オプションは、Startup.ConfigureServices 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより迅速に受信できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
TransportMaxBufferSize 32 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより迅速にバッファーできますが、メモリ消費が増加する可能性があります。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。
MinimumProtocolVersion 0 ネゴシエート プロトコルの最小バージョンを指定します。 これは、クライアントを新しいバージョンに制限するために使用します。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。

.NET クライアントでは、これらのオプションは、WithUrl に指定するオプション デリゲートで変更できます。

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

JavaScript クライアントでは、これらのオプションは、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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 この値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。
MaximumParallelInvocationsPerClient 1 キューに入れる前に各クライアントから並列で呼び出すことができるハブ メソッドの最大数。

オプションは、Program.cs 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できますが、メモリ消費が増加する可能性があります。
TransportMaxBufferSize 64 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。
MinimumProtocolVersion 0 ネゴシエート プロトコルの最小バージョンを指定します。 これは、クライアントを新しいバージョンに制限するために使用します。
CloseOnAuthenticationExpiration false このオプションを設定すると、トークンの有効期限が切れたときに接続を閉じる認証有効期限追跡が有効になります。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。
ApplicationMaxBufferSize 1 MB バックプレッシャを適用する前にクライアントによってバッファー処理され、サーバーで受信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できるようになりますが、メモリ消費量が増加する可能性があります。
TransportMaxBufferSize 1 MB バックプレッシャを観測する前にクライアントによってバッファー処理され、ユーザー アプリケーションから送信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。

.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 の 2 つのプロトコルをサポートしています。 それぞれのプロトコルにシリアル化構成オプションが用意されています。

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

Note

現時点では、JavaScript クライアントで JSON シリアル化を構成することはできません。

Newtonsoft.Json に切り替える

System.Text.Json でサポートされていない Newtonsoft.Json の機能が必要な場合は、「Newtonsoft.Json に切り替える」を参照してください。

MessagePack シリアル化オプション

MessagePack シリアル化は、AddMessagePackProtocol 呼び出しにデリゲートを指定することで構成できます。 詳細については、SignalR の MessagePack に関する記事をご覧ください。

Note

現時点では、JavaScript クライアントで MessagePack シリアル化を構成することはできません。

サーバー オプションの構成

次の表に、SignalR ハブを構成するためのオプションを示します。

オプション 既定値 説明
ClientTimeoutInterval 30 秒 この間隔以内にメッセージ (キープアライブを含む) を受信しない場合、サーバーによって、クライアントが切断されたと見なされます。 この実装方法により、クライアントが切断済みとしてマークされるまでに、このタイムアウト間隔よりも長い時間がかかる可能性があります。 推奨される値は、KeepAliveInterval 値の 2 倍です。
HandshakeTimeout 15 秒 この時間間隔内にクライアントから最初のハンドシェイク メッセージが送信されない場合、接続は閉じられます。 これは詳細設定であり、ネットワーク待ち時間が長いことが原因でハンドシェイク タイムアウト エラーが発生している場合にのみ変更する必要があります。 ハンドシェイク プロセスの詳細については、SignalR ハブ プロトコルの仕様を参照してください。
KeepAliveInterval 15 秒 この間隔以内にサーバーからメッセージが送信されない場合、接続の開いた状態を保つために ping メッセージが自動的に送信されます。 KeepAliveInterval を変更する場合は、クライアントで ServerTimeout または serverTimeoutInMilliseconds の設定を変更します。 推奨される ServerTimeout または serverTimeoutInMilliseconds の値は、KeepAliveInterval 値の 2 倍です。
SupportedProtocols インストールされているすべてのプロトコル このハブでサポートされているプロトコル。 既定では、サーバーに登録されているすべてのプロトコルが許可されます。 この一覧からプロトコルを削除すると、個々のハブに対して特定のプロトコルを無効にできます。
EnableDetailedErrors false true にすると、Hub メソッドで例外がスローされたときに、詳細な例外メッセージがクライアントに返されます。 これらの例外メッセージには機密情報が含まれる可能性があるため、既定値は false です。
StreamBufferCapacity 10 クライアント アップロード ストリーム用にバッファー処理できる項目の最大数。 この制限に達すると、ストリーム項目がサーバーによって処理されるまで、呼び出しの処理がブロックされます。
MaximumReceiveMessageSize 32 KB 1 つの受信ハブ メッセージの最大サイズ。 この値を大きくすると、サービス拒否 (DoS) 攻撃のリスクが高まるおそれがあります。
MaximumParallelInvocationsPerClient 1 キューに入れる前に各クライアントから並列で呼び出すことができるハブ メソッドの最大数。
DisableImplicitFromServicesParameters false ハブ メソッドの引数は、可能であれば DI から解決されます。

オプションは、Program.cs 内の AddSignalR 呼び出しにオプションのデリゲートを指定することで、すべてのハブに対して構成できます。

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

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 バックプレッシャを適用する前にサーバーによってバッファー処理され、クライアントで受信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できますが、メモリ消費が増加する可能性があります。
TransportMaxBufferSize 64 KB バックプレッシャを観測する前にサーバーによってバッファー処理され、アプリから送信される最大バイト数。 この値を大きくすると、サーバーはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。
AuthorizationData Hub クラスに適用される Authorize 属性から自動的に収集されるデータ。 クライアントがハブに接続する権限を持っているかどうかを判断するために使用される IAuthorizeData オブジェクトの一覧。
Transports すべてのトランスポートが有効になっています。 クライアントが接続に使用できるトランスポートを制限できる HttpTransportType 値のビット フラグ列挙型。
LongPolling 後の説明をご覧ください。 Long Polling トランスポートに固有の追加オプション。
WebSockets 後の説明をご覧ください。 WebSocket トランスポートに固有の追加オプション。
MinimumProtocolVersion 0 ネゴシエート プロトコルの最小バージョンを指定します。 これは、クライアントを新しいバージョンに制限するために使用します。
CloseOnAuthenticationExpiration false このオプションを設定すると、トークンの有効期限が切れたときに接続を閉じる認証有効期限追跡が有効になります。

Long Polling トランスポートには、LongPolling プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
PollTimeout 90 秒 1 つのポーリング要求を終了する前に、サーバーが、クライアントにメッセージが送信するのを待機する最大時間。 この値を小さくすると、クライアントで新しいポーリング要求がより頻繁に発行されるようになります。

WebSocket トランスポートには、WebSockets プロパティを使用して構成できる追加オプションが用意されています。

オプション 既定値 説明
CloseTimeout 5 秒 サーバーが閉じた後、この時間間隔内にクライアントが閉じない場合、接続は終了します。
SubProtocolSelector null Sec-WebSocket-Protocol ヘッダーをカスタム値に設定するために使用できるデリゲート。 このデリゲートは、クライアントから要求された値を入力として受け取り、目的の値を返すことが期待されます。

クライアント オプションを構成する

クライアント オプションは、HubConnectionBuilder の種類で構成できます (.NET および JavaScript クライアントで使用できます)。 これは Java クライアントでも使用できますが、HttpHubConnectionBuilder サブクラスは、ビルダー構成オプションが含まれ、HubConnection 自体にもあります。

ログの構成

ログは、ConfigureLogging メソッドを使用して .NET クライアントに構成します。 ログ プロバイダーおよびフィルターは、サーバー上と同じ方法で登録できます。 詳細については、ASP.NET Core のログのドキュメントをご覧ください。

Note

ログ プロバイダーを登録するには、必要なパッケージをインストールする必要があります。 完全な一覧については、ドキュメントの「組み込みのログ プロバイダー」セクションを参照してください。

たとえば、コンソールのログを有効にするには、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 値を指定することもできます。 これは、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

Note

ログを完全に無効にするには、configureLogging メソッドで signalR.LogLevel.None を指定します。

ログの詳細については、SignalR 診断に関するドキュメントを参照してください。

SignalR Java クライアントでは、SLF4J ライブラリがログに使用されます。 これは高レベルのログ API であり、このライブラリのユーザーは、特定のログの依存関係を導入することで独自の特定のログの実装を選択できます。 次のコード スニペットは、SignalR Java クライアントで java.util.logging を使用する方法を示しています。

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 を使用すると、指定したトランスポートのみを使用するようにクライアントを制限できます。 すべてのトランスポートは既定で有効になっています。

たとえば、Server-Sent Events トランスポートを無効にし、WebSocket と Long Polling の接続を許可するには、次のコマンドを実行します。

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 クライアントでは、WebSocket が、使用可能な唯一のトランスポートです。

Java クライアントでは、トランスポートは、HttpHubConnectionBuilderwithTransport メソッドを使用して選択します。 Java クライアントでは、既定で WebSocket トランスポートが使用されます。

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

Note

SignalR Java クライアントでは、トランスポート フォールバックはまだサポートされていません。

ベアラー認証の構成

認証データを SignalR 要求と共に提供するには、AccessTokenProvider オプション (JavaScript の場合は accessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (型が BearerAuthorization ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。ただし、ブラウザー API によってヘッダーを適用する機能が制限されている場合 (具体的には、Server-Sent Events および 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 クライアントでは、アクセス トークンは、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 値の 2 倍以上の数値です。
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 サービスを使用する場合は有効にできません。
ClientCertificates Empty 認証要求に送信する TLS 証明書のコレクション。
Cookies Empty HTTP 要求ごとに送信する HTTP Cookie のコレクション。
Credentials Empty HTTP 要求ごとに送信する資格情報。
CloseTimeout 5 秒 WebSocket のみ。 サーバーで終了要求を確認できるように、終了後にクライアントで待機する最大時間。 この時間内にサーバーで終了が確認されない場合、クライアントは切断されます。
Headers Empty HTTP 要求ごとに送信する追加の HTTP ヘッダーのマップ。
HttpMessageHandlerFactory null HTTP 要求の送信に使用される HttpMessageHandler を構成または置換するために使用できるデリゲート。 WebSocket 接続には使用されません。 このデリゲートでは、null 以外の値を返す必要があり、パラメーターとして既定値を受け取ります。 その既定値の設定を変更して返すか、新しい HttpMessageHandler インスタンスを返します。 ハンドラーを置き換える場合は、指定されたハンドラーから保持する設定をコピーしてください。そうしないと、構成されたオプション (Cookie やヘッダーなど) が新しいハンドラーに適用されません。
Proxy null HTTP 要求を送信するときに使用する HTTP プロキシ。
UseDefaultCredentials false このブール値は、HTTP および WebSocket 要求の既定の資格情報を送信するために設定します。 これにより、Windows 認証を使用できるようになります。
WebSocketConfiguration null 追加の WebSocket オプションを構成するために使用できるデリゲート。 オプションの構成に使用できる ClientWebSocketOptions のインスタンスを受け取ります。
ApplicationMaxBufferSize 1 MB バックプレッシャを適用する前にクライアントによってバッファー処理され、サーバーで受信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを適用せずに、より大きなメッセージをより高速に受信できるようになりますが、メモリ消費量が増加する可能性があります。
TransportMaxBufferSize 1 MB バックプレッシャを観測する前にクライアントによってバッファー処理され、ユーザー アプリケーションから送信される最大バイト数。 この値を大きくすると、クライアントはバックプレッシャを待たずに、より大きなメッセージをより高速にバッファー処理できますが、メモリ消費が増加する可能性があります。

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

その他のリソース