Använda hubbar i SignalR för ASP.NET Core

Av Rachel Appel och Kevin Griffin

SignalR Hubs-API:et gör det möjligt för anslutna klienter att anropa metoder på servern, vilket underlättar kommunikation i realtid. Servern definierar metoder som anropas av klienten och klienten definierar metoder som anropas av servern. SignalR möjliggör också indirekt kommunikation från klient till klient, som alltid förmedlas av SignalR hubben, så att meddelanden kan skickas mellan enskilda klienter, grupper eller till alla anslutna klienter. SignalR tar hand om allt som krävs för att möjliggöra kommunikation mellan klienter och servrar i realtid.

Konfigurera SignalR hubbar

Om du vill registrera de tjänster som krävs av SignalR hubbar anropar du AddSignalR i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Om du vill konfigurera SignalR slutpunkter anropar du MapHub, även i Program.cs:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Skapa och använda hubbar

Skapa en hubb genom att deklarera en klass som ärver från Hub. Lägg till public metoder i klassen för att göra dem anropsbara från klienter:

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

Kontextobjektet

Klassen Hub innehåller en Context egenskap som innehåller följande egenskaper med information om anslutningen:

Hub.Context innehåller också följande metoder:

Objektet Klient

Klassen Hub innehåller en Clients egenskap som innehåller följande egenskaper för kommunikation mellan server och klient:

Hub.Clients innehåller också följande metoder:

Varje egenskap eller metod i föregående tabeller returnerar ett objekt med en SendAsync metod. Metoden SendAsync tar emot namnet på den klientmetod som ska anropas och eventuella parametrar.

Objektet som returneras av Client metoderna och Caller innehåller också en InvokeAsync metod som kan användas för att vänta på ett resultat från klienten.

Skicka meddelanden till klienter

Om du vill göra anrop till specifika klienter använder du objektets Clients egenskaper. I följande exempel finns det tre hubbmetoder:

• SendMessage skickar ett meddelande till alla anslutna klienter med hjälp av Clients.All.
• SendMessageToCaller skickar ett meddelande tillbaka till anroparen med hjälp av Clients.Caller.
• SendMessageToGroup skickar ett meddelande till alla klienter i SignalR Users gruppen.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Starkt skrivna hubbar

En nackdel med att använda SendAsync är att den förlitar sig på en sträng för att ange vilken klientmetod som ska anropas. Detta lämnar koden öppen för körningsfel om metodnamnet är felstavat eller saknas i klienten.

Ett alternativ till att använda SendAsync är att starkt skriva Hub klassen med Hub<T>. I följande exempel ChatHub har klientmetoden extraherats till ett gränssnitt med namnet IChatClient:

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

Det här gränssnittet kan användas för att omstrukturera föregående ChatHub exempel så att det är starkt skrivet:

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

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Med hjälp av Hub<IChatClient> aktiveras kompileringstidskontroll av klientmetoderna. Detta förhindrar problem som orsakas av användning av strängar, eftersom Hub<T> endast kan ge åtkomst till de metoder som definierats i gränssnittet. Om du använder ett starkt skrivet Hub<T> inaktiveras möjligheten att använda SendAsync.

Klientresultat

Förutom att göra anrop till klienter kan servern begära ett resultat från en klient. Detta kräver att servern använder ISingleClientProxy.InvokeAsync och att klienten ska returnera ett resultat från sin .On-hanterare.

Det finns två sätt att använda API:et på servern, det första är att anropa Client(...) eller Caller på Clients egenskapen i en hubbmetod:

public class ChatHub : Hub
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        var message = await Clients.Client(connectionId).InvokeAsync<string>(
            "GetMessage");
        return message;
    }
}

Det andra sättet är att anropa Client(...) på en instans av IHubContext<T>.

async Task SomeMethod(IHubContext<MyHub> context)
{
    string result = await context.Clients.Client(connectionID).InvokeAsync<string>(
        "GetMessage");
}

Typstarka hubbar kan också returnera värden från gränssnittsmetoder.

public interface IClient
{
    Task<string> GetMessage();
}

public class ChatHub : Hub<IClient>
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        string message = await Clients.Client(connectionId).GetMessage();
        return message;
    }
}

Klienter returnerar resultat i sina .On(...) hanterare enligt nedan:

.NET-klient

hubConnection.On("GetMessage", async () =>
{
    Console.WriteLine("Enter message:");
    var message = await Console.In.ReadLineAsync();
    return message;
});

Typescript-klient

hubConnection.on("GetMessage", async () => {
    let promise = new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve("message");
        }, 100);
    });
    return promise;
});

Java-klient

hubConnection.onWithResult("GetMessage", () -> {
    return Single.just("message");
});

Ändra namnet på en hubbmetod

Som standard är ett serverhubbmetodnamn namnet på .NET-metoden. Om du vill ändra det här standardbeteendet för en specifik metod använder du attributet HubMethodName . Klienten bör använda det här namnet i stället för .NET-metodnamnet när metoden anropas:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Mata in tjänster i en hubb

Hubbkonstruktorer kan acceptera tjänster från DI som parametrar, som kan lagras i egenskaper i klassen för användning i en hubbmetod.

När du matar in flera tjänster för olika hubbmetoder eller som ett alternativt sätt att skriva kod kan hubbmetoder också acceptera tjänster från DI. Standardmässigt inspekteras och löses hubbmetodparametrar från DI om möjligt.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message, IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Om implicit lösning av parametrar från tjänster inte önskas inaktiverar du den med DisableImplicitFromServicesParameters. Om du uttryckligen vill ange vilka parametrar som matchas från DI i hubbmetoder använder du DisableImplicitFromServicesParameters alternativet och använder [FromServices] attributet eller ett anpassat attribut som implementeras IFromServiceMetadata på de hubbmetodparametrar som ska matchas från DI.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();
services.AddSignalR(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message,
        [FromServices] IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Stöd för nyckelade tjänster i Dependency Injection

Keyed services avser en mekanism för att registrera och hämta tjänster inom beroendeinjektion (DI) med hjälp av nycklar. En tjänst associeras med en nyckel genom att anropa AddKeyedSingleton (eller AddKeyedScoped eller AddKeyedTransient) för att registrera den. Få åtkomst till en registrerad tjänst genom att ange nyckeln med attributet [FromKeyedServices]. Följande kod visar hur du använder nyckelade tjänster:

using Microsoft.AspNetCore.SignalR;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

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

var app = builder.Build();

app.MapRazorPages();
app.MapHub<MyHub>("/myHub");

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

public class MyHub : Hub
{
    public void SmallCacheMethod([FromKeyedServices("small")] ICache cache)
    {
        Console.WriteLine(cache.Get("signalr"));
    }

    public void BigCacheMethod([FromKeyedServices("big")] ICache cache)
    {
        Console.WriteLine(cache.Get("signalr"));
    }
}

Hantera händelser för en anslutning

SignalR Hubs-API:et tillhandahåller de OnConnectedAsync virtuella metoderna och OnDisconnectedAsync för att hantera och spåra anslutningar. Åsidosätt den OnConnectedAsync virtuella metoden för att utföra åtgärder när en klient ansluter till hubben, till exempel lägga till den i en grupp:

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

Åsidosätt den OnDisconnectedAsync virtuella metoden för att utföra åtgärder när en klient kopplar från. Om klienten kopplas från avsiktligt, till exempel genom att anropa connection.stop(), är parametern exception inställd på null. Men om klienten kopplas från på grund av ett fel, till exempel ett nätverksfel, innehåller parametern exception ett undantag som beskriver felet:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync behöver inte anropas i OnDisconnectedAsync, den hanteras automatiskt åt dig.

Hantering av fel

Undantag som genereras i hubbmetoder skickas till klienten som anropade metoden. På JavaScript-klienten invoke returnerar metoden ett JavaScript Promise. Klienter kan koppla en catch hanterare till det returnerade löftet eller använda try/catch med async/await för att hantera undantag:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Anslutningar stängs inte när en hubb utlöser ett undantag. Som standard SignalR returnerar ett allmänt felmeddelande till klienten, som visas i följande exempel:

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

Oväntade undantag innehåller ofta känslig information, till exempel namnet på en databasserver i ett undantag som utlöses när databasanslutningen misslyckas. SignalR visar inte dessa detaljerade felmeddelanden som standard som ett säkerhetsmått. Mer information om varför undantagsinformation utelämnas finns i Säkerhetsöverväganden i ASP.NET Core SignalR.

Om ett exceptionellt villkor måste spridas till klienten använder du HubException klassen . Om en HubException genereras i en hubbmetod, SignalRskickar den hela undantagsmeddelandet till klienten, oförändrat.

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

Ytterligare resurser

• Visa eller ladda ned exempelkod(ladda ned)
• Översikt över ASP.NET Core SignalR
• ASP.NET Core SignalR JavaScript-klient
• Publicera en ASP.NET Core SignalR-app till Azure App Service

Av Rachel Appel och Kevin Griffin

SignalR Hubs-API:et gör det möjligt för anslutna klienter att anropa metoder på servern, vilket underlättar kommunikation i realtid. Servern definierar metoder som anropas av klienten och klienten definierar metoder som anropas av servern. SignalR möjliggör också indirekt kommunikation från klient till klient, som alltid förmedlas av SignalR hubben, så att meddelanden kan skickas mellan enskilda klienter, grupper eller till alla anslutna klienter. SignalR tar hand om allt som krävs för att möjliggöra kommunikation mellan klienter och servrar i realtid.

Konfigurera SignalR hubbar

Om du vill registrera de tjänster som krävs av SignalR hubbar anropar du AddSignalR i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Om du vill konfigurera SignalR slutpunkter anropar du MapHub, även i Program.cs:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Skapa och använda hubbar

Skapa en hubb genom att deklarera en klass som ärver från Hub. Lägg till public metoder i klassen för att göra dem anropsbara från klienter:

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

Kontextobjektet

Klassen Hub innehåller en Context egenskap som innehåller följande egenskaper med information om anslutningen:

Hub.Context innehåller också följande metoder:

Objektet Klient

Klassen Hub innehåller en Clients egenskap som innehåller följande egenskaper för kommunikation mellan server och klient:

Hub.Clients innehåller också följande metoder:

Varje egenskap eller metod i föregående tabeller returnerar ett objekt med en SendAsync metod. Metoden SendAsync tar emot namnet på den klientmetod som ska anropas och eventuella parametrar.

Objektet som returneras av Client metoderna och Caller innehåller också en InvokeAsync metod som kan användas för att vänta på ett resultat från klienten.

Skicka meddelanden till klienter

Om du vill göra anrop till specifika klienter använder du objektets Clients egenskaper. I följande exempel finns det tre hubbmetoder:

• SendMessage skickar ett meddelande till alla anslutna klienter med hjälp av Clients.All.
• SendMessageToCaller skickar ett meddelande tillbaka till anroparen med hjälp av Clients.Caller.
• SendMessageToGroup skickar ett meddelande till alla klienter i SignalR Users gruppen.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Starkt skrivna hubbar

En nackdel med att använda SendAsync är att den förlitar sig på en sträng för att ange vilken klientmetod som ska anropas. Detta lämnar koden öppen för körningsfel om metodnamnet är felstavat eller saknas i klienten.

Ett alternativ till att använda SendAsync är att starkt skriva Hub klassen med Hub<T>. I följande exempel ChatHub har klientmetoden extraherats till ett gränssnitt med namnet IChatClient:

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

Det här gränssnittet kan användas för att omstrukturera föregående ChatHub exempel så att det är starkt skrivet:

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

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Med hjälp av Hub<IChatClient> aktiveras kompileringstidskontroll av klientmetoderna. Detta förhindrar problem som orsakas av användning av strängar, eftersom Hub<T> endast kan ge åtkomst till de metoder som definierats i gränssnittet. Om du använder ett starkt skrivet Hub<T> inaktiveras möjligheten att använda SendAsync.

Klientresultat

Förutom att göra anrop till klienter kan servern begära ett resultat från en klient. Detta kräver att servern använder ISingleClientProxy.InvokeAsync och att klienten ska returnera ett resultat från sin .On-hanterare.

Det finns två sätt att använda API:et på servern, det första är att anropa Client(...) eller Caller på Clients egenskapen i en hubbmetod:

public class ChatHub : Hub
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        var message = await Clients.Client(connectionId).InvokeAsync<string>(
            "GetMessage");
        return message;
    }
}

Det andra sättet är att anropa Client(...) på en instans av IHubContext<T>.

async Task SomeMethod(IHubContext<MyHub> context)
{
    string result = await context.Clients.Client(connectionID).InvokeAsync<string>(
        "GetMessage");
}

Typstarka hubbar kan också returnera värden från gränssnittsmetoder.

public interface IClient
{
    Task<string> GetMessage();
}

public class ChatHub : Hub<IClient>
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        string message = await Clients.Client(connectionId).GetMessage();
        return message;
    }
}

Klienter returnerar resultat i sina .On(...) hanterare enligt nedan:

.NET-klient

hubConnection.On("GetMessage", async () =>
{
    Console.WriteLine("Enter message:");
    var message = await Console.In.ReadLineAsync();
    return message;
});

Typescript-klient

hubConnection.on("GetMessage", async () => {
    let promise = new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve("message");
        }, 100);
    });
    return promise;
});

Java-klient

hubConnection.onWithResult("GetMessage", () -> {
    return Single.just("message");
});

Ändra namnet på en hubbmetod

Som standard är ett serverhubbmetodnamn namnet på .NET-metoden. Om du vill ändra det här standardbeteendet för en specifik metod använder du attributet HubMethodName . Klienten bör använda det här namnet i stället för .NET-metodnamnet när metoden anropas:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Mata in tjänster i en hubb

Hubbkonstruktorer kan acceptera tjänster från DI som parametrar, som kan lagras i egenskaper i klassen för användning i en hubbmetod.

När du matar in flera tjänster för olika hubbmetoder eller som ett alternativt sätt att skriva kod kan hubbmetoder också acceptera tjänster från DI. Standardmässigt inspekteras och löses hubbmetodparametrar från DI om möjligt.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message, IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Om implicit lösning av parametrar från tjänster inte önskas inaktiverar du den med DisableImplicitFromServicesParameters. Om du uttryckligen vill ange vilka parametrar som matchas från DI i hubbmetoder använder du DisableImplicitFromServicesParameters alternativet och använder [FromServices] attributet eller ett anpassat attribut som implementeras IFromServiceMetadata på de hubbmetodparametrar som ska matchas från DI.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();
services.AddSignalR(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message,
        [FromServices] IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Hantera händelser för en anslutning

SignalR Hubs-API:et tillhandahåller de OnConnectedAsync virtuella metoderna och OnDisconnectedAsync för att hantera och spåra anslutningar. Åsidosätt den OnConnectedAsync virtuella metoden för att utföra åtgärder när en klient ansluter till hubben, till exempel lägga till den i en grupp:

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

Åsidosätt den OnDisconnectedAsync virtuella metoden för att utföra åtgärder när en klient kopplar från. Om klienten kopplas från avsiktligt, till exempel genom att anropa connection.stop(), är parametern exception inställd på null. Men om klienten kopplas från på grund av ett fel, till exempel ett nätverksfel, innehåller parametern exception ett undantag som beskriver felet:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync behöver inte anropas i OnDisconnectedAsync, den hanteras automatiskt åt dig.

Hantering av fel

Undantag som genereras i hubbmetoder skickas till klienten som anropade metoden. På JavaScript-klienten invoke returnerar metoden ett JavaScript Promise. Klienter kan koppla en catch hanterare till det returnerade löftet eller använda try/catch med async/await för att hantera undantag:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Anslutningar stängs inte när en hubb utlöser ett undantag. Som standard SignalR returnerar ett allmänt felmeddelande till klienten, som visas i följande exempel:

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

Oväntade undantag innehåller ofta känslig information, till exempel namnet på en databasserver i ett undantag som utlöses när databasanslutningen misslyckas. SignalR visar inte dessa detaljerade felmeddelanden som standard som ett säkerhetsmått. Mer information om varför undantagsinformation utelämnas finns i Säkerhetsöverväganden i ASP.NET Core SignalR.

Om ett exceptionellt villkor måste spridas till klienten använder du HubException klassen . Om en HubException genereras i en hubbmetod, SignalRskickar den hela undantagsmeddelandet till klienten, oförändrat.

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

Ytterligare resurser

• Visa eller ladda ned exempelkod(ladda ned)
• Översikt över ASP.NET Core SignalR
• ASP.NET Core SignalR JavaScript-klient
• Publicera en ASP.NET Core SignalR-app till Azure App Service

Av Rachel Appel och Kevin Griffin

SignalR Hubs-API:et gör det möjligt för anslutna klienter att anropa metoder på servern, vilket underlättar kommunikation i realtid. Servern definierar metoder som anropas av klienten och klienten definierar metoder som anropas av servern. SignalR möjliggör också indirekt kommunikation från klient till klient, som alltid förmedlas av SignalR hubben, så att meddelanden kan skickas mellan enskilda klienter, grupper eller till alla anslutna klienter. SignalR tar hand om allt som krävs för att möjliggöra kommunikation mellan klienter och servrar i realtid.

Konfigurera SignalR hubbar

Om du vill registrera de tjänster som krävs av SignalR hubbar anropar du AddSignalR i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Om du vill konfigurera SignalR slutpunkter anropar du MapHub, även i Program.cs:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Skapa och använda hubbar

Skapa en hubb genom att deklarera en klass som ärver från Hub. Lägg till public metoder i klassen för att göra dem anropsbara från klienter:

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

Kontextobjektet

Klassen Hub innehåller en Context egenskap som innehåller följande egenskaper med information om anslutningen:

Hub.Context innehåller också följande metoder:

Objektet Klient

Klassen Hub innehåller en Clients egenskap som innehåller följande egenskaper för kommunikation mellan server och klient:

Hub.Clients innehåller också följande metoder:

Varje egenskap eller metod i föregående tabeller returnerar ett objekt med en SendAsync metod. Metoden SendAsync tar emot namnet på den klientmetod som ska anropas och eventuella parametrar.

Skicka meddelanden till klienter

Om du vill göra anrop till specifika klienter använder du objektets Clients egenskaper. I följande exempel finns det tre hubbmetoder:

• SendMessage skickar ett meddelande till alla anslutna klienter med hjälp av Clients.All.
• SendMessageToCaller skickar ett meddelande tillbaka till anroparen med hjälp av Clients.Caller.
• SendMessageToGroup skickar ett meddelande till alla klienter i SignalR Users gruppen.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Starkt skrivna hubbar

En nackdel med att använda SendAsync är att den förlitar sig på en sträng för att ange vilken klientmetod som ska anropas. Detta lämnar koden öppen för körningsfel om metodnamnet är felstavat eller saknas i klienten.

Ett alternativ till att använda SendAsync är att starkt skriva Hub klassen med Hub<T>. I följande exempel ChatHub har klientmetoden extraherats till ett gränssnitt med namnet IChatClient:

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

Det här gränssnittet kan användas för att omstrukturera föregående ChatHub exempel så att det är starkt skrivet:

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

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Med hjälp av Hub<IChatClient> aktiveras kompileringstidskontroll av klientmetoderna. Detta förhindrar problem som orsakas av användning av strängar, eftersom Hub<T> endast kan ge åtkomst till de metoder som definierats i gränssnittet. Om du använder ett starkt skrivet Hub<T> inaktiveras möjligheten att använda SendAsync.

Ändra namnet på en hubbmetod

Som standard är ett serverhubbmetodnamn namnet på .NET-metoden. Om du vill ändra det här standardbeteendet för en specifik metod använder du attributet HubMethodName . Klienten bör använda det här namnet i stället för .NET-metodnamnet när metoden anropas:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Hantera händelser för en anslutning

SignalR Hubs-API:et tillhandahåller de OnConnectedAsync virtuella metoderna och OnDisconnectedAsync för att hantera och spåra anslutningar. Åsidosätt den OnConnectedAsync virtuella metoden för att utföra åtgärder när en klient ansluter till hubben, till exempel lägga till den i en grupp:

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

Åsidosätt den OnDisconnectedAsync virtuella metoden för att utföra åtgärder när en klient kopplar från. Om klienten kopplas från avsiktligt, till exempel genom att anropa connection.stop(), är parametern exception inställd på null. Men om klienten kopplas från på grund av ett fel, till exempel ett nätverksfel, innehåller parametern exception ett undantag som beskriver felet:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync behöver inte anropas i OnDisconnectedAsync, den hanteras automatiskt åt dig.

Hantering av fel

Undantag som genereras i hubbmetoder skickas till klienten som anropade metoden. På JavaScript-klienten invoke returnerar metoden ett JavaScript Promise. Klienter kan koppla en catch hanterare till det returnerade löftet eller använda try/catch med async/await för att hantera undantag:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Anslutningar stängs inte när en hubb utlöser ett undantag. Som standard SignalR returnerar ett allmänt felmeddelande till klienten, som visas i följande exempel:

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

Oväntade undantag innehåller ofta känslig information, till exempel namnet på en databasserver i ett undantag som utlöses när databasanslutningen misslyckas. SignalR visar inte dessa detaljerade felmeddelanden som standard som ett säkerhetsmått. Mer information om varför undantagsinformation utelämnas finns i Säkerhetsöverväganden i ASP.NET Core SignalR.

Om ett exceptionellt villkor måste spridas till klienten använder du HubException klassen . Om en HubException genereras i en hubbmetod, SignalRskickar den hela undantagsmeddelandet till klienten, oförändrat.

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

Ytterligare resurser

• Visa eller ladda ned exempelkod(ladda ned)
• Översikt över ASP.NET Core SignalR
• ASP.NET Core SignalR JavaScript-klient
• Publicera en ASP.NET Core SignalR-app till Azure App Service
• SignalR Hubbprotokoll

Av Rachel Appel och Kevin Griffin

Visa eller ladda ned exempelkod(ladda ned)

Vad är en hubb?SignalR

SignalR Hubs-API:et gör det möjligt för anslutna klienter att anropa metoder på servern, vilket underlättar kommunikation i realtid. Servern definierar metoder som anropas av klienten och klienten definierar metoder som anropas av servern. SignalR möjliggör också indirekt kommunikation från klient till klient, som alltid förmedlas av SignalR hubben, så att meddelanden kan skickas mellan enskilda klienter, grupper eller till alla anslutna klienter. SignalR tar hand om allt som krävs för att möjliggöra kommunikation mellan klienter och servrar i realtid.

Konfigurera SignalR hubbar

Mellanprogrammet SignalR kräver vissa tjänster som konfigureras genom att anropa AddSignalR:

services.AddSignalR();

När du lägger till SignalR funktionalitet i en ASP.NET Core-app, konfigurera SignalR rutter genom att anropa MapHub i metodens Startup.ConfigureUseEndpoints återanrop:

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

Skapa och använda hubbar

Skapa en hubb genom att deklarera en klass som ärver från Huboch lägga till offentliga metoder i den. Klienter kan anropa metoder som definieras som public:

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

Du kan ange en returtyp och parametrar, inklusive komplexa typer och matriser, som i vilken C#-metod som helst. SignalR hanterar serialisering och deserialisering av komplexa objekt och matriser i dina parametrar och returvärden.

Kontextobjektet

Klassen Hub har en Context egenskap som innehåller följande egenskaper med information om anslutningen:

Hub.Context innehåller också följande metoder:

Objektet Klient

Klassen Hub har en Clients egenskap som innehåller följande egenskaper för kommunikation mellan server och klient:

Hub.Clients innehåller också följande metoder:

Varje egenskap eller metod i föregående tabeller returnerar ett objekt med en SendAsync metod. Med SendAsync metoden kan du ange namnet och parametrarna för den klientmetod som ska anropas.

Skicka meddelanden till klienter

Om du vill göra anrop till specifika klienter använder du objektets Clients egenskaper. I följande exempel finns det tre hubbmetoder:

• SendMessage skickar ett meddelande till alla anslutna klienter med hjälp av Clients.All.
• SendMessageToCaller skickar ett meddelande tillbaka till anroparen med hjälp av Clients.Caller.
• SendMessageToGroup skickar ett meddelande till alla klienter i SignalR Users gruppen.

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

Starkt skrivna hubbar

En nackdel med att använda SendAsync är att den förlitar sig på en magisk sträng för att ange vilken klientmetod som ska anropas. Detta lämnar koden öppen för körningsfel om metodnamnet är felstavat eller saknas i klienten.

Ett alternativ till att använda SendAsync är att starkt skriva Hub med Hub<T>. I följande exempel har klientmetoderna ChatHub extraherats till ett gränssnitt med namnet IChatClient.

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

Det här gränssnittet kan användas för att omstrukturera föregående ChatHub exempel:

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

Med hjälp av Hub<IChatClient> aktiveras kompileringstidskontroll av klientmetoderna. Detta förhindrar problem som orsakas av magiska strängar, eftersom Hub<T> endast kan ge åtkomst till de metoder som definierats i gränssnittet.

Om du använder ett starkt skrivet Hub<T> inaktiveras möjligheten att använda SendAsync. Alla metoder som definieras i gränssnittet kan fortfarande definieras som asynkrona. I själva verket bör var och en av dessa metoder returnera en Task. Eftersom det är ett gränssnitt ska du inte använda nyckelordet async . Till exempel:

public interface IClient
{
    Task ClientMethod();
}

Ändra namnet på en hubbmetod

Som standard är ett serverhubbmetodnamn namnet på .NET-metoden. Du kan dock använda attributet HubMethodName för att ändra den här standardinställningen och manuellt ange ett namn för metoden. Klienten bör använda det här namnet i stället för .NET-metodnamnet när metoden anropas:

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

Hantera händelser för en anslutning

SignalR Hubs-API:et tillhandahåller de OnConnectedAsync virtuella metoderna och OnDisconnectedAsync för att hantera och spåra anslutningar. Åsidosätt den OnConnectedAsync virtuella metoden för att utföra åtgärder när en klient ansluter till hubben, till exempel lägga till den i en grupp:

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

Åsidosätt den OnDisconnectedAsync virtuella metoden för att utföra åtgärder när en klient kopplar från. Om klienten kopplas från avsiktligt (genom att anropa connection.stop(), till exempel) kommer parametern exception att bli null. Men om klienten kopplas från på grund av ett fel (till exempel ett nätverksfel) innehåller parametern exception ett undantag som beskriver felet:

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", "I", "disconnect");
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync behöver inte anropas i OnDisconnectedAsync, den hanteras automatiskt åt dig.

Hantering av fel

Undantag som genereras i dina hubbmetoder skickas till klienten som anropade metoden. På JavaScript-klienten invoke returnerar metoden ett JavaScript Promise. När klienten får ett fel med en hanterare som är kopplad till löftet med catch, anropas den och skickas som ett JavaScript-objekt Error.

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

Om hubben utlöser ett undantag stängs inte anslutningarna. Som standard SignalR returnerar ett allmänt felmeddelande till klienten. Till exempel:

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

Oväntade undantag innehåller ofta känslig information, till exempel namnet på en databasserver i ett undantag som utlöses när databasanslutningen misslyckas. SignalR visar inte dessa detaljerade felmeddelanden som standard som ett säkerhetsmått. Mer information om varför undantagsinformation utelämnas finns i Säkerhetsöverväganden i ASP.NET Core SignalR.

Om du har ett exceptionellt villkor som du vill sprida till klienten kan du använda HubException klassen . Om du kastar ett HubException från din hub-metod, SignalRkommer hela meddelandet att skickas till klienten, omodifierat:

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

Ytterligare resurser

• Översikt över ASP.NET Core SignalR
• ASP.NET Core SignalR JavaScript-klient
• Publicera en ASP.NET Core SignalR-app till Azure App Service

Av Rachel Appel och Kevin Griffin

Visa eller ladda ned exempelkod(ladda ned)

Vad är en hubb?SignalR

SignalR Hubs-API:et gör det möjligt för anslutna klienter att anropa metoder på servern, vilket underlättar kommunikation i realtid. Servern definierar metoder som anropas av klienten och klienten definierar metoder som anropas av servern. SignalR möjliggör också indirekt kommunikation från klient till klient, som alltid förmedlas av SignalR hubben, så att meddelanden kan skickas mellan enskilda klienter, grupper eller till alla anslutna klienter. SignalR tar hand om allt som krävs för att möjliggöra kommunikation mellan klienter och servrar i realtid.

Konfigurera SignalR hubbar

Mellanprogrammet SignalR kräver vissa tjänster som konfigureras genom att anropa AddSignalR:

services.AddSignalR();

När du lägger till SignalR funktioner i en ASP.NET Core-app konfigurerar du SignalR vägar genom att anropa UseSignalR i Startup.Configure -metoden:

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

Skapa och använda hubbar

Skapa en hubb genom att deklarera en klass som ärver från Huboch lägga till offentliga metoder i den. Klienter kan anropa metoder som definieras som public:

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

Du kan ange en returtyp och parametrar, inklusive komplexa typer och matriser, som i vilken C#-metod som helst. SignalR hanterar serialisering och deserialisering av komplexa objekt och matriser i dina parametrar och returvärden.

Kontextobjektet

Klassen Hub har en Context egenskap som innehåller följande egenskaper med information om anslutningen:

Hub.Context innehåller också följande metoder:

Objektet Klient

Klassen Hub har en Clients egenskap som innehåller följande egenskaper för kommunikation mellan server och klient:

Hub.Clients innehåller också följande metoder:

Varje egenskap eller metod i föregående tabeller returnerar ett objekt med en SendAsync metod. Med SendAsync metoden kan du ange namnet och parametrarna för den klientmetod som ska anropas.

Skicka meddelanden till klienter

Om du vill göra anrop till specifika klienter använder du objektets Clients egenskaper. I följande exempel finns det tre hubbmetoder:

• SendMessage skickar ett meddelande till alla anslutna klienter med hjälp av Clients.All.
• SendMessageToCaller skickar ett meddelande tillbaka till anroparen med hjälp av Clients.Caller.
• SendMessageToGroup skickar ett meddelande till alla klienter i SignalR Users gruppen.

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

Starkt skrivna hubbar

En nackdel med att använda SendAsync är att den förlitar sig på en magisk sträng för att ange vilken klientmetod som ska anropas. Detta lämnar koden öppen för körningsfel om metodnamnet är felstavat eller saknas i klienten.

Ett alternativ till att använda SendAsync är att starkt skriva Hub med Hub<T>. I följande exempel har klientmetoderna ChatHub extraherats till ett gränssnitt med namnet IChatClient.

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

Det här gränssnittet kan användas för att omstrukturera föregående ChatHub exempel:

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

Med hjälp av Hub<IChatClient> aktiveras kompileringstidskontroll av klientmetoderna. Detta förhindrar problem som orsakas av magiska strängar, eftersom Hub<T> endast kan ge åtkomst till de metoder som definierats i gränssnittet.

Om du använder ett starkt skrivet Hub<T> inaktiveras möjligheten att använda SendAsync. Alla metoder som definieras i gränssnittet kan fortfarande definieras som asynkrona. I själva verket bör var och en av dessa metoder returnera en Task. Eftersom det är ett gränssnitt ska du inte använda nyckelordet async . Till exempel:

public interface IClient
{
    Task ClientMethod();
}

Ändra namnet på en hubbmetod

Som standard är ett serverhubbmetodnamn namnet på .NET-metoden. Du kan dock använda attributet HubMethodName för att ändra den här standardinställningen och manuellt ange ett namn för metoden. Klienten bör använda det här namnet i stället för .NET-metodnamnet när metoden anropas:

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

Hantera händelser för en anslutning

SignalR Hubs-API:et tillhandahåller de OnConnectedAsync virtuella metoderna och OnDisconnectedAsync för att hantera och spåra anslutningar. Åsidosätt den OnConnectedAsync virtuella metoden för att utföra åtgärder när en klient ansluter till hubben, till exempel lägga till den i en grupp:

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

Åsidosätt den OnDisconnectedAsync virtuella metoden för att utföra åtgärder när en klient kopplar från. Om klienten kopplas från avsiktligt (genom att anropa connection.stop(), till exempel) kommer parametern exception att bli null. Men om klienten kopplas från på grund av ett fel (till exempel ett nätverksfel) innehåller parametern exception ett undantag som beskriver felet:

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", "I", "disconnect");
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync behöver inte anropas i OnDisconnectedAsync, den hanteras automatiskt åt dig.

Hantering av fel

Undantag som genereras i dina hubbmetoder skickas till klienten som anropade metoden. På JavaScript-klienten invoke returnerar metoden ett JavaScript Promise. När klienten får ett fel med en hanterare som är kopplad till löftet med catch, anropas den och skickas som ett JavaScript-objekt Error.

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

Om hubben utlöser ett undantag stängs inte anslutningarna. Som standard SignalR returnerar ett allmänt felmeddelande till klienten. Till exempel:

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

Oväntade undantag innehåller ofta känslig information, till exempel namnet på en databasserver i ett undantag som utlöses när databasanslutningen misslyckas. SignalR visar inte dessa detaljerade felmeddelanden som standard som ett säkerhetsmått. Mer information om varför undantagsinformation utelämnas finns i Säkerhetsöverväganden i ASP.NET Core SignalR.

Om du har ett exceptionellt villkor som du vill sprida till klienten kan du använda HubException klassen . Om du kastar ett HubException från din hub-metod, SignalRkommer hela meddelandet att skickas till klienten, omodifierat:

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

Ytterligare resurser

• Översikt över ASP.NET Core SignalR
• ASP.NET Core SignalR JavaScript-klient
• Publicera en ASP.NET Core SignalR-app till Azure App Service