ASP.NET Core SignalR JavaScriptový klient

Od Rachel Appel

SignalRklientská knihovna ASP.NET Core JavaScript umožňuje vývojářům volat kód centra na straně serveru.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Instalace SignalR balíčku klienta

SignalRKlientská knihovna JavaScriptu je dodávána jako balíček npm . Následující oddíly popisují různé způsoby instalace klientské knihovny.

Instalace pomocí npm

v případě Visual Studio v kořenové složce spusťte následující příkazy z Správce balíčků Console . pro Visual Studio Code spusťte následující příkazy z integrovaného terminálu.

npm init -y
npm install @microsoft/signalr

NPM nainstaluje obsah balíčku do složky *node_modules \ @microsoft\signalr\dist\browser* . Vytvořte novou složku s názvem Signal ve složce wwwroot \ lib . Zkopírujte soubor signalr.js do složky wwwroot\lib\signalr .

Odkazování na SignalR klienta JavaScriptu v <script> elementu. Příklad:

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

použít Content Delivery Network (CDN)

chcete-li použít klientskou knihovnu bez npm požadavků, odkazujte na CDN hostovanou kopii klientské knihovny. Příklad:

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

Klientská knihovna je k dispozici na následujících sítě CDN:

• cdnjs
• jsDelivr
• unpkg

Instalace pomocí LibMan

LibMan se dá použít k instalaci určitých souborů knihovny klienta z klientské knihovny hostované v CDN. Například do projektu přidejte pouze soubor JavaScriptu minifikovaného. Podrobnosti o tomto přístupu najdete v tématu Přidání SignalR klientské knihovny.

Připojení do centra

Následující kód vytvoří a spustí připojení. V názvu centra se nerozlišují malá a velká písmena:

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

Připojení mezi zdroji

Prohlížeče obvykle načítají připojení ze stejné domény jako požadovanou stránku. Existují však situace, kdy je vyžadováno připojení k jiné doméně.

Chcete-li zabránit škodlivému webu v čtení citlivých dat z jiné lokality, připojení mezi zdroji jsou ve výchozím nastavení zakázána. Pokud chcete povolit žádost o více zdrojů, povolte ji ve Startup třídě:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SignalRChat.Hubs;

namespace SignalRChat
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddSignalR();

            services.AddCors(options =>
            {
                options.AddDefaultPolicy(builder =>
                {
                    builder.WithOrigins("https://example.com")
                        .AllowCredentials();
                });
            });
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
            }

            app.UseStaticFiles();
            app.UseRouting();

            app.UseCors();

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

Volání metod centra z klienta

Klienti JavaScriptu volají veřejné metody na rozbočovačích prostřednictvím metody Invoke HubConnection. invokeMetoda akceptuje:

• Název metody centra
• Jakékoli argumenty definované v metodě hub.

V následujícím příkladu je název metody v centru SendMessage . Druhý a třetí argument předaný k invoke mapování na metody user a message argumenty centra:

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

invokeMetoda vrací příslibJavaScriptu. PromiseJe vyřešen s návratovou hodnotou (pokud existuje), když metoda na serveru vrátí. Pokud metoda na serveru vyvolá chybu, bude Promise zpráva odmítnuta s chybovou zprávou. Použijte async await metody a nebo Promise then a catch ke zpracování těchto případů.

Klienti JavaScriptu můžou také volat veřejné metody na rozbočovače prostřednictvím metody Send objektu HubConnection . Na rozdíl od invoke metody send Metoda nečeká na odpověď ze serveru. sendMetoda vrátí JavaScript Promise . PromiseJe vyřešena při odeslání zprávy na server. Pokud při odesílání zprávy dojde k chybě, bude Promise zpráva odmítnuta s chybovou zprávou. Použijte async await metody a nebo Promise then a catch ke zpracování těchto případů.

Volání metod klienta z centra

Chcete-li přijímat zprávy z centra, definujte metodu pomocí metody on HubConnection .

• Název metody klienta jazyka JavaScript.
• Argumenty, které rozbočovač předává metodě.

V následujícím příkladu je název metody ReceiveMessage . Názvy argumentů jsou user a message :

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

Předchozí kód v aplikaci se connection.on spustí, když kód na straně serveru volá SendAsync metodu:

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

SignalR Určuje, která metoda klienta má být volána, a to tak, že odpovídá názvu metody a argumentům definovaným v SendAsync a connection.on .

Zpracování chyb a protokolování

try catch async await Promise catch Pro zpracování chyb na straně klienta použijte metody a a nebo. Slouží console.error k výstupu chyb do konzoly prohlížeče:

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

Nastavte trasování protokolu na straně klienta předáním protokolovacího nástroje a typu události, které se mají protokolovat při navázání spojení. Zprávy jsou protokolovány se zadanou úrovní protokolu a vyšší. K dispozici jsou následující úrovně protokolu:

• signalR.LogLevel.Error: Chybové zprávy. Protokoluje Error pouze zprávy.
• signalR.LogLevel.Warning: Varovné zprávy o potenciálních chybách. Protokoly Warning a Error zprávy.
• signalR.LogLevel.Information: Stavové zprávy bez chyb. Protokoly Information , Warning a Error zprávy.
• signalR.LogLevel.Trace: Trace Messages. Zaznamená vše, včetně dat přepravovaných mezi centrem a klientem.

K nakonfigurování úrovně protokolu použijte metodu configureLogging pro HubConnectionBuilder . Zprávy jsou protokolovány do konzoly prohlížeče:

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

Znovu připojit klienty

Automaticky znovu připojit

Klient jazyka JavaScript pro SignalR lze nakonfigurovat tak, aby se automaticky znovu připojil pomocí withAutomaticReconnect metody v HubConnectionBuilder. Ve výchozím nastavení se automaticky znovu nepřipojí.

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

Bez parametrů withAutomaticReconnect() nakonfiguruje klienta, aby čekal na 0, 2, 10 a 30 sekund, než se pokusí o každý pokus o opětovné připojení, který se zastaví po čtyřech pokusech o selhání.

Před zahájením jakýchkoli pokusů o opětovné připojení HubConnection přejdete do HubConnectionState.Reconnecting stavu a dojde k jeho onreconnecting zpětnému volání namísto přechodu do Disconnected stavu a aktivaci jeho onclose zpětného volání, jako je třeba HubConnection automatické opětovné připojení. Díky tomu můžete uživatelům upozornit, že připojení bylo ztraceno, a zakázat prvky uživatelského rozhraní.

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("messagesList").appendChild(li);
});

Pokud se klient úspěšně znovu připojí během prvních čtyř pokusů, převede se HubConnection zpátky do Connected stavu a spustí zpětná onreconnected volání. To vám umožní informovat uživatele o tom, že bylo připojení znovu navázáno.

Vzhledem k tomu, že připojení na serveru zcela začíná, connectionId bude zpětnému volání k dispozici nový onreconnected .

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("messagesList").appendChild(li);
});

withAutomaticReconnect() neprovede konfiguraci HubConnection pro opakování počátečního spuštění, takže chyby spuštění je nutné zpracovat ručně:

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

Pokud se klient úspěšně znovu nepřipojí během prvních čtyř pokusů, HubConnection přejde do Disconnected stavu a aktivuje jeho zpětné volání při jeho ukončení . To vám umožní informovat uživatele o trvalé ztrátě připojení a doporučit aktualizaci stránky:

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("messagesList").appendChild(li);
});

Aby bylo možné nakonfigurovat vlastní počet pokusů o opětovné připojení před odpojením nebo změnou časování pro opětovné připojení, withAutomaticReconnect přijme pole čísel představující zpoždění v milisekundách, které se má počkat, než se spustí pokus o opětovné připojení.

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

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

Předchozí příklad nakonfiguruje , aby se ihned po ztrátě připojení začal pokoušet HubConnection o opětovné připojení. To platí i pro výchozí konfiguraci.

Pokud první pokus o opětovné připojení selže, druhý pokus o opětovné připojení se také spustí okamžitě místo čekání na 2 sekundy, jako by byl ve výchozí konfiguraci.

Pokud druhý pokus o opětovné připojení selže, třetí pokus o opětovné připojení se spustí za 10 sekund, což je opět jako výchozí konfigurace.

Vlastní chování se pak znovu odchýlí od výchozího chování tím, že se zastaví po selhání třetího pokusu o opětovné připojení namísto pokusu o další pokus o opětovné připojení za dalších 30 sekund, jako by to bylo ve výchozí konfiguraci.

Pokud chcete mít ještě větší kontrolu nad načasováním a počtem pokusů o automatické opětovné připojení, přijme objekt implementující rozhraní, které má jednu metodu withAutomaticReconnect IRetryPolicy s názvem nextRetryDelayInMilliseconds .

nextRetryDelayInMilliseconds přebírá jeden argument s typem RetryContext . Má RetryContext tři vlastnosti: previousRetryCount a , které jsou , a a v uvedeném elapsedMilliseconds retryReason number number Error pořadí. Před prvním pokusem o opětovné připojení bude hodnota i nulová a hodnota bude chyba, která způsobila previousRetryCount elapsedMilliseconds retryReason ztrátu připojení. Po každém neúspěšným pokusu o opakování se zvýší o jeden pokus, aktualizuje se tak, aby odrážel dobu strávenou opětovným připojením v milisekundách, a hodnota bude Chyba, která způsobila selhání posledního pokusu o opětovné previousRetryCount elapsedMilliseconds retryReason připojení.

nextRetryDelayInMilliseconds musí vrátit buď číslo představující počet milisekund, které se má čekat před dalším pokusem o opětovné připojení, nebo jestli by se mělo zastavit null HubConnection opětovné připojení.

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

Alternativně můžete napsat kód, který znovu připojí vašeho klienta ručně, jak je znázorněno v části Ruční opětovné připojení.

Ruční opětovné připojení

Následující kód ukazuje typický přístup k ručnímu opětovnému připojení:

1. Vytvoří se funkce (v tomto případě funkce) pro start spuštění připojení.
2. Volejte start funkci v obslužné rutině události onclose připojení.

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

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

Produkční implementace obvykle používají exponenciální omezení nebo opakování po zadaném počtu opakování.

Karta v prohlížeči v spánku

Některé prohlížeče mají funkci zamrznutí nebo uschnutí tabulátoru, která snižuje využití prostředků počítače pro neaktivní karty. To může způsobit SignalR ukončení připojení a může vést k nežádoucímu uživatelskému prostředí. Prohlížeče používají heuristika ke zjistování, jestli by měla být karta v režimu spánku, například:

• Přehrávání zvuku
• Podržíte webový zámek.
• Podržením IndexedDB zámku
• Připojení k zařízení USB
• Zachytávání videa nebo zvuku
• Zrcadlení
• Zachycení okna nebo zobrazení

Aby se aplikace nespouštěla do režimu spánku, měla by aktivovat jednu z heuristických metod, které prohlížeč používá.

Následující příklad kódu ukazuje, jak pomocí webového zámku udržet kartu v neschování a vyhnout se neočekávanému ukončení připojení.

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

Pro předchozí příklad kódu:

• Zámky webu jsou experimentální. Podmíněná kontrola potvrzuje, že prohlížeč podporuje webové zámky.
• Překladač příslibů ( ) je uložený tak, aby zámek mohl být uvolněn, když je přijatelné, aby lockResolver karta usnula.
• Při zavírání připojení se zámek uvolní voláním lockResolver() . Po uvolnění zámku může karta usnout.

Další zdroje informací

• Referenční dokumentace k rozhraní API v JavaScriptu
• Kurz k JavaScriptu
• Kurz k WebPacku a TypeScriptu
• Centra
• Klient .NET
• Publikování do Azure
• Požadavky mezi zdroji (CORS)
• Dokumentace ke službě Azure SignalR Service bez serveru
• Řešení chyb připojení

Od Pomíl Appel

Klientská ASP.NET Core JavaScript umožňuje vývojářům SignalR volat kód centra na straně serveru.

Zobrazení nebo stažení ukázkového kódu (stažení)

Instalace SignalR balíčku klienta

Javascriptová SignalR klientská knihovna se dodává jako balíček npm. Následující části popisují různé způsoby instalace klientské knihovny.

Instalace pomocí npm

Pokud používáte Visual Studio, spusťte následující příkazy z konzoly Správce balíčků v kořenové složce. Pokud Visual Studio Code, spusťte následující příkazy z integrovaného terminálu.

npm init -y
npm install @aspnet/signalr

npm nainstaluje obsah balíčku do *node_modules \ @aspnet\signalr\dist\browser* složky. Ve složce wwwroot \ lib vytvořte novou složku signalr. Zkopírujte signalr.js do složky wwwroot\lib\signalr.

Odkazovat SignalR na javascriptového klienta v <script> elementu . Příklad:

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

Použití Content Delivery Network (CDN)

Pokud chcete použít klientskou knihovnu bez předpokladu npm, CDN kopii klientské knihovny hostovanou klientskou knihovnou. Příklad:

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

Klientská knihovna je dostupná v následujících sítích CDN:

• cdnjs
• jsDelivr
• unpkg

Instalace pomocí nástroje LibMan

LibMan lze použít k instalaci konkrétních souborů klientské knihovny z CDN hostované klientské knihovny. Například přidejte do projektu pouze minifikovaný javascriptový soubor. Podrobnosti o tomto přístupu najdete v tématu Přidání SignalR klientské knihovny.

Připojení k centru

Následující kód vytvoří a spustí připojení. V názvu centra se velká a malá písmena nelišují.

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

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

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

// Start the connection.
start();

/* this is here to show an alternative to start, with a then
connection.start().then(() => console.log("connected"));
*/

/* this is here to show another alternative to start, with a catch
connection.start().catch(err => console.error(err));
*/

Připojení mezi zdroji

Prohlížeče obvykle načítá připojení ze stejné domény jako požadovaná stránka. Existují však situace, kdy se vyžaduje připojení k jiné doméně.

Aby škodlivý web nečetl citlivá data z jiné lokality, jsou připojení mezi zdroji ve výchozím nastavení zakázaná. Pokud chcete povolit požadavek mezi zdroji, povolte ho ve Startup třídě .

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SignalRChat.Hubs;

namespace SignalRChat
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });

            services.AddMvc();

            services.AddCors(options => options.AddPolicy("CorsPolicy", 
            builder => 
            {
                builder.AllowAnyMethod().AllowAnyHeader()
                       .WithOrigins("http://localhost:55830")
                       .AllowCredentials();
            }));

            services.AddSignalR();
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseBrowserLink();
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
            app.UseCors("CorsPolicy");
            app.UseSignalR(routes => 
            {
                routes.MapHub<ChatHub>("/chathub");
            });
            app.UseMvc();            
        }
    }
}

Volání metod centra z klienta

Klienti JavaScriptu volají veřejné metody v centrech prostřednictvím metody invoke třídy HubConnection. Metoda invoke přijímá dva argumenty:

• Název metody centra. V následujícím příkladu je název metody v centru SendMessage .

• Všechny argumenty definované v metodě centra. V následujícím příkladu je název argumentu message . Příklad kódu používá syntaxi funkce šipky, která je podporována v aktuálních verzích všech hlavních prohlížečů s výjimkou Internet Explorer.

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

Metoda invoke vrátí příslib JavaScriptu. Metoda se po vrácení metody na serveru vyřeší vrácenou Promise hodnotou (pokud existuje). Pokud metoda na serveru vyvolá chybu, metoda Promise se zamítne s chybovou zprávou. Ke zpracování těchto případů (nebo syntaxe) použijte metody then catch a na Promise await samotném objektu .

Metoda send vrátí JavaScript Promise . Se Promise vyřeší, když se zpráva odeslala na server. Pokud při odesílání zprávy dojde k chybě, Promise zamítne se s chybovou zprávou. Ke zpracování těchto případů (nebo syntaxe) použijte metody then catch a na Promise await samotném objektu .

Volání klientských metod z centra

Pokud chcete přijímat zprávy z centra, definujte metodu pomocí metody on třídy HubConnection .

• Název javascriptové klientské metody. V následujícím příkladu má metoda název ReceiveMessage .
• Argumenty, které centrum předává metodě . V následujícím příkladu je hodnota argumentu message .

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

Předchozí kód v se spustí, když ho kód na straně serveru connection.on zavolá pomocí SendAsync metody .

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

SignalR určuje, která klientská metoda se má volat, podle názvu metody a argumentů definovaných v a SendAsync connection.on .

Zpracování chyb a protokolování

catchZřetězte metodu na konec start metody pro zpracování chyb na straně klienta. Slouží console.error k výstupu chyb do konzoly prohlížeče.

connection.start().catch(err => console.error(err));

Nastavte trasování protokolu na straně klienta tak, že předáte protokolovací nástroj a typ události do protokolu při připojení. Zprávy jsou protokolovány se zadanou úrovní protokolu a vyšší. Dostupné úrovně protokolu jsou následující:

• signalR.LogLevel.Error: Chybové zprávy. Protokoluje Error pouze zprávy.
• signalR.LogLevel.Warning: Upozorní vás na potenciální chyby. Protokoly Warning a Error zprávy.
• signalR.LogLevel.Information: Stavové zprávy bez chyb. Protokoly Information Warning , a Error zprávy.
• signalR.LogLevel.Trace: Trasovací zprávy. Protokoluje všechno, včetně dat transportovaných mezi centrem a klientem.

Ke konfiguraci úrovně protokolu použijte metodu configureLogging v HubConnectionBuilder. Zprávy jsou protokolovány do konzoly prohlížeče.

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

Opětovné připojení klientů

Ruční opětovné připojení

Následující kód ukazuje typický přístup k ručnímu opětovnému připojení:

1. Vytvoří se funkce (v tomto případě funkce) pro start spuštění připojení.
2. Volejte start funkci v obslužné rutině události onclose připojení.

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

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

Implementace z reálného světa by před tím, než se zřeknou, použije exponenciální omezení nebo zkusí zadaný počet opakování.

Další zdroje informací

• Referenční dokumentace k rozhraní API v JavaScriptu
• Kurz k JavaScriptu
• Kurz k WebPacku a TypeScriptu
• Centra
• Klient .NET
• Publikování do Azure
• Požadavky mezi zdroji (CORS)
• Dokumentace ke službě Azure SignalR Service bez serveru