Azure SignalR Service を使用する

[アーティクル]
12/16/2024

この記事では、アプリサーバーで SignalR を使用しているときに、アプリサーバー側で SDK を使用して SignalR Service に接続する方法について説明します。

重要

この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。

接続文字列には、アプリケーションが Azure SignalR Service にアクセスするために必要な認可情報が含まれています。接続文字列内のアクセスキーは、サービスのルートパスワードに似ています。運用環境では、常にアクセスキーを保護してください。 Azure Key Vault を使用してキーの管理とローテーションを安全に行い、Microsoft Entra ID を使用して接続文字列をセキュリティで保護し、Microsoft Entra ID を使用してアクセスを認可します。

アクセスキーを他のユーザーに配布したり、ハードコーディングしたり、他のユーザーがアクセスできるプレーンテキストで保存したりしないでください。キーが侵害された可能性があると思われる場合は、キーをローテーションしてください。

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");
    });
}

接続文字列を構成する

この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。運用環境では、常にアクセスキーを保護してください。 Azure Key Vault を使用してキーの管理とローテーションを安全に行い、Microsoft Entra ID を使用して接続文字列をセキュリティで保護し、Microsoft Entra ID を使用してアクセスを認可します。

アプリケーションで 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 の代わりに、このオプションを使用してトランスポートを構成します。

`AllowStatefulReconnects`

既定値は null です
このオプションでは、すべてのハブのステートフル再接続を有効または無効にします。
null の場合、SDK はハブ設定を読み取ります。
true の場合、Azure SignalR Service は宣言されたすべてのハブでステートフル再接続を有効にします。また、クライアントは、クライアント側でステートフル再接続を有効にする必要があります。
false の場合、Azure SignalR Service は宣言されたすべてのハブでステートフル再接続を無効にします。

サンプル

上記のオプションは、次のサンプルコードのように構成できます。

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 の詳細については、次の記事を参照してください。

Azure SignalR Service の内部

クイックスタート: SignalR Service を使用してチャットルームを作成する

次の方法で共有

Azure SignalR Service を使用する

Azure SignalR Service のインスタンスを作成する

ASP.NET Core SignalR の場合

SDK のインストール

接続文字列を構成する

オプションの構成

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimsProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

GracefulShutdown

GracefulShutdown.Mode

GracefulShutdown.Timeout

ServiceScaleTimeout

MaxPollIntervalInSeconds

TransportTypeDetector

AllowStatefulReconnects

サンプル

従来の ASP.NET SignalR の場合

SDK のインストール

接続文字列を構成する

オプションの構成

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

MaxPollIntervalInSeconds

サンプル

アプリケーション サーバーのスケールアウト

次のステップ

フィードバック

その他のリソース

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimsProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`GracefulShutdown`

`GracefulShutdown.Mode`

`GracefulShutdown.Timeout`

`ServiceScaleTimeout`

`MaxPollIntervalInSeconds`

`TransportTypeDetector`

`AllowStatefulReconnects`

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`MaxPollIntervalInSeconds`

アプリケーションサーバーのスケールアウト