ASP.NET Core SignalR JavaScript-client

Door Rachel Appel

Met de ASP.NET Core SignalR JavaScript-clientbibliotheek kunnen ontwikkelaars SignalR hubcode aan de serverzijde aanroepen.

Het SignalR-clientpakket installeren

De SignalR JavaScript-clientbibliotheek wordt geleverd als een npm--pakket. In de volgende secties worden verschillende manieren beschreven om de clientbibliotheek te installeren.

Installeren met npm

Visual Studio

Voer de volgende opdrachten uit vanuit Package Manager Console:

Visual Studio Code

Voer de volgende opdrachten uit vanuit de Integrated Terminal:

Visual Studio voor Mac-

Voer de volgende opdrachten uit vanuit een opdrachtvenster:

npm init -y
npm install @microsoft/signalr

npm installeert de inhoud van het pakket in de map node_modules\@microsoft\signalr\dist\browser. Maak de map wwwroot/lib/signalr. Kopieer het signalr.js bestand naar de map wwwroot/lib/signalr.

Verwijs naar de SignalR JavaScript-client in het <script>-element. Bijvoorbeeld:

<script src="~/lib/signalr/signalr.js"></script>

Een CDN (Content Delivery Network) gebruiken

Als u de clientbibliotheek wilt gebruiken zonder de npm-vereiste, verwijst u naar een door CDN gehoste kopie van de clientbibliotheek. Bijvoorbeeld:

<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.js"></script>

In de voorgaande markeringen wordt versie 6.0.1 opgegeven. Kies uit een van de volgende CDN's om de nieuwste clientbibliotheekversie op te halen:

• cdnjs-
• jsDelivr-
• unpkg

Installeren met LibMan

LibMan- kan worden gebruikt voor het installeren van specifieke clientbibliotheekbestanden uit de door CDN gehoste clientbibliotheek. Voeg bijvoorbeeld alleen het minified JavaScript-bestand toe aan het project. Voor details over die benadering, zie Voeg de SignalR-clientbibliotheek toe.

Verbinding maken met een hub

Met de volgende code wordt een verbinding gemaakt en gestart. De naam van de hub is niet hoofdlettergevoelig:

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

async function start() {
    try {
        await connection.start();
        console.log("SignalR Connected.");
    } catch (err) {
        console.log(err);
        setTimeout(start, 5000);
    }
};

connection.onclose(async () => {
    await start();
});

// Start the connection.
start();

Cross-origin-verbindingen (CORS)

Normaal gesproken laden browsers verbindingen vanuit hetzelfde domein als de aangevraagde pagina. Er zijn echter situaties waarin een verbinding met een ander domein is vereist.

Bij het maken van aanvragen voor meerdere domeinen, moet de clientcode een absolute URL gebruiken in plaats van een relatieve URL. Voor aanvragen tussen domeinen wijzigt u .withUrl("/chathub") in .withUrl("https://{App domain name}/chathub").

Als u wilt voorkomen dat een kwaadwillende site gevoelige gegevens van een andere site leest, worden cross-origin-verbindingen standaard uitgeschakeld. Als u een cross-origin-aanvraag wilt toestaan, schakelt u CORSin:

using SignalRChat.Hubs;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(
        builder =>
        {
            builder.WithOrigins("https://example.com")
                .AllowAnyHeader()
                .WithMethods("GET", "POST")
                .AllowCredentials();
        });
});

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

// UseCors must be called before MapHub.
app.UseCors();

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

app.Run();

UseCors moet worden aangeroepen voordat u MapHubaanroept.

Hubmethoden aanroepen vanaf de client

JavaScript-clients roepen openbare methoden van hubs aan via de -methode van de HubConnection. De methode invoke accepteert:

• De naam van de hubmethode.
• Alle argumenten die zijn gedefinieerd in de hubmethode.

In de volgende gemarkeerde code is de naam van de methode op de hub SendMessage. De tweede en derde argumenten die zijn doorgegeven aan invoke komen overeen met de user- en message-argumenten van de hubmethode.

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

Hubmethoden aanroepen vanaf een client wordt alleen ondersteund wanneer u de Azure SignalR Service gebruikt in de modus Standaard. Zie Veelgestelde vragen (azure-signalr GitHub-opslagplaats)voor meer informatie.

De methode invoke retourneert een JavaScript-Promise. De Promise wordt opgelost met de retourwaarde (indien aanwezig) wanneer de methode vanaf de server retourneert. Als de methode op de server een fout genereert, wordt de Promise afgewezen met de foutmelding. Gebruik async en await of de Promisethen en catch methoden om deze gevallen af te handelen.

JavaScript-clients kunnen ook openbare methoden op hubs aanroepen via de methode van de HubConnection. In tegenstelling tot de methode invoke, wacht de send methode niet op een reactie van de server. De methode send retourneert een JavaScript-Promise. De Promise wordt opgelost wanneer het bericht naar de server is verzonden. Als er een fout optreedt bij het verzenden van het bericht, wordt de Promise geweigerd met het foutbericht. Gebruik async en await of de Promisethen en catch methoden om deze gevallen af te handelen.

Als u sendgebruikt, wordt er niet gewacht totdat de server het bericht heeft ontvangen. Daarom is het niet mogelijk om gegevens of fouten van de server te retourneren.

Clientmethoden aanroepen vanuit de hub

Als u berichten van de hub wilt ontvangen, definieert u een methode met behulp van de op methode van de HubConnection.

• De naam van de JavaScript-clientmethode.
• Argumenten die de hub doorgeeft aan de methode.

In het volgende voorbeeld is de methodenaam ReceiveMessage. De argumentnamen zijn user en message:

connection.on("ReceiveMessage", (user, message) => {
    const li = document.createElement("li");
    li.textContent = `${user}: ${message}`;
    document.getElementById("messageList").appendChild(li);
});

De voorgaande code in connection.on wordt uitgevoerd wanneer code aan de serverzijde deze aanroept met behulp van de methode SendAsync:

using Microsoft.AspNetCore.SignalR;
namespace SignalRChat.Hubs;

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

SignalR bepaalt welke clientmethode moet worden aangeroepen door de methodenaam en argumenten te vergelijken die zijn gedefinieerd in SendAsync en connection.on.

Een best practice is het aanroepen van de start methode op de HubConnection na on. Dit zorgt ervoor dat de handlers worden geregistreerd voordat berichten worden ontvangen.

Foutafhandeling en logboekregistratie

Gebruik console.error om fouten uit te voeren naar de console van de browser wanneer de client geen verbinding kan maken of een bericht kan verzenden:

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

Stel logboektracering aan de clientzijde in door een logboekregistratie en het type gebeurtenis door te geven dat moet worden geregistreerd wanneer de verbinding wordt gemaakt. Berichten worden geregistreerd met het opgegeven logboekniveau en hoger. De beschikbare logboekniveaus zijn als volgt:

• signalR.LogLevel.Error: foutberichten. Registreert alleen Error berichten.
• signalR.LogLevel.Warning: waarschuwingsberichten over mogelijke fouten. Registreert berichten Warningen Error.
• signalR.LogLevel.Information: statusberichten zonder fouten. Registreert Information, Warningen Error berichten.
• signalR.LogLevel.Trace: Berichten traceren. Registreert alles, inclusief gegevens die tussen hub en client worden vervoerd.

Gebruik de methode configureLogging op HubConnectionBuilder om het logboekniveau te configureren. Berichten worden vastgelegd in de browserconsole:

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

Clients opnieuw verbinden

Automatisch opnieuw verbinding maken

De JavaScript-client voor SignalR kan worden geconfigureerd om automatisch opnieuw verbinding te maken met behulp van de methode WithAutomaticReconnect op HubConnectionBuilder. Standaard wordt er niet automatisch opnieuw verbinding gemaakt.

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect()
    .build();

Zonder parameters configureert WithAutomaticReconnect de client respectievelijk 0, 2, 10 en 30 seconden te wachten voordat elke poging opnieuw wordt geprobeerd. Na vier mislukte pogingen stopt het met proberen opnieuw verbinding te maken.

Voordat u opnieuw verbinding probeert te maken, moet u ervoor zorgen dat de configuratie van het HubConnectioncorrect is ingesteld.

• Gaat over naar de HubConnectionState.Reconnecting status en activeert de onreconnecting callbacks.
• De overgang naar de Disconnected-status gebeurt niet en het activeert niet de onclose-callbacks, net als een HubConnection zonder automatische herverbinding geconfigureerd.

De benadering voor opnieuw verbinden biedt de volgende mogelijkheden:

• Waarschuw gebruikers dat de verbinding is verbroken.
• Schakel UI-elementen uit.

connection.onreconnecting(error => {
    console.assert(connection.state === signalR.HubConnectionState.Reconnecting);

    document.getElementById("messageInput").disabled = true;

    const li = document.createElement("li");
    li.textContent = `Connection lost due to error "${error}". Reconnecting.`;
    document.getElementById("messageList").appendChild(li);
});

Als de client opnieuw verbinding maakt binnen de eerste vier pogingen, wordt de HubConnection teruggezet naar de status van de Connected en worden de onreconnected callbacks geactiveerd. Dit biedt de mogelijkheid om gebruikers te informeren dat de verbinding opnieuw tot stand is gebracht.

Omdat de verbinding volledig nieuw lijkt voor de server, wordt een nieuwe connectionId verstrekt aan de onreconnected callback.

De connectionId parameter van de onreconnected callback is niet-gedefinieerde als de HubConnection is geconfigureerd om onderhandeling over te slaan.

connection.onreconnected(connectionId => {
    console.assert(connection.state === signalR.HubConnectionState.Connected);

    document.getElementById("messageInput").disabled = false;

    const li = document.createElement("li");
    li.textContent = `Connection reestablished. Connected with connectionId "${connectionId}".`;
    document.getElementById("messageList").appendChild(li);
});

withAutomaticReconnect configureert de HubConnection niet om initiële startfouten opnieuw uit te voeren. Startfouten moeten dus handmatig worden afgehandeld:

async function start() {
    try {
        await connection.start();
        console.assert(connection.state === signalR.HubConnectionState.Connected);
        console.log("SignalR Connected.");
    } catch (err) {
        console.assert(connection.state === signalR.HubConnectionState.Disconnected);
        console.log(err);
        setTimeout(() => start(), 5000);
    }
};

Als de client niet succesvol opnieuw verbinding maakt binnen de eerste vier pogingen, gaat de HubConnection over naar de Disconnected staat en worden de -callbacks geactiveerd. Dit biedt de mogelijkheid om gebruikers te informeren:

• De verbinding is permanent verloren gegaan.
• Probeer de pagina te vernieuwen:

connection.onclose(error => {
    console.assert(connection.state === signalR.HubConnectionState.Disconnected);

    document.getElementById("messageInput").disabled = true;

    const li = document.createElement("li");
    li.textContent = `Connection closed due to error "${error}". Try refreshing this page to restart the connection.`;
    document.getElementById("messageList").appendChild(li);
});

Als u een aangepast aantal nieuwe verbindingspogingen wilt configureren voordat u de tijdsinstellingen voor opnieuw verbinden verbreekt of wijzigt, accepteert withAutomaticReconnect een matrix met getallen die de vertraging in milliseconden vertegenwoordigen om te wachten voordat elke poging voor opnieuw verbinden wordt gestart.

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect([0, 0, 10000])
    .build();

    // .withAutomaticReconnect([0, 2000, 10000, 30000]) yields the default behavior

In het voorgaande voorbeeld wordt de HubConnection geconfigureerd om opnieuw verbinding te maken direct nadat de verbinding is verbroken. De standaardconfiguratie wacht ook op nul seconden om opnieuw verbinding te maken.

Als de eerste poging om opnieuw verbinding te maken mislukt, wordt de tweede poging om opnieuw verbinding te maken ook onmiddellijk gestart in plaats van 2 seconden te wachten met behulp van de standaardconfiguratie.

Als de tweede poging om opnieuw verbinding te maken mislukt, begint de derde poging om opnieuw verbinding te maken in 10 seconden, wat hetzelfde is als de standaardconfiguratie.

De geconfigureerde timing voor opnieuw verbinden wijkt af van het standaardgedrag door te stoppen na de fout met de derde poging om opnieuw verbinding te maken in plaats van een andere poging om opnieuw verbinding te maken in een andere 30 seconden.

Voor meer controle over de timing en het aantal automatische nieuwe verbindingspogingen accepteert withAutomaticReconnect een object dat de IRetryPolicy-interface implementeert, met één methode met de naam nextRetryDelayInMilliseconds.

nextRetryDelayInMilliseconds gebruikt één argument met het type RetryContext. De RetryContext heeft drie eigenschappen: previousRetryCount, elapsedMilliseconds en retryReason, wat respectievelijk een number, een number en een Error zijn. Voordat de eerste poging om opnieuw verbinding te maken, zijn zowel previousRetryCount als elapsedMilliseconds nul en is de retryReason de fout waardoor de verbinding is verbroken. Na elke mislukte herstelpoging wordt previousRetryCount met één verhoogd, elapsedMilliseconds wordt bijgewerkt om de hoeveelheid tijd in milliseconden die tot nu toe aan opnieuw verbinden is besteed weer te geven, en retryReason is de Fout die de laatste poging om opnieuw verbinding te maken heeft laten mislukken.

nextRetryDelayInMilliseconds moet een getal retourneren dat het aantal milliseconden aangeeft dat moet worden gewacht voordat de volgende poging tot opnieuw verbinding wordt gemaakt of null als de HubConnection moet stoppen met opnieuw verbinding maken.

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withAutomaticReconnect({
        nextRetryDelayInMilliseconds: retryContext => {
            if (retryContext.elapsedMilliseconds < 60000) {
                // If we've been reconnecting for less than 60 seconds so far,
                // wait between 0 and 10 seconds before the next reconnect attempt.
                return Math.random() * 10000;
            } else {
                // If we've been reconnecting for more than 60 seconds so far, stop reconnecting.
                return null;
            }
        }
    })
    .build();

Code kan ook worden geschreven waarmee de client handmatig opnieuw wordt verbonden, zoals wordt weergegeven in de volgende sectie.

Handmatig opnieuw verbinding maken

De volgende code demonstreert een typische benadering voor handmatig opnieuw verbinden:

1. Er wordt een functie (in dit geval de start functie) gemaakt om de verbinding te starten.
2. Roep de start functie aan in de onclose gebeurtenis-handler van de verbinding.

async function start() {
    try {
        await connection.start();
        console.log("SignalR Connected.");
    } catch (err) {
        console.log(err);
        setTimeout(start, 5000);
    }
};

connection.onclose(async () => {
    await start();
});

Productie-implementaties gebruiken doorgaans een exponentieel uitstel of proberen een opgegeven aantal keren opnieuw.

Tabblad Slaapstand van browser

Sommige browsers hebben een functie voor het blokkeren of slapen van tabbladen om het gebruik van computerbronnen voor inactieve tabbladen te verminderen. Hierdoor kunnen SignalR verbindingen worden gesloten en kan dit leiden tot een ongewenste gebruikerservaring. Browsers gebruiken heuristieken om erachter te komen of een tabblad in de slaapstand moet worden geplaatst, zoals:

• Audio afspelen
• Een webvergrendeling vasthouden
• Een IndexedDB slot vasthouden
• Verbinding maken met een USB-apparaat
• Video of audio vastleggen
• Wordt gespiegeld
• Een venster of weergave vastleggen

Browser-heuristiek kan na verloop van tijd veranderen en kan verschillen tussen browsers. Bekijk de ondersteuningsmatrix en zoek uit welke methode het beste werkt voor uw scenario's.

Om te voorkomen dat een app in de slaapstand wordt gezet, moet de app een van de heuristieken activeren die door de browser worden gebruikt.

In het volgende codevoorbeeld ziet u hoe u een webvergrendeling gebruikt om een tabblad wakker te houden en een onverwachte sluiting van de verbinding te voorkomen.

var lockResolver;
if (navigator && navigator.locks && navigator.locks.request) {
    const promise = new Promise((res) => {
        lockResolver = res;
    });

    navigator.locks.request('unique_lock_name', { mode: "shared" }, () => {
        return promise;
    });
}

Voor het voorgaande codevoorbeeld:

• Webvergrendelingen zijn experimenteel. De voorwaardelijke controle bevestigt dat de browser webvergrendelingen ondersteunt.
• De promise-afhandelaar, lockResolver, wordt opgeslagen zodat de vergrendeling kan worden vrijgegeven wanneer het tabblad in de slaapstand kan gaan.
• Wanneer u de verbinding sluit, wordt de vergrendeling vrijgegeven door lockResolver()aan te roepen. Wanneer de vergrendeling wordt losgelaten, kan het tabblad in de slaapstand gaan.

Aanvullende informatiebronnen

• Voorbeeldcode bekijken of downloaden (hoe te downloaden)
• JavaScript-API-verwijzing
• JavaScript-zelfstudie
• Handleiding WebPack en TypeScript
• Hubs
• .NET-client
• Publiceren op Azure
• Cross-Origin Requests (CORS)
• Serverloze documentatie van Azure Service SignalR
• Verbindingsproblemen oplossen