przewodnik interfejsu API usługi SignalR Hubs ASP.NET — klient JavaScript
Ostrzeżenie
Ta dokumentacja nie jest przeznaczona dla najnowszej wersji usługi SignalR. Przyjrzyj się ASP.NET Core SignalR.
Ten dokument zawiera wprowadzenie do korzystania z interfejsu API usługi Hubs dla usługi SignalR w wersji 2 w klientach JavaScript, takich jak przeglądarki i aplikacje ze Sklepu Windows (WinJS).
Interfejs API usługi SignalR Hubs umożliwia wykonywanie zdalnych wywołań procedur (RPCs) z serwera do połączonych klientów i klientów z serwerem. W kodzie serwera definiuje się metody, które mogą być wywoływane przez klientów, a metody uruchamiane na kliencie. W kodzie klienta zdefiniujesz metody, które mogą być wywoływane z serwera i wywołujesz metody uruchamiane na serwerze. Usługa SignalR zajmuje się wszystkimi instalacjami instalacyjnymi typu klient-serwer.
Usługa SignalR oferuje również interfejs API niższego poziomu o nazwie Połączenia trwałe. Aby zapoznać się z wprowadzeniem do usługi SignalR, koncentratorów i połączeń trwałych, zobacz Wprowadzenie do usługi SignalR.
Wersje oprogramowania używane w tym temacie
- Visual Studio 2017
- .NET 4.5
- SignalR w wersji 2
Poprzednie wersje tego tematu
Aby uzyskać informacje o wcześniejszych wersjach usługi SignalR, zobacz SignalR Older Versions (Starsze wersje usługi SignalR).
Pytania i komentarze
Prześlij opinię na temat tego, jak podoba ci się ten samouczek i co możemy poprawić w komentarzach w dolnej części strony. Jeśli masz pytania, które nie są bezpośrednio związane z samouczkiem, możesz opublikować je na forum ASP.NET SignalR lub StackOverflow.com.
Omówienie
Ten dokument zawiera następujące sekcje:
Aby uzyskać dokumentację dotyczącą programowania serwerów lub klientów platformy .NET, zobacz następujące zasoby:
- Przewodnik interfejsu API usługi SignalR Hubs — serwer
- Przewodnik interfejsu API usługi SignalR Hubs — klient platformy .NET
Składnik serwera SignalR 2 jest dostępny tylko na platformie .NET 4.5 (chociaż istnieje klient platformy .NET dla usługi SignalR 2 na platformie .NET 4.0).
Wygenerowany serwer proxy i co robi za Ciebie
Możesz programować klienta języka JavaScript w celu komunikowania się z usługą SignalR z serwerem proxy generowanym przez usługę SignalR lub bez serwera proxy generowanego przez usługę SignalR. Serwer proxy ułatwia składnię kodu używanego do łączenia, pisania metod wywoływanych przez serwer i wywoływania metod na serwerze.
Podczas pisania kodu w celu wywołania metod serwera wygenerowany serwer proxy umożliwia używanie składni wyglądającej tak, jakby wykonywano funkcję lokalną: możesz napisać serverMethod(arg1, arg2) zamiast invoke('serverMethod', arg1, arg2). Wygenerowana składnia serwera proxy umożliwia również natychmiastowy i zrozumiały błąd po stronie klienta, jeśli błędnie wpiszesz nazwę metody serwera. Jeśli utworzysz ręcznie plik, który definiuje serwery proxy, możesz również uzyskać obsługę funkcji IntelliSense na potrzeby pisania kodu wywołującego metody serwera.
Załóżmy na przykład, że na serwerze masz następującą klasę Hub:
public class ContosoChatHub : Hub
{
public void NewContosoChatMessage(string name, string message)
{
Clients.All.addContosoChatMessageToPage(name, message);
}
}
W poniższych przykładach kodu pokazano, jak wygląda kod JavaScript podczas wywoływania NewContosoChatMessage metody na serwerze i odbierania wywołań addContosoChatMessageToPage metody z serwera.
Za pomocą wygenerowanego serwera proxy
var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (name, message) {
console.log(name + ' ' + message);
};
$.connection.hub.start().done(function () {
// Wire up Send button to call NewContosoChatMessage on the server.
$('#newContosoChatMessage').click(function () {
contosoChatHubProxy.server.newContosoChatMessage($('#displayname').val(), $('#message').val());
$('#message').val('').focus();
});
});
Bez wygenerowanego serwera proxy
var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(name, message) {
console.log(name + ' ' + message);
});
connection.start().done(function() {
// Wire up Send button to call NewContosoChatMessage on the server.
$('#newContosoChatMessage').click(function () {
contosoChatHubProxy.invoke('newContosoChatMessage', $('#displayname').val(), $('#message').val());
$('#message').val('').focus();
});
});
Kiedy używać wygenerowanego serwera proxy
Jeśli chcesz zarejestrować wiele procedur obsługi zdarzeń dla metody klienta wywoływanej przez serwer, nie możesz użyć wygenerowanego serwera proxy. W przeciwnym razie możesz użyć wygenerowanego serwera proxy lub nie na podstawie preferencji kodowania. Jeśli nie chcesz jej używać, nie musisz odwoływać się do adresu URL "signalr/hubs" w elemencie script w kodzie klienta.
Konfiguracja klienta
Klient języka JavaScript wymaga odwołań do biblioteki jQuery i podstawowego pliku JavaScript usługi SignalR. Wersja jQuery musi być w wersji 1.6.4 lub nowszej, na przykład 1.7.2, 1.8.2 lub 1.9.1. Jeśli zdecydujesz się na użycie wygenerowanego serwera proxy, musisz również odwołać się do pliku JavaScript wygenerowanego serwera proxy usługi SignalR. W poniższym przykładzie pokazano, jak odwołania mogą wyglądać na stronie HTML korzystającej z wygenerowanego serwera proxy.
<script src="Scripts/jquery-1.10.2.min.js"></script>
<script src="Scripts/jquery.signalR-2.1.0.min.js"></script>
<script src="signalr/hubs"></script>
Te odwołania muszą być uwzględnione w tej kolejności: najpierw jQuery, rdzeń usługi SignalR po tym, a serwery proxy SignalR ostatnio.
Jak odwoływać się do dynamicznie wygenerowanego serwera proxy
W poprzednim przykładzie odwołaniem do wygenerowanego serwera proxy usługi SignalR jest dynamiczne generowanie kodu JavaScript, a nie do pliku fizycznego. Usługa SignalR tworzy kod JavaScript dla serwera proxy na bieżąco i udostępnia go klientowi w odpowiedzi na adres URL "/signalr/hubs". Jeśli określono inny podstawowy adres URL połączeń usługi SignalR na serwerze w metodzie MapSignalR , adres URL dynamicznie wygenerowanego pliku serwera proxy to niestandardowy adres URL z dołączonym do niego adresem URL "/hubs".
Uwaga
W przypadku klientów JavaScript systemu Windows 8 (Sklep Windows) użyj fizycznego pliku proxy zamiast dynamicznie wygenerowanego. Aby uzyskać więcej informacji, zobacz Jak utworzyć plik fizyczny dla serwera proxy wygenerowanego przez usługę SignalR w dalszej części tego tematu.
W widoku ASP.NET MVC 4 lub 5 Razor użyj tyldy, aby odwołać się do katalogu głównego aplikacji w dokumentacji pliku serwera proxy:
<script src="~/signalr/hubs"></script>
Aby uzyskać więcej informacji na temat używania usługi SignalR w programie MVC 5, zobacz Wprowadzenie z usługą SignalR i MVC 5.
W widoku ASP.NET MVC 3 Razor użyj odwołania Url.Content do pliku serwera proxy:
<script src="@Url.Content("~/signalr/hubs")"></script>
W aplikacji ASP.NET Web Forms użyj ResolveClientUrl odwołania do pliku proxy lub zarejestruj go za pomocą skryptu ScriptManager przy użyciu ścieżki względnej katalogu głównego aplikacji (począwszy od tyldy):
<script src='<%: ResolveClientUrl("~/signalr/hubs") %>'></script>
Ogólnie rzecz biorąc, użyj tej samej metody do określenia adresu URL "/signalr/hubs", który jest używany dla plików CSS lub JavaScript. Jeśli określisz adres URL bez użycia tyldy, w niektórych scenariuszach aplikacja będzie działać poprawnie podczas testowania w programie Visual Studio przy użyciu IIS Express, ale zakończy się niepowodzeniem z błędem 404 podczas wdrażania w pełnych usługach IIS. Aby uzyskać więcej informacji, zobacz Rozwiązywanie odwołań do zasobów Root-Level na serwerach sieci Web w programie Visual Studio dla projektów sieci Web ASP.NET w witrynie MSDN.
Po uruchomieniu projektu internetowego w programie Visual Studio 2017 w trybie debugowania, a jeśli używasz programu Internet Explorer jako przeglądarki, możesz zobaczyć plik serwera proxy w Eksplorator rozwiązań w obszarze Skrypty.
Aby wyświetlić zawartość pliku, kliknij dwukrotnie koncentratory. Jeśli nie używasz programu Visual Studio 2012 lub 2013 lub Internet Explorer lub nie korzystasz z trybu debugowania, możesz również uzyskać zawartość pliku, przechodząc do adresu URL "/signalR/hubs". Jeśli na przykład witryna jest uruchomiona pod adresem http://localhost:56699, przejdź do http://localhost:56699/SignalR/hubs witryny w przeglądarce.
Jak utworzyć plik fizyczny dla wygenerowanego serwera proxy usługi SignalR
Alternatywą dla dynamicznie wygenerowanego serwera proxy jest utworzenie pliku fizycznego zawierającego kod serwera proxy i odwołanie do tego pliku. Możesz to zrobić w celu kontrolowania zachowania buforowania lub tworzenia pakietów albo uzyskiwania funkcji IntelliSense podczas kodowania wywołań do metod serwera.
Aby utworzyć plik serwera proxy, wykonaj następujące kroki:
Zainstaluj pakiet NuGet Microsoft.AspNet.SignalR.Utils .
Otwórz wiersz polecenia i przejdź do folderu tools zawierającego plik SignalR.exe. Folder tools znajduje się w następującej lokalizacji:
[your solution folder]\packages\Microsoft.AspNet.SignalR.Utils.2.1.0\toolsWprowadź następujące polecenie:
signalr ghp /path:[path to the .dll that contains your Hub class]Ścieżka do .dll jest zazwyczaj folderem bin w folderze projektu.
To polecenie tworzy plik o nazwie server.js w tym samym folderze co signalr.exe.
Umieść plik server.js w odpowiednim folderze w projekcie, zmień jego nazwę odpowiednio dla aplikacji i dodaj do niego odwołanie zamiast odwołania "signalr/hubs".
Jak nawiązać połączenie
Przed nawiązaniem połączenia należy utworzyć obiekt połączenia, utworzyć serwer proxy i zarejestrować programy obsługi zdarzeń dla metod, które można wywołać z serwera. Po skonfigurowaniu procedur obsługi zdarzeń i serwera proxy należy nawiązać połączenie przez wywołanie start metody .
Jeśli używasz wygenerowanego serwera proxy, nie musisz tworzyć obiektu połączenia we własnym kodzie, ponieważ wygenerowany kod serwera proxy wykonuje go za Ciebie.
Nawiązywanie połączenia (z wygenerowanym serwerem proxy)
var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (name, message) {
console.log(userName + ' ' + message);
};
$.connection.hub.start()
.done(function(){ console.log('Now connected, connection ID=' + $.connection.hub.id); })
.fail(function(){ console.log('Could not Connect!'); });
Nawiązywanie połączenia (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(userName, message) {
console.log(userName + ' ' + message);
});
connection.start()
.done(function(){ console.log('Now connected, connection ID=' + connection.id); })
.fail(function(){ console.log('Could not connect'); });
Przykładowy kod używa domyślnego adresu URL "/signalr", aby nawiązać połączenie z usługą SignalR. Aby uzyskać informacje o sposobie określania innego podstawowego adresu URL, zobacz przewodnik interfejsu API usługi ASP.NET SignalR Hubs — serwer — adres URL /signalr.
Domyślnie lokalizacja centrum jest bieżącym serwerem; Jeśli łączysz się z innym serwerem, określ adres URL przed wywołaniem start metody, jak pokazano w poniższym przykładzie:
$.connection.hub.url = '<yourbackendurl>;
Uwaga
Zwykle programy obsługi zdarzeń są rejestrowane przed wywołaniem metody w start celu nawiązania połączenia. Jeśli chcesz zarejestrować niektóre programy obsługi zdarzeń po nawiązaniu połączenia, możesz to zrobić, ale przed wywołaniem start metody należy zarejestrować co najmniej jedną z procedur obsługi zdarzeń. Jednym z powodów tego jest to, że w aplikacji może istnieć wiele centrów, ale nie chcesz wyzwalać OnConnected zdarzenia w każdym centrum, jeśli zamierzasz używać go tylko do jednego z nich. Po nawiązaniu połączenia obecność metody klienta na serwerze proxy centrum jest tym, co nakazuje usłudze SignalR wyzwolenie OnConnected zdarzenia. Jeśli nie zarejestrujesz żadnych procedur obsługi zdarzeń przed wywołaniem start metody, będzie można wywołać metody w centrum, ale metoda centrum OnConnected nie zostanie wywołana, a żadne metody klienta nie będą wywoływane z serwera.
$.connection.hub jest tym samym obiektem, który tworzy $.hubConnection()
Jak widać w przykładach, gdy używasz wygenerowanego serwera proxy, $.connection.hub odnosi się do obiektu połączenia. Jest to ten sam obiekt, który otrzymujesz przez wywołanie, $.hubConnection() gdy nie używasz wygenerowanego serwera proxy. Wygenerowany kod serwera proxy tworzy połączenie, wykonując następującą instrukcję:
Jeśli używasz wygenerowanego serwera proxy, możesz wykonać dowolne czynności, $.connection.hub które można wykonać za pomocą obiektu połączenia, gdy nie używasz wygenerowanego serwera proxy.
Asynchroniczne wykonywanie metody start
Metoda start jest wykonywana asynchronicznie. Zwraca obiekt odroczony jQuery, co oznacza, że można dodać funkcje wywołania zwrotnego, wywołując metody takie jak pipe, donei fail. Jeśli masz kod, który chcesz wykonać po nawiązaniu połączenia, na przykład wywołanie metody serwera, umieść ten kod w funkcji wywołania zwrotnego lub wywołaj go z funkcji wywołania zwrotnego. Metoda .done wywołania zwrotnego jest wykonywana po nawiązaniu połączenia i po zakończeniu wykonywania dowolnego kodu w OnConnected metodzie obsługi zdarzeń na serwerze.
Jeśli umieścisz instrukcję "Teraz połączono" z poprzedniego przykładu jako następny wiersz kodu po start wywołaniu metody (nie w wywołaniu zwrotnym), console.log wiersz zostanie wykonany przed nawiązaniem .done połączenia, jak pokazano w poniższym przykładzie:
Jak ustanowić połączenie między domenami
Zazwyczaj jeśli przeglądarka ładuje stronę z http://contoso.comusługi , połączenie usługi SignalR znajduje się w tej samej domenie pod adresem http://contoso.com/signalr. Jeśli strona z http://contoso.com tworzy połączenie z http://fabrikam.com/signalrusługą , jest to połączenie między domenami. Ze względów bezpieczeństwa połączenia między domenami są domyślnie wyłączone.
W usłudze SignalR 1.x żądania między domenami były kontrolowane przez pojedynczą flagę EnableCrossDomain. Ta flaga kontroluje zarówno żądania JSONP, jak i CORS. Aby uzyskać większą elastyczność, obsługa mechanizmu CORS została usunięta ze składnika serwera usługi SignalR (klienci Języka JavaScript nadal używają mechanizmu CORS normalnie, jeśli zostanie wykryta, że przeglądarka ją obsługuje), a nowe oprogramowanie pośredniczące OWIN zostało udostępnione do obsługi tych scenariuszy.
Jeśli aplikacja JSONP jest wymagana na kliencie (aby obsługiwać żądania między domenami w starszych przeglądarkach), należy ją jawnie włączyć, ustawiając EnableJSONP obiekt na HubConfigurationtruewartość , jak pokazano poniżej. Protokół JSONP jest domyślnie wyłączony, ponieważ jest mniej bezpieczny niż MECHANIZM CORS.
Dodawanie aplikacji Microsoft.Owin.Cors do projektu: Aby zainstalować tę bibliotekę, uruchom następujące polecenie w konsoli Menedżera pakietów:
Install-Package Microsoft.Owin.Cors
To polecenie spowoduje dodanie do projektu wersji 2.1.0 pakietu.
Wywoływanie elementu UseCors
Poniższy fragment kodu przedstawia sposób implementowania połączeń między domenami w usłudze SignalR 2.
Implementowanie żądań między domenami w usłudze SignalR 2
Poniższy kod pokazuje, jak włączyć mechanizm CORS lub JSONP w projekcie SignalR 2. Ten przykładowy kod używa Map metody i RunSignalR zamiast MapSignalR, aby oprogramowanie pośredniczące CORS było uruchamiane tylko dla żądań signalR, które wymagają obsługi MECHANIZMU CORS (zamiast całego ruchu na ścieżce określonej w MapSignalR. Mapa może być również używana dla dowolnego innego oprogramowania pośredniczącego, które musi być uruchamiane dla określonego prefiksu adresu URL, a nie dla całej aplikacji.
using Microsoft.AspNet.SignalR;
using Microsoft.Owin.Cors;
using Owin;
namespace MyWebApplication
{
public class Startup
{
public void Configuration(IAppBuilder app)
{
// Branch the pipeline here for requests that start with "/signalr"
app.Map("/signalr", map =>
{
// Setup the CORS middleware to run before SignalR.
// By default this will allow all origins. You can
// configure the set of origins and/or http verbs by
// providing a cors options with a different policy.
map.UseCors(CorsOptions.AllowAll);
var hubConfiguration = new HubConfiguration
{
// You can enable JSONP by uncommenting line below.
// JSONP requests are insecure but some older browsers (and some
// versions of IE) require JSONP to work cross domain
// EnableJSONP = true
};
// Run the SignalR pipeline. We're not using MapSignalR
// since this branch already runs under the "/signalr"
// path.
map.RunSignalR(hubConfiguration);
});
}
}
}
Uwaga
Nie ustawiaj
jQuery.support.corswartości true w kodzie.
Usługa SignalR obsługuje użycie mechanizmu CORS. Ustawienie
jQuery.support.corswartości true powoduje wyłączenie protokołu JSONP, ponieważ powoduje, że usługa SignalR zakłada, że przeglądarka obsługuje mechanizm CORS.Podczas nawiązywania połączenia z adresem URL hosta lokalnego program Internet Explorer 10 nie rozważy połączenia między domenami, więc aplikacja będzie działać lokalnie z programem IE 10, nawet jeśli na serwerze nie włączono połączeń między domenami.
Aby uzyskać informacje o korzystaniu z połączeń między domenami w programie Internet Explorer 9, zobacz ten wątek StackOverflow.
Aby uzyskać informacje o korzystaniu z połączeń między domenami w przeglądarce Chrome, zobacz ten wątek StackOverflow.
Przykładowy kod używa domyślnego adresu URL "/signalr", aby nawiązać połączenie z usługą SignalR. Aby uzyskać informacje o sposobie określania innego podstawowego adresu URL, zobacz przewodnik interfejsu API usługi ASP.NET SignalR Hubs — serwer — adres URL /signalr.
Jak skonfigurować połączenie
Przed nawiązaniem połączenia można określić parametry parametrów zapytania lub określić metodę transportu.
Jak określić parametry ciągu zapytania
Jeśli chcesz wysłać dane do serwera po nawiązaniu połączenia z klientem, możesz dodać parametry parametrów zapytania do obiektu połączenia. W poniższych przykładach pokazano, jak ustawić parametr ciągu zapytania w kodzie klienta.
Ustaw wartość ciągu zapytania przed wywołaniem metody startowej (z wygenerowanym serwerem proxy)
$.connection.hub.qs = { 'version' : '1.0' };
Ustaw wartość ciągu zapytania przed wywołaniem metody startowej (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.qs = { 'version' : '1.0' };
W poniższym przykładzie pokazano, jak odczytać parametr ciągu zapytania w kodzie serwera.
public class ContosoChatHub : Hub
{
public override Task OnConnected()
{
var version = Context.QueryString['version'];
if (version != '1.0')
{
Clients.Caller.notifyWrongVersion();
}
return base.OnConnected();
}
}
Jak określić metodę transportu
W ramach procesu nawiązywania połączenia klient usługi SignalR zwykle negocjuje z serwerem, aby określić najlepszy transport obsługiwany przez zarówno serwer, jak i klienta. Jeśli wiesz już, którego transportu chcesz użyć, możesz pominąć ten proces negocjacji, określając metodę transportu podczas wywoływania start metody .
Kod klienta określający metodę transportu (z wygenerowanymi serwerami proxy)
$.connection.hub.start( { transport: 'longPolling' });
Kod klienta określający metodę transportu (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.start({ transport: 'longPolling' });
Alternatywnie można określić wiele metod transportu w kolejności, w której usługa SignalR ma je wypróbować:
Kod klienta określający niestandardowy schemat rezerwowy transportu (z wygenerowanym serwerem proxy)
$.connection.hub.start( { transport: ['webSockets', 'longPolling'] });
Kod klienta określający niestandardowy schemat rezerwowy transportu (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.start({ transport: ['webSockets', 'longPolling'] });
Do określenia metody transportu można użyć następujących wartości:
- "webSockets"
- "foreverFrame"
- "serverSentEvents"
- "longPolling"
W poniższych przykładach pokazano, jak dowiedzieć się, która metoda transportu jest używana przez połączenie.
Kod klienta, który wyświetla metodę transportu używaną przez połączenie (z wygenerowanym serwerem proxy)
$.connection.hub.start().done(function () {
console.log("Connected, transport = " + $.connection.hub.transport.name);
});
Kod klienta, który wyświetla metodę transportu używaną przez połączenie (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.hub.start().done(function () {
console.log("Connected, transport = " + connection.transport.name);
});
Aby uzyskać informacje o sposobie sprawdzania metody transportu w kodzie serwera, zobacz ASP.NET SignalR Hubs API Guide - Server — How to get information about the client from the Context property (Przewodnik po interfejsie API usługi SignalR Hubs — serwer — jak uzyskać informacje o kliencie z właściwości Context). Aby uzyskać więcej informacji na temat transportu i rezerwowych, zobacz Wprowadzenie do usługi SignalR — transporty i rezerwowe.
Jak uzyskać serwer proxy dla klasy Hub
Każdy obiekt połączenia tworzony hermetyzuje informacje o połączeniu z usługą SignalR, która zawiera co najmniej jedną klasę koncentratora. Aby komunikować się z klasą Hub, należy użyć obiektu proxy, który samodzielnie utworzysz (jeśli nie używasz wygenerowanego serwera proxy) lub który jest generowany dla Ciebie.
Na kliencie nazwa serwera proxy jest wielbłądową wersją nazwy klasy Hub. Usługa SignalR automatycznie wprowadza tę zmianę, aby kod JavaScript mógł być zgodny z konwencjami języka JavaScript.
Klasa koncentratora na serwerze
public class ContosoChatHub : Hub
Uzyskiwanie odwołania do wygenerowanego serwera proxy klienta dla centrum
var myHubProxy = $.connection.contosoChatHub
Tworzenie serwera proxy klienta dla klasy Hub (bez wygenerowanego serwera proxy)
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
Jeśli udekorujesz klasę Hub atrybutem, użyj dokładnej HubName nazwy bez zmiany wielkości liter.
Klasa koncentratora na serwerze z atrybutem HubName
[HubName("ContosoChatHub")]
public class ChatHub : Hub
Uzyskiwanie odwołania do wygenerowanego serwera proxy klienta dla centrum
var contosoChatHubProxy = $.connection.ContosoChatHub
Tworzenie serwera proxy klienta dla klasy Hub (bez wygenerowanego serwera proxy)
var contosoChatHubProxy = connection.createHubProxy('ContosoChatHub');
How to define methods on the client that the server can call (Jak zdefiniować metody na kliencie, który może wywołać serwer)
Aby zdefiniować metodę, którą serwer może wywołać z centrum, dodaj procedurę obsługi zdarzeń do serwera proxy centrum przy użyciu client właściwości wygenerowanego serwera proxy lub wywołaj on metodę, jeśli nie używasz wygenerowanego serwera proxy. Parametry mogą być obiektami złożonymi.
Dodaj procedurę obsługi zdarzeń przed wywołaniem metody w start celu nawiązania połączenia. (Jeśli chcesz dodać programy obsługi zdarzeń po wywołaniu start metody, zobacz notatkę w temacie Jak nawiązać połączenie wcześniej w tym dokumencie i użyć składni pokazanej do definiowania metody bez używania wygenerowanego serwera proxy).
Dopasowanie nazwy metody jest bez uwzględniania wielkości liter. Na przykład Clients.All.addContosoChatMessageToPage na serwerze zostanie wykonane AddContosoChatMessageToPagepolecenie , addContosoChatMessageToPagelub addcontosochatmessagetopage na kliencie.
Definiowanie metody na kliencie (przy użyciu wygenerowanego serwera proxy)
var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addContosoChatMessageToPage = function (userName, message) {
console.log(userName + ' ' + message);
};
$.connection.hub.start()
.done(function(){ console.log('Now connected, connection ID=' + $.connection.hub.id); })
.fail(function(){ console.log('Could not Connect!'); });
Alternatywny sposób definiowania metody na kliencie (przy użyciu wygenerowanego serwera proxy)
$.extend(contosoChatHubProxy.client, {
addContosoChatMessageToPage: function(userName, message) {
console.log(userName + ' ' + message);
};
});
Zdefiniuj metodę na kliencie (bez wygenerowanego serwera proxy lub podczas dodawania po wywołaniu metody startowej)
var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
contosoChatHubProxy.on('addContosoChatMessageToPage', function(userName, message) {
console.log(userName + ' ' + message);
});
connection.start()
.done(function(){ console.log('Now connected, connection ID=' + connection.id); })
.fail(function(){ console.log('Could not connect'); });
Kod serwera, który wywołuje metodę klienta
public class ContosoChatHub : Hub
{
public void NewContosoChatMessage(string name, string message)
{
Clients.All.addContosoChatMessageToPage(name, message);
}
}
Poniższe przykłady obejmują złożony obiekt jako parametr metody.
Zdefiniuj metodę na kliencie, który przyjmuje obiekt złożony (z wygenerowanym serwerem proxy)
var contosoChatHubProxy = $.connection.contosoChatHub;
contosoChatHubProxy.client.addMessageToPage = function (message) {
console.log(message.UserName + ' ' + message.Message);
});
Zdefiniuj metodę na kliencie, który przyjmuje obiekt złożony (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
var contosoChatHubProxy = connection.createHubProxy('contosoChatHub');
chatHubProxy.on('addMessageToPage', function (message) {
console.log(message.UserName + ' ' + message.Message);
});
Kod serwera definiujący obiekt złożony
public class ContosoChatMessage
{
public string UserName { get; set; }
public string Message { get; set; }
}
Kod serwera, który wywołuje metodę klienta przy użyciu obiektu złożonego
public void SendMessage(string name, string message)
{
Clients.All.addContosoChatMessageToPage(new ContosoChatMessage() { UserName = name, Message = message });
}
Jak wywoływać metody serwera z klienta
Aby wywołać metodę serwera od klienta, użyj server właściwości wygenerowanego serwera proxy lub invoke metody na serwerze proxy centrum, jeśli nie używasz wygenerowanego serwera proxy. Zwracana wartość lub parametry mogą być obiektami złożonymi.
Przekaż wersję camel-case nazwy metody w centrum. Usługa SignalR automatycznie wprowadza tę zmianę, aby kod JavaScript mógł być zgodny z konwencjami języka JavaScript.
W poniższych przykładach pokazano, jak wywołać metodę serwera, która nie ma wartości zwracanej i jak wywołać metodę serwera, która ma zwracaną wartość.
Metoda serwera bez atrybutu HubMethodName
public class ContosoChatHub : Hub
{
public void NewContosoChatMessage(ChatMessage message)
{
Clients.All.addContosoChatMessageToPage(message);
}
}
Kod serwera definiujący obiekt złożony przekazany w parametrze
public class ChatMessage
{
public string UserName { get; set; }
public string Message { get; set; }
}
Kod klienta, który wywołuje metodę serwera (z wygenerowany serwer proxy)
contosoChatHubProxy.server.newContosoChatMessage({ UserName: userName, Message: message}).done(function () {
console.log ('Invocation of NewContosoChatMessage succeeded');
}).fail(function (error) {
console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
});
Kod klienta, który wywołuje metodę serwera (bez wygenerowanego serwera proxy)
contosoChatHubProxy.invoke('newContosoChatMessage', { UserName: userName, Message: message}).done(function () {
console.log ('Invocation of NewContosoChatMessage succeeded');
}).fail(function (error) {
console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
});
Jeśli metoda Hub została ozdobiona atrybutem HubMethodName , użyj tej nazwy bez zmiany wielkości liter.
Metoda serwera z atrybutem HubMethodName
public class ContosoChatHub : Hub
{
[HubMethodName("NewContosoChatMessage")]
public void NewContosoChatMessage(string name, string message)
{
Clients.All.addContosoChatMessageToPage(name, message);
}
}
Kod klienta, który wywołuje metodę serwera (z wygenerowany serwer proxy)
contosoChatHubProxy.server.NewContosoChatMessage(userName, message).done(function () {
console.log ('Invocation of NewContosoChatMessage succeeded');
}).fail(function (error) {
console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
});
Kod klienta, który wywołuje metodę serwera (bez wygenerowanego serwera proxy)
contosoChatHubProxy.invoke('NewContosoChatMessage', userName, message).done(function () {
console.log ('Invocation of NewContosoChatMessage succeeded');
}).fail(function (error) {
console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
});
W powyższych przykładach pokazano, jak wywołać metodę serwera, która nie ma wartości zwracanej. W poniższych przykładach pokazano, jak wywołać metodę serwera, która ma wartość zwracaną.
Kod serwera dla metody, która ma wartość zwracaną
public class StockTickerHub : Hub
{
public IEnumerable<Stock> GetAllStocks()
{
return _stockTicker.GetAllStocks();
}
}
Klasa Stock używana dla wartości zwracanej
public class Stock
{
public string Symbol { get; set; }
public decimal Price { get; set; }
}
Kod klienta, który wywołuje metodę serwera (z wygenerowany serwer proxy)
function init() {
return stockTickerProxy.server.getAllStocks().done(function (stocks) {
$.each(stocks, function () {
var stock = this;
console.log("Symbol=" + stock.Symbol + " Price=" + stock.Price);
});
}).fail(function (error) {
console.log('Error: ' + error);
});
}
Kod klienta, który wywołuje metodę serwera (bez wygenerowanego serwera proxy)
function init() {
return stockTickerProxy.invoke('getAllStocks').done(function (stocks) {
$.each(stocks, function () {
var stock = this;
console.log("Symbol=" + stock.Symbol + " Price=" + stock.Price);
});
}).fail(function (error) {
console.log('Error: ' + error);
});
}
Jak obsługiwać zdarzenia okresu istnienia połączenia
Usługa SignalR udostępnia następujące zdarzenia okresu istnienia połączenia, które można obsłużyć:
starting: Zgłaszane przed wysłaniem jakichkolwiek danych za pośrednictwem połączenia.received: zgłaszane, gdy wszystkie dane są odbierane w połączeniu. Dostarcza odebrane dane.connectionSlow: zgłaszane, gdy klient wykryje wolne lub często porzucanie połączenia.reconnecting: podniesione, gdy podstawowy transport rozpoczyna ponowne nawiązywanie połączenia.reconnected: podniesione, gdy podstawowy transport został ponownie połączony.stateChanged: Zgłaszane, gdy zmieni się stan połączenia. Zapewnia stary stan i nowy stan (Łączenie, Podłączanie, ponowne nawiązywanie połączenia lub Rozłączenie).disconnected: zgłaszane, gdy połączenie zostało rozłączone.
Jeśli na przykład chcesz wyświetlić komunikaty ostrzegawcze, gdy występują problemy z połączeniem, które mogą powodować zauważalne opóźnienia, obsłuż zdarzenie connectionSlow .
Obsługa zdarzenia connectionSlow (z wygenerowanymi serwerami proxy)
$.connection.hub.connectionSlow(function () {
console.log('We are currently experiencing difficulties with the connection.')
});
Obsługa zdarzenia connectionSlow (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.connectionSlow(function () {
console.log('We are currently experiencing difficulties with the connection.')
});
Aby uzyskać więcej informacji, zobacz Opis i obsługa zdarzeń okresu istnienia połączenia w usłudze SignalR.
Jak obsługiwać błędy
Klient Języka JavaScript usługi SignalR udostępnia error zdarzenie, dla którego można dodać procedurę obsługi. Można również użyć metody fail, aby dodać procedurę obsługi błędów, które wynikają z wywołania metody serwera.
Jeśli nie włączysz jawnie szczegółowych komunikatów o błędach na serwerze, obiekt wyjątku zwracany przez usługę SignalR po błędzie zawiera minimalne informacje o błędzie. Na przykład jeśli wywołanie nie newContosoChatMessage powiedzie się, komunikat o błędzie w obiekcie błędu zawiera "There was an error invoking Hub method 'contosoChatHub.newContosoChatMessage'." Wysyłanie szczegółowych komunikatów o błędach do klientów w środowisku produkcyjnym nie jest zalecane ze względów bezpieczeństwa, ale jeśli chcesz włączyć szczegółowe komunikaty o błędach na potrzeby rozwiązywania problemów, użyj następującego kodu na serwerze.
var hubConfiguration = new HubConfiguration();
hubConfiguration.EnableDetailedErrors = true;
app.MapSignalR(hubConfiguration);
W poniższym przykładzie pokazano, jak dodać procedurę obsługi dla zdarzenia błędu.
Dodawanie procedury obsługi błędów (z wygenerowanym serwerem proxy)
$.connection.hub.error(function (error) {
console.log('SignalR error: ' + error)
});
Dodawanie procedury obsługi błędów (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.error(function (error) {
console.log('SignalR error: ' + error)
});
W poniższym przykładzie pokazano, jak obsłużyć błąd wywołania metody.
Obsługa błędu z wywołania metody (z wygenerowanym serwerem proxy)
contosoChatHubProxy.newContosoChatMessage(userName, message)
.fail(function(error) {
console.log( 'newContosoChatMessage error: ' + error)
});
Obsługa błędu wywołania metody (bez wygenerowanego serwera proxy)
contosoChatHubProxy.invoke('newContosoChatMessage', userName, message)
.fail(function(error) {
console.log( 'newContosoChatMessage error: ' + error)
});
Jeśli wywołanie metody zakończy się niepowodzeniem, error zostanie również zgłoszone zdarzenie, więc kod w error procedurze obsługi metody i wywołanie .fail zwrotne metody zostanie wykonane.
Jak włączyć rejestrowanie po stronie klienta
Aby włączyć rejestrowanie po stronie klienta w połączeniu, ustaw logging właściwość obiektu połączenia przed wywołaniem start metody w celu nawiązania połączenia.
Włączanie rejestrowania (przy użyciu wygenerowanego serwera proxy)
$.connection.hub.logging = true;
$.connection.hub.start();
Włączanie rejestrowania (bez wygenerowanego serwera proxy)
var connection = $.hubConnection();
connection.logging = true;
connection.start();
Aby wyświetlić dzienniki, otwórz narzędzia deweloperskie przeglądarki i przejdź do karty Konsola. Aby zapoznać się z samouczkiem przedstawiającym instrukcje krok po kroku i zrzuty ekranu pokazujące, jak to zrobić, zobacz Server Broadcast with ASP.NET Signalr - Enable Logging (Emisja serwera za pomocą usługi Signalr — włączanie rejestrowania).
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla