ASP.NET Core SignalR の構成

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Program.cs 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでProgram.cs呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでProgram.csにデリゲートを渡すことによって構成されます。

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプション:

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

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

await builder.StartAsync();

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

ステートフルな再接続を構成する

SignalR ステートフル再接続を使用すると、ネットワーク接続の切り替え時や短時間のアクセス不能時など、ネットワーク接続が一時的に切断されたクライアントが検知するダウンタイムが短縮されます。

ステートフル再接続は、次の方法でこれを実現します。

• サーバーとクライアント上のデータを一時的にバッファリングする。
• サーバーとクライアントの両方で受信したメッセージの確認 (ACK- ing)。
• 接続が稼働していることを認識し、接続が停止している間に送信された可能性のあるメッセージを再生します。

ステートフル 再接続は、.NET 8 以降で使用できます。

サーバー ハブ エンドポイントとクライアントの両方でステートフル再接続を選択します:

• サーバー ハブ エンドポイントの構成を更新して、AllowStatefulReconnects オプションを有効にします。

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

  必要に応じて、サーバーで許可される最大バッファー サイズ (バイト単位) をグローバルに設定することも、StatefulReconnectBufferSize オプションを使用して特定のハブに対して設定することもできます:

  StatefulReconnectBufferSize オプションのグローバル設定:

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

  特定のハブに対して設定されたStatefulReconnectBufferSizeオプション

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

  StatefulReconnectBufferSize オプションは省略可能で、既定値は 100,000 バイトです。

• JavaScript または TypeScript クライアント コードを更新して、withStatefulReconnect オプションを有効にします:

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

  bufferSize オプションは省略可能で、既定値は 100,000 バイトです。

• .NET クライアント コードを更新して、WithStatefulReconnect オプションを有効にします:

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

  StatefulReconnectBufferSize オプションは省略可能で、既定値は 100,000 バイトです。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 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 クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定の キャメル ケース 名ではなく、"PascalCase" プロパティ名を使用するようにシリアライザーを構成するには、 Startup.ConfigureServicesで次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでStartup.ConfigureServices呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでStartup.Configureにデリゲートを渡すことによって構成されます。

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

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 withUrlに提供される JavaScript オブジェクトで指定できます。

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

Java クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定の キャメル ケース 名ではなく、"PascalCase" プロパティ名を使用するようにシリアライザーを構成するには、 Startup.ConfigureServicesで次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでStartup.ConfigureServices呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでStartup.Configureにデリゲートを渡すことによって構成されます。

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

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 withUrlに提供される JavaScript オブジェクトで指定できます。

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

Java クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Startup.ConfigureServices 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでStartup.ConfigureServices呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでStartup.Configureにデリゲートを渡すことによって構成されます。

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

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 withUrlに提供される JavaScript オブジェクトで指定できます。

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

Java クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Startup.ConfigureServices 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでStartup.ConfigureServices呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでStartup.Configureにデリゲートを渡すことによって構成されます。

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

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 withUrlに提供される JavaScript オブジェクトで指定できます。

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

Java クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Startup.ConfigureServices 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでStartup.ConfigureServices呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでStartup.Configureにデリゲートを渡すことによって構成されます。

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

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 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 クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Program.cs 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでProgram.cs呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでProgram.csにデリゲートを渡すことによって構成されます。

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 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 クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム

JSON/MessagePack シリアル化オプション

ASP.NET Core SignalR では、メッセージをエンコードするための 2 つのプロトコル ( JSON と MessagePack) がサポートされています。 各プロトコルには、シリアル化構成オプションがあります。

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

たとえば、既定のキャメル ケースの名前ではなく、プロパティ名の大文字と小文字の区別を変更しないようにシリアライザーを構成するには、Program.cs 内で次のコードを使用します。

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

.NET クライアントでは、同じ AddJsonProtocol 拡張メソッドが HubConnectionBuilderに存在します。 拡張メソッドを解決するには、 Microsoft.Extensions.DependencyInjection 名前空間をインポートする必要があります。

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

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

Newtonsoft.Json に切り替える

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

MessagePack シリアル化オプション

MessagePack シリアル化は、 AddMessagePackProtocol 呼び出しにデリゲートを提供することで構成できます。 詳細については、SignalRの MessagePack を参照してください。

サーバー オプションを構成する

次の表では、 SignalR ハブを構成するためのオプションについて説明します。

AddSignalRでProgram.cs呼び出しに委任するオプションを指定することで、すべてのハブに対してオプションを構成できます。

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

単一ハブのオプションは、 AddSignalR で提供されるグローバル オプションをオーバーライドし、 AddHubOptionsを使用して構成できます。

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

高度な HTTP 構成オプション

HttpConnectionDispatcherOptionsを使用して、トランスポートとメモリ バッファーの管理に関連する詳細設定を構成します。 これらのオプションは、MapHubでProgram.csにデリゲートを渡すことによって構成されます。

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

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

次の表では、ASP.NET Core SignalR の高度な HTTP オプションを構成するためのオプションについて説明します。

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

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

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

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

ログ記録の構成

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

たとえば、コンソールのログ記録を有効にするには、 Microsoft.Extensions.Logging.Console NuGet パッケージをインストールします。 AddConsole拡張メソッドを呼び出します。

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

JavaScript クライアントには、同様の configureLogging メソッドが存在します。 生成するログ メッセージの最小レベルを示す LogLevel 値を指定します。 ログはブラウザー コンソール ウィンドウに書き込まれます。

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

LogLevel値の代わりに、ログ レベル名を表すstring値を指定することもできます。 これは、SignalR定数にアクセスできない環境でLogLevelログ記録を構成する場合に便利です。

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

次の表に、使用可能なログ レベルを示します。 configureLoggingに指定する値は、ログに記録される最小ログ レベルを設定します。 このレベルでログに記録されたメッセージ 、またはテーブルの後に一覧表示されているレベルがログに記録されます。

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

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

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

依存関係のログ記録を構成しない場合、SLF4J は、次の警告メッセージを含む既定の操作なしロガーを読み込みます。

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

これは無視しても問題ありません。

許可されるトランスポートを構成する

SignalRによって使用されるトランスポートは、WithUrl呼び出し (JavaScript のwithUrl) で構成できます。 HttpTransportTypeの値のビットごとの OR を使用して、指定されたトランスポートのみを使用するようにクライアントを制限できます。 既定では、すべてのトランスポートが有効になっています。

たとえば、Server-Sent イベント トランスポートを無効にし、WebSocket 接続と Long Polling 接続を許可するには、次のようにします。

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

JavaScript クライアントでは、トランスポートは、transportに指定された options オブジェクトの withUrl フィールドを設定することによって構成されます。

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

このバージョンの Java クライアント WebSocket は、使用可能な唯一のトランスポートです。

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

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

ベアラー認証を構成する

SignalR要求と共に認証データを提供するには、AccessTokenProvider オプション (JavaScript のaccessTokenFactory) を使用して、目的のアクセス トークンを返す関数を指定します。 .NET クライアントでは、このアクセス トークンは HTTP "ベアラー認証" トークンとして渡されます (Authorization型の Bearer ヘッダーを使用)。 JavaScript クライアントでは、アクセス トークンはベアラー トークンとして使用されます。 ただし、ブラウザー API によってヘッダーを適用する機能が制限されるケースがいくつかあります (具体的には、Server-Sent イベントと WebSockets 要求)。 このような場合、アクセス トークンはクエリ文字列値 access_tokenとして提供されます。

.NET クライアントでは、AccessTokenProviderの options デリゲートを使用して、WithUrl オプションを指定できます。

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

JavaScript クライアントでは、アクセス トークンは、accessTokenFactoryの options オブジェクトに withUrl フィールドを設定することによって構成されます。

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

SignalR Java クライアントでは、HttpHubConnectionBuilder にアクセス トークン ファクトリを提供することで、認証に使用するベアラー トークンを構成できます。 withAccessTokenFactory を使用して RxJavaSingle<String> を指定します。 Single.defer を呼び出すと、クライアントのアクセス トークンを生成するロジックを記述できます。

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

タイムアウトとキープアライブのオプションを構成する

タイムアウトとキープアライブ動作を構成するための追加のオプションは、 HubConnection オブジェクト自体で使用できます。

追加のオプションの構成

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

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

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

JavaScript クライアントでは、次のオプションを、 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 クライアントでは、これらのオプションは、HttpHubConnectionBuilder から返される HubConnectionBuilder.create("HUB URL") でメソッドを使用して構成できます。

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

その他のリソース

• ASP.NET Core の概要 SignalR
• ASP.NET Core でハブを使用する SignalR
• ASP.NET Core SignalR JavaScript クライアント
• ASP.NET Core SignalR .NET クライアント
• ASP.NET Core の SignalR で MessagePack Hub Protocol を使用する
• ASP.NET Core SignalR でサポートされているプラットフォーム