Azure SignalR Service を使用する
この記事では、アプリ サーバーで SignalR を使用しているときに、アプリ サーバー側で SDK を使用して SignalR Service に接続する方法について説明します。
Azure SignalR Service のインスタンスを作成する
「クイックスタート: ARM テンプレートを使用して Azure SignalR Service をデプロイする」に従って、SignalR Service インスタンスを作成します。
ASP.NET Core SignalR の場合
SDK のインストール
コマンドを実行して、SignalR Service SDK を ASP.NET Core プロジェクトにインストールします。
dotnet add package Microsoft.Azure.SignalR
Startup
クラスで、次のコード スニペットとして SignalR Service SDK を使用します。
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR()
.AddAzureSignalR();
}
public void Configure(IApplicationBuilder app)
{
app.UseEndpoints(routes =>
{
routes.MapHub<YourHubClass>("/path_for_your_hub");
});
}
接続文字列を構成する
アプリケーションで SignalR Service の接続文字列を構成するには、2 つの方法があります。
Azure:SignalR:ConnectionString
またはAzure__SignalR__ConnectionString
という名前で環境変数を設定します。- Azure App Service で、アプリケーション設定に配置します。
接続文字列を
AddAzureSignalR()
のパラメーターとして渡します。services.AddSignalR() .AddAzureSignalR("<replace with your connection string>");
または
services.AddSignalR() .AddAzureSignalR(options => options.ConnectionString = "<replace with your connection string>");
オプションの構成
Azure SignalR Service SDK を使用するときにカスタマイズできる、いくつかのオプション があります。
ConnectionString
- 既定値は、
web.config
ファイル内のAzure:SignalR:ConnectionString
connectionString
またはappSetting
です。 - 再構成することはできますが、値がハード コーディングされて "いない" ことを確認してください。
InitialHubServerConnectionCount
- 既定値は
5
です。 - このオプションは、アプリケーション サーバーと Azure SignalR Service の間のハブごとの接続の初期数を制御します。 通常は既定値で十分であるため、そのままにしておきます。 実行時に、SDK はパフォーマンス チューニングまたは負荷分散のために新しいサーバー接続を開始する場合があります。 クライアントの数が多い場合は、より多くの数を指定してスループットを向上させることができます。 たとえば、合計で 100,000 クライアントがある場合、接続数を
10
または15
に増やすことができます。
MaxHubServerConnectionCount
- 既定値は
null
です。 - このオプションは、アプリケーション サーバーと Azure SignalR Service の間でハブごとに許可される最大接続数を制御します。 実行時に、SDK はパフォーマンス チューニングまたは負荷分散のために新しいサーバー接続を開始する場合があります。 既定では、必要に応じて新しいサーバー接続が開始されます。 許可される最大サーバー接続数が構成されている場合、サーバー接続数が制限に達しても、SDK は新しい接続を開始しません。
ApplicationName
- 既定値は
null
です。 - このオプションは、同じハブ名を含む異なるアプリ サーバーで同じ Azure SignalR インスタンスを共有する場合に便利です。 設定されていない場合、接続されているすべてのアプリ サーバーは同じアプリケーションのインスタンスと見なされます。
ClaimsProvider
- 既定値は
null
です。 - このオプションは、クライアント接続に関連付ける要求を制御します。
これは、Service SDK がクライアントのネゴシエート要求でクライアントのアクセス トークンを生成するときに使用されます。
既定では、ネゴシエートされた要求の
HttpContext.User
からのすべての要求が予約されます。 これらにはHub.Context.User
でアクセスできます。 - 通常、このオプションはそのままにする必要があります。 カスタマイズする前に、何が起こるかを理解するようにしてください。
AccessTokenLifetime
- 既定値は
1 hour
です。 - このオプションは、サービス SDK がクライアントごとに生成するアクセス トークンの有効な有効期間を制御します。 アクセス トークンは、クライアントのネゴシエート要求に対する応答で返されます。
ServerSentEvent
またはLongPolling
をトランスポートとして使用すると、有効期限が切れた後に認証エラーのため、クライアント接続が閉じられます。 クライアントの切断を回避するために、この値を増やすことができます。
AccessTokenAlgorithm
- 既定値は
HS256
です - このオプションでは、アクセス トークンを生成するときに
SecurityAlgorithms
を選択できます。 サポートされている省略可能な値がHS256
とHS512
になりました。HS512
の方が安全ですが、生成されるトークンはHS256
を使用する場合よりも比較的長くなることに注意してください。
ServerStickyMode
- 既定値は
Disabled
です。 - このオプションは、サーバー スティッキーのモードを指定します。 最初にネゴシエートするサーバーにクライアントがルーティングされると、それをサーバー スティッキーと呼びます。
- 分散シナリオでは、複数のアプリ サーバーが 1 つの Azure SignalR インスタンスに接続されている可能性があります。 クライアント接続の内部に関するページで説明したように、クライアントは最初にアプリ サーバーとネゴシエートしてから、Azure SignalR にリダイレクトされて永続的な接続を確立します。 次に、Azure SignalR は、クライアントとサーバー間のデータのトランスポートに関するページで説明するように、クライアントにサービスを提供する 1 つのアプリ サーバーを検索します。
Disabled
に設定すると、クライアントはランダムなアプリ サーバーにルーティングされます。 一般に、アプリ サーバーは、このモードを使用するとクライアント接続が分散されます。 自分のシナリオが "ブロードキャスト" または "グループ送信" の場合は、この既定のオプションを使用するだけで十分です。Preferred
に設定すると、Azure SignalR は、他のコストやグローバル ルーティングが不要な方法で、クライアントが最初にネゴシエートするアプリ サーバーを検索しようとします。 これは、自分のシナリオが接続に送信*の場合に役立ちます。 "接続に送信" では、送信側と受信側が同じアプリ サーバーにルーティングされるときに、パフォーマンスが向上し、待機時間が短くなる可能性があります。Required
に設定すると、Azure SignalR は常に、クライアントが最初にネゴシエートするアプリ サーバーを検索しようとします。 このオプションは、一部のクライアント コンテキストがnegotiate
ステップからフェッチされ、メモリに格納され、Hub
内で使用される場合に便利です。 ただし、このオプションにはパフォーマンス上の欠点がある可能性があります。これは、Azure SignalR が、この特定のアプリ サーバーをグローバルに検索し、クライアントとサーバーの間でトラフィックをグローバルにルーティングし続けるために他の作業を行う必要があるためです。
GracefulShutdown
GracefulShutdown.Mode
- 既定値は
Off
です - このオプションは、アプリ サーバーが SIGINT (Ctrl + C キー) を受け取った後の動作を指定します。
WaitForClientsClose
に設定すると、サーバーを直ちに停止するのではなく、Azure SignalR Service から削除して、新しいクライアント接続がこのサーバーに割り当てられないようにします。MigrateClients
に設定すると、さらに、クライアント接続を別の有効なサーバーに移行しようとします。 移行は、メッセージが配信された後にのみトリガーされます。OnConnected
とOnDisconnected
は、接続が入出力に移行されるときにトリガーされます。IConnectionMigrationFeature
は、接続が入出力に移行されているかどうかを識別するのに役立ちます。- 詳細な使用方法については、サンプル コード を参照してください。
GracefulShutdown.Timeout
- 既定値は
30 seconds
です - このオプションは、クライアントが閉じられる、または移行されるのを待機する最も長い時間を指定します。
ServiceScaleTimeout
- 既定値は
5 minutes
です - このオプションは、少なくともオンライン クライアントに影響を与える動的スケーリング サービス エンドポイントを待機する最も長い時間を指定します。 通常、単一のアプリ サーバーとサービス エンドポイントの間の動的スケールは数秒で完了できますが、複数のアプリ サーバーと、ネットワーク ジッターを持つ複数のサービス エンドポイントがあり、クライアントの安定性を確保したい場合は、それに応じてこの値を構成できます。
MaxPollIntervalInSeconds
- 既定値は
5
です - このオプションでは、Azure SignalR Service で
LongPolling
接続に許可される最大ポーリング間隔を定義します。 次のポーリング要求がMaxPollIntervalInSeconds
内に来ない場合、Azure SignalR Service によってクライアント接続がクリーンアップされます。 - 値は
[1, 300]
に制限されます。
TransportTypeDetector
- 既定値: すべてのトランスポートが有効になっています。
- このオプションは、クライアントが HTTP 要求の送信に使用できるトランスポートをカスタマイズする関数を定義します。
HttpConnectionDispatcherOptions.Transports
の代わりに、このオプションを使用してトランスポートを構成します。
サンプル
上記のオプションは、次のサンプル コードのように構成できます。
services.AddSignalR()
.AddAzureSignalR(options =>
{
options.InitialHubServerConnectionCount = 10;
options.AccessTokenLifetime = TimeSpan.FromDays(1);
options.ClaimsProvider = context => context.User.Claims;
options.GracefulShutdown.Mode = GracefulShutdownMode.WaitForClientsClose;
options.GracefulShutdown.Timeout = TimeSpan.FromSeconds(10);
options.TransportTypeDetector = httpContext => AspNetCore.Http.Connections.HttpTransportType.WebSockets | AspNetCore.Http.Connections.HttpTransportType.LongPolling;
});
従来の ASP.NET SignalR の場合
Note
SignalR を初めて試す場合は、ASP.NET Core SignalR を使用することをお勧めします。これはシンプルで信頼性が高く、簡単に使用できます。
SDK のインストール
Package Manager コンソールを使用して、SignalR Service SDK を ASP.NET プロジェクトにインストールします。
Install-Package Microsoft.Azure.SignalR.AspNet
Startup
クラスで、次のコード スニペットとして SignalR Service SDK を使用し、MapSignalR()
を MapAzureSignalR({your_applicationName})
に置き換えます。 {YourApplicationName}
を自分のアプリケーションの名前に置き換えます。これは、このアプリケーションを他のアプリケーションと区別するための一意の名前です。 値として this.GetType().FullName
を使用することができます。
public void Configuration(IAppBuilder app)
{
app.MapAzureSignalR(this.GetType().FullName);
}
接続文字列を構成する
web.config
ファイルの接続文字列を connectionStrings
セクションに設定します。
<configuration>
<connectionStrings>
<add name="Azure:SignalR:ConnectionString" connectionString="Endpoint=...;AccessKey=..."/>
</connectionStrings>
...
</configuration>
オプションの構成
Azure SignalR Service SDK を使用するときにカスタマイズできる、いくつかのオプション があります。
ConnectionString
- 既定値は、
web.config
ファイル内のAzure:SignalR:ConnectionString
connectionString
またはappSetting
です。 - 再構成することはできますが、値がハード コーディングされて "いない" ことを確認してください。
InitialHubServerConnectionCount
- 既定値は
5
です。 - このオプションは、アプリケーション サーバーと Azure SignalR Service の間のハブごとの接続の初期数を制御します。 通常は既定値で十分であるため、そのままにしておきます。 実行時に、SDK はパフォーマンス チューニングまたは負荷分散のために新しいサーバー接続を開始する場合があります。 クライアントの数が多い場合は、より多くの数を指定してスループットを向上させることができます。 たとえば、合計で 100,000 クライアントがある場合、接続数を
10
または15
に増やすことができます。
MaxHubServerConnectionCount
- 既定値は
null
です。 - このオプションは、アプリケーション サーバーと Azure SignalR Service の間でハブごとに許可される最大接続数を制御します。 実行時に、SDK はパフォーマンス チューニングまたは負荷分散のために新しいサーバー接続を開始する場合があります。 既定では、必要に応じて新しいサーバー接続が開始されます。 許可される最大サーバー接続数が構成されている場合、サーバー接続数が制限に達しても、SDK は新しい接続を開始しません。
ApplicationName
- 既定値は
null
です。 - このオプションは、同じハブ名を含む異なるアプリ サーバーで同じ Azure SignalR インスタンスを共有する場合に便利です。 設定されていない場合、接続されているすべてのアプリ サーバーは同じアプリケーションのインスタンスと見なされます。
ClaimProvider
- 既定値は
null
です。 - このオプションは、クライアント接続に関連付ける要求を制御します。
これは、Service SDK がクライアントのネゴシエート要求でクライアントのアクセス トークンを生成するときに使用されます。
既定では、ネゴシエートされた要求の
IOwinContext.Authentication.User
からのすべての要求が予約されます。 - 通常、このオプションはそのままにする必要があります。 カスタマイズする前に、何が起こるかを理解するようにしてください。
AccessTokenLifetime
- 既定値は
1 hour
です。 - このオプションは、サービス SDK がクライアントごとに生成するアクセス トークンの有効な有効期間を制御します。 アクセス トークンは、クライアントのネゴシエート要求に対する応答で返されます。
ServerSentEvent
またはLongPolling
をトランスポートとして使用すると、有効期限が切れた後に認証エラーのため、クライアント接続が閉じられます。 クライアントの切断を回避するために、この値を増やすことができます。
AccessTokenAlgorithm
- 既定値は
HS256
です - このオプションでは、アクセス トークンを生成するときに
SecurityAlgorithms
を選択できます。 サポートされている省略可能な値がHS256
とHS512
になりました。HS512
の方が安全ですが、生成されるトークンはHS256
を使用する場合よりも比較的長くなることに注意してください。
ServerStickyMode
- 既定値は
Disabled
です。 - このオプションは、サーバー スティッキーのモードを指定します。 最初にネゴシエートするサーバーにクライアントがルーティングされると、それをサーバー スティッキーと呼びます。
- 分散シナリオでは、複数のアプリ サーバーが 1 つの Azure SignalR インスタンスに接続されている可能性があります。 クライアント接続の内部に関するページで説明したように、クライアントは最初にアプリ サーバーとネゴシエートしてから、Azure SignalR にリダイレクトされて永続的な接続を確立します。 次に、Azure SignalR は、クライアントとサーバー間のデータのトランスポートに関するページで説明するように、クライアントにサービスを提供する 1 つのアプリ サーバーを検索します。
Disabled
に設定すると、クライアントはランダムなアプリ サーバーにルーティングされます。 一般に、アプリ サーバーは、このモードを使用するとクライアント接続が分散されます。 自分のシナリオが "ブロードキャスト" または "グループ送信" の場合は、この既定のオプションを使用するだけで十分です。Preferred
に設定すると、Azure SignalR は、他のコストやグローバル ルーティングが不要な方法で、クライアントが最初にネゴシエートするアプリ サーバーを検索しようとします。 これは、自分のシナリオが接続に送信*の場合に役立ちます。 "接続に送信" では、送信側と受信側が同じアプリ サーバーにルーティングされるときに、パフォーマンスが向上し、待機時間が短くなる可能性があります。Required
に設定すると、Azure SignalR は常に、クライアントが最初にネゴシエートするアプリ サーバーを検索しようとします。 このオプションは、一部のクライアント コンテキストがnegotiate
ステップからフェッチされ、メモリに格納され、Hub
内で使用される場合に便利です。 ただし、このオプションにはパフォーマンス上の欠点がある可能性があります。これは、Azure SignalR が、この特定のアプリ サーバーをグローバルに検索し、クライアントとサーバーの間でトラフィックをグローバルにルーティングし続けるために他の作業を行う必要があるためです。
MaxPollIntervalInSeconds
- 既定値は
5
です - このオプションは、Azure SignalR Service で非アクティブな接続に許可される最大アイドル時間を定義します。 ASP.NET SignalR では、長いポーリング トランスポートの種類または再接続に適用されます。 次の
/reconnect
または/poll
要求がMaxPollIntervalInSeconds
内に来ない場合、Azure SignalR Service によってクライアント接続がクリーンアップされます。 - 値は
[1, 300]
に制限されます。
サンプル
上記のオプションは、次のサンプル コードのように構成できます。
app.Map("/signalr",subApp => subApp.RunAzureSignalR(this.GetType().FullName, new HubConfiguration(), options =>
{
options.InitialHubServerConnectionCount = 1;
options.AccessTokenLifetime = TimeSpan.FromDays(1);
options.ClaimProvider = context => context.Authentication?.User.Claims;
}));
アプリケーション サーバーのスケールアウト
Azure SignalR Service では、永続的な接続がアプリケーション サーバーからオフロードされるため、ハブ クラスでのビジネス ロジックの実装に集中できます。 ただし、大規模なクライアント接続を処理する場合は、パフォーマンスを向上させるためにアプリケーション サーバーをスケールアウトする必要があります。 アプリケーション サーバーをスケールアウトするためのヒントをいくつか次に示します。
- 複数のアプリケーション サーバーが同じ Azure SignalR Service インスタンスに接続できます。
- 同じハブ名を含む異なるアプリケーションで同じ Azure SignalR インスタンスを共有する場合は、異なる ApplicationName オプションで設定します。 設定されていない場合、接続されているすべてのアプリ サーバーは同じアプリケーションのインスタンスと見なされます。
- ApplicationName オプションとハブ クラスの名前が同じである限り、異なるアプリケーション サーバーからの接続は同じハブにグループ化されます。
- 各クライアント接続は、アプリケーション サーバーの 1 つにのみ作成され、そのクライアントからのメッセージはその同じアプリケーション サーバーにのみ送信されます。 (すべてのアプリケーション サーバーから) クライアント情報にグローバルにアクセスする場合は、一元化されたストレージを使用して、すべてのアプリケーション サーバーからのクライアント情報を保存する必要があります。
次のステップ
この記事では、アプリケーションで SignalR Service を使用する方法について説明します。 SignalR Service の詳細については、次の記事を参照してください。