ASP.NET Core 用 SignalR でハブを使用する

作成者: Rachel Appel、Kevin Griffin

サンプル コードを表示またはダウンロードする (ダウンロード方法)

SignalR ハブとは

SignalR Hubs API を使用すると、接続されているクライアント上のメソッドをサーバーから呼び出すことができます。 サーバーのコードでは、クライアントによって呼び出されるメソッドを定義します。 クライアントのコードでは、サーバーから呼び出されるメソッドを定義します。 クライアントからサーバーおよびサーバーからクライアントへのリアルタイム通信を可能にするバックグラウンドの処理はすべて、SignalR によって行われます。

SignalR ハブを構成する

SignalR ミドルウェアに必要ないくつかのサービスは、services.AddSignalR を呼び出すと構成されます。

services.AddSignalR();

app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<ChatHub>("/chathub");
});

app.UseSignalR(route =>
{
    route.MapHub<ChatHub>("/chathub");
});

ハブを作成して使用する

Hub から継承するクラスを宣言してハブを作成し、それにパブリック メソッドを追加します。 クライアントは、public として定義されているメソッドを呼び出すことができます。

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message)
    {
        return Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

C# のメソッドの場合と同様に、複合型や配列など、戻り値の型とパラメーターを指定できます。 パラメーターと戻り値の複合オブジェクトおよび配列のシリアル化と逆シリアル化は、SignalR によって処理されます。

Context オブジェクト

Hub クラスの Context プロパティには、接続に関する情報が設定される次のプロパティが含まれます。

Hub.Context には、次のメソッドも含まれます。

Clients オブジェクト

Hub クラスの Clients プロパティには、サーバーとクライアントの間の通信に関する次のプロパティが含まれます。

Hub.Clients には、次のメソッドも含まれます。

SendAsync メソッドでは、前の表の各プロパティまたはメソッドからオブジェクトが返されます。 SendAsync メソッドを使用すると、呼び出すクライアント メソッドの名前とパラメーターを指定できます。

クライアントにメッセージを送信する

特定のクライアントに対して呼び出しを行うには、Clients オブジェクトのプロパティを使用します。 次の例には、3 つのハブ メソッドがあります。

• SendMessage を呼び出すと、Clients.All を使用して、接続されているすべてのクライアントにメッセージが送信されます。
• SendMessageToCaller を呼び出すと、Clients.Caller を使用して、呼び出し元にメッセージが返送されます。
• SendMessageToGroup を呼び出すと、SignalR Users グループ内のすべてのクライアントにメッセージが送信されます。

public Task SendMessage(string user, string message)
{
    return Clients.All.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToCaller(string user, string message)
{
    return Clients.Caller.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToGroup(string user, string message)
{
    return Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);
}

厳密に型指定されたハブ

SendAsync を使用する場合の欠点は、呼び出されるクライアント メソッドを指定するのに、マジック文字列が使用されることです。 このため、メソッド名が間違って綴られていたり、クライアントに存在しなくなっていると、コードで実行時エラーが発生します。

SendAsync を使用する代わりに、Hub<T> を使用して Hub を厳密に型指定する方法もあります。 次の例では、ChatHub クライアント メソッドが IChatClient というインターフェイスに抽出されています。

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

このインターフェイスを使用して、前の ChatHub の例をリファクタリングすることができます。

public class StronglyTypedChatHub : Hub<IChatClient>
{
    public async Task SendMessage(string user, string message)
    {
        await Clients.All.ReceiveMessage(user, message);
    }

    public Task SendMessageToCaller(string user, string message)
    {
        return Clients.Caller.ReceiveMessage(user, message);
    }
}

Hub<IChatClient> を使用すると、クライアント メソッドをコンパイル時にチェックできます。 これにより、Hub<T> では、インターフェイスで定義されたメソッドへのアクセスのみを提供できるため、マジック文字列の使用による問題を回避できます。

厳密に型指定された Hub<T> を使用すると、SendAsync は使用できなくなります。 インターフェイスで定義されているどのメソッドも、引き続き非同期として定義できます。 実際、これらの各メソッドからは Task を返す必要があります。 これはインターフェイスであるため、async キーワードを使用しないでください。 次に例を示します。

public interface IClient
{
    Task ClientMethod();
}

ハブ メソッドの名前を変更する

既定では、サーバー ハブ メソッドの名前は .NET メソッドの名前です。 ただし、HubMethodName 属性を使ってこの既定値を変更し、メソッドの名前を手動で指定することができます。 クライアントでメソッドを呼び出すときは、.NET のメソッド名ではなく、この名前を使用する必要があります。

[HubMethodName("SendMessageToUser")]
public Task DirectMessage(string user, string message)
{
    return Clients.User(user).SendAsync("ReceiveMessage", user, message);
}

接続のイベントを処理する

SignalR Hubs API には、接続の管理と追跡のために、仮想メソッド OnConnectedAsync と OnDisconnectedAsync が用意されています。 クライアントがハブに接続するときにアクションを実行するには (グループへの追加など)、OnConnectedAsync 仮想メソッドをオーバーライドします。

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

クライアントが切断するときにアクションを実行するには、OnDisconnectedAsync 仮想メソッドをオーバーライドします。 クライアントが意図的に切断された場合 (たとえば、connection.stop() を呼び出すことによって)、exception パラメーターは null になります。 一方、エラーのためにクライアントが切断された場合は (ネットワーク障害など)、exception パラメーターにエラーを説明する例外が格納されます。

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnDisconnectedAsync(exception);
}

エラーの処理

ハブ メソッドでスローされた例外は、メソッドを呼び出したクライアントに送信されます。 JavaScript クライアントでは、invoke メソッドによって JavaScript Promise が返されます。 クライアントが catch を使用してハンドラーが Promise にアタッチされたエラーを受け取ると、それが呼び出されて、JavaScript の Error オブジェクトとして渡されます。

connection.invoke("SendMessage", user, message).catch(err => console.error(err));

ハブが例外をスローした場合、接続は閉じられません。 既定では、SignalR からは一般的なエラー メッセージがクライアントに返されます。 次に例を示します。

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'MethodName' on the server.

予期しない例外には、データベース接続が失敗したときにトリガーされる例外でのデータベース サーバー名など、機密情報が含まれていることがよくあります。 セキュリティ対策として、SignalR では、これらの詳細なエラー メッセージは既定では公開されません。 例外の詳細が抑制される理由について詳しくは、セキュリティの考慮事項に関する記事をご覧ください。

例外の状態をクライアントに伝える必要が "ある" 場合は、HubException クラスを使用できます。 ハブ メソッドから HubException をスローすると、SignalR によってメッセージ全体が変更されずにクライアントに 送信されます。

public Task ThrowException()
{
    throw new HubException("This error will be sent to the client!");
}

関連リソース

• ASP.NET Core SignalR の概要
• JavaScript クライアント
• Azure に発行する